Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 34 additions & 27 deletions docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,9 +425,9 @@ session-peer send --host mac --to 'codex:<full-thread-uuid>' \

Omit `--host mac` for local use. Remove `--dry-run` only when ready to submit.
Quoting `~` keeps expansion on the destination; an absolute remote path also
works. `--codex-home` explicitly chooses that copy but is not proof of activity.
This explicit-home form also works with releases that predate active-writer
resolution.
works. Current releases treat `--codex-home` as a destination constraint and
still validate every matching known home's writer evidence. Older releases
accept the explicit-home syntax but do not provide this safety guarantee.

The duplicate-home rejection baseline shipped in v0.6.1. The active-writer
selection, revalidation, and detailed `codexHomeResolution` evidence described
Expand All @@ -451,28 +451,35 @@ forwarded by `--host`. On Windows, use absolute Windows paths with backslashes
escaped as required by JSON. Empty configuration arrays are allowed; malformed
configuration is an error for implicit sends.

If the UUID occurs in multiple known homes, session-peer examines the exact
`thread-writer-locks/<uuid>.lock` in each matching home. It independently probes
the kernel advisory lock and correlates the opener through two stable `lsof`
observations. Exactly one stable, same-user Codex writer selects that home; the
evidence is checked again immediately before queue submission. A free or stale
lock does not win merely because its file exists.

Zero or multiple live writers, missing `lsof`, permission failures, changing
PIDs/inodes and conflicting evidence fail closed before queueing. Archived saved
copies still count. Unreadable or incompatible known databases and missing
configured databases also prevent implicit submission. Choose `--codex-home`
explicitly to bypass unrelated inventory and activity checks. Resolved symlink
aliases and repeated paths count as one home.

With no competing saved home, native queue behavior is preserved. `list`
aggregates known homes unless `--codex-home` selects exactly one. There is no general filesystem scan or process
environment inspection, and process arguments are not exposed. Activity
inspection runs on the destination machine, including over SSH. Platforms
without POSIX `flock` or `lsof` cannot automatically resolve competing homes and
must use `--codex-home`. Unconfigured/custom layouts and copies created after the
check can still be missed. Use `session-peer doctor` to inspect the selected home,
bounded candidates, executable, and supported state DB schema without submitting.
For every send and dry-run, session-peer finds every known home that saves the
UUID and examines its exact `thread-writer-locks/<uuid>.lock`. This includes a
single candidate and an explicit `--codex-home`. It independently probes the
kernel advisory lock and correlates the opener through two stable `lsof`
observations. An implicit send selects the only stable, same-user Codex writer.
An explicit home must be that writer; if another home owns the only live writer,
the command returns a structured conflict and never changes the home silently.
The selected PID, process start time, and held lock are checked again immediately
before queue submission. A free or stale lock does not win merely because its
file exists.

Unknown evidence, multiple live writers, missing `lsof`, permission failures,
changing PIDs/start times/inodes, and conflicting evidence fail closed before
queueing. Archived saved copies still count. Unreadable or incompatible known
databases and missing configured databases also prevent submission. If every
saved copy is inactive, intentionally queueing for a future resume requires an
explicit `--codex-home` together with `--allow-inactive-codex-home`; `--wake`
already serves as the explicit activation opt-in. The inactive flag without an
explicit home is rejected. Resolved symlink aliases and repeated paths count as
one home.

`list` aggregates known homes unless `--codex-home` selects exactly one. There
is no general filesystem scan or process environment inspection, and process
arguments are not exposed. Activity inspection runs on the destination machine,
including over SSH. Platforms without POSIX `flock` or `lsof` cannot establish
live-writer ownership and fail closed when that evidence is required.
Unconfigured/custom layouts and copies created after the check can still be
missed. Use `session-peer doctor` to inspect the selected home, bounded
candidates, executable, and supported state DB schema without submitting.

### Submission and JSON results

Expand Down Expand Up @@ -505,8 +512,8 @@ Within the common envelope, Codex send JSON includes `target: {agent, id}`,
- `codexHome`: the resolved absolute destination home, not a sender-side guess.
- `codexHomeResolution`: schema-versioned `status`, `selected`, `reason`, and
bounded candidate evidence. Status is `explicit`, `selected`, `ambiguous`, or
`unknown`; candidates expose saved-thread, writer-lock and stable owner PID
facts without process arguments or environment values.
`unknown`; candidates expose saved-thread, writer-lock, stable owner PID and
process start-time facts without process arguments or environment values.
- `submitted`: `true` only after successful queue CLI completion, `false` for dry-run.
- `consumptionConfirmed`: always `false`; neither queued nor validated establishes consumption.

Expand Down
2 changes: 1 addition & 1 deletion docs/i18n-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"docs/ai-assistant-guide.md": "9624ec96b92fb688fae3be3c94cb3564c77985091be451fbf1f056a1af9b9d9c",
"docs/antigravity.md": "6937c0208464dc536ce810abd70e449b65cb72e1d937a3d818339f46a9ab11d4",
"docs/architecture/agent-transports.md": "859af9c28d2cd12830bb1a084d9a5d03f3ede637a52e7ff7271f509edfaeaf7b",
"docs/cli-reference.md": "85016f5d378ed7dca97753ac420c68cb1e6ebcdf81680a15547239dc1492fa95",
"docs/cli-reference.md": "bdd93721d00f2df1d684f3cd99c7a5addeb965b58e439a3d1a9d09eabfb15b18",
"docs/diagnostics.md": "e7c757655a08c3a0180e375a7bdd67c034f6916e800968054aa1cc98ec1ca4aa",
"docs/download-metrics.md": "ded60e7b84d14ce779f8d639516b4e390358a06ef76b677dc9c1f997fb626a9f",
"docs/mcp.md": "e99689b8e6a222babc9438be2b2aabee953c3e0b2f967c6582065569529c32da",
Expand Down
54 changes: 29 additions & 25 deletions docs/ja/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -424,9 +424,9 @@ session-peer send --host mac --to 'codex:<full-thread-uuid>' \

ローカルで使用する場合は `--host mac` を省略します。実際に送信する準備ができたときにのみ `--dry-run` を削除してください。
`~` をクォートすることで送信先での展開が維持されます。絶対リモートパスも
機能します。`--codex-home` は明示的にそのコピーを選択しますが、アクティビティの証明にはなりません。
この明示的ホームの形式は、アクティブライターの解決機能より前のリリースでも
機能します。
機能します。現在のリリースは `--codex-home` を送信先の制約として扱いながら、一致するすべての
既知ホームのライターエビデンスを検証します。以前のリリースも明示的ホームの構文を受け付けますが、
この安全性は保証しません。

重複ホームの拒否ベースラインは v0.6.1 でリリースされました。後述のアクティブライターの
選択、再検証、および詳細な `codexHomeResolution` エビデンスは v0.6.2 でリリースされています。
Expand All @@ -449,27 +449,31 @@ export SESSION_PEER_CODEX_HOMES='["/srv/codex/account-a", "/srv/codex/account-b"
絶対 Windows パスを使用します。空の設定配列は許可されます。設定が不正な形式である場合、
暗黙的な送信ではエラーになります。

UUID が複数の既知のホームに存在する場合、session-peer は一致する各ホーム内の正確な
`thread-writer-locks/<uuid>.lock` を検査します。カーネルのアドバイザリロックを個別にプローブし、
2 回の安定した `lsof` 観測を通じてオープンしているプロセスを関連付けます。同一ユーザーの安定した
Codex ライターがちょうど 1 つだけ存在する場合にそのホームが選択され、そのエビデンスは
キューへの投入直前に再度チェックされます。空きロックや古いロックは、単にそのファイルが
存在するというだけでは選択されません。

アクティブなライターが 0 または複数存在する場合、`lsof` の欠落、権限エラー、PID/inode の変動、
および競合するエビデンスがある場合は、キューイングの前にフェイルクローズ(安全側に倒して失敗)します。アーカイブされた保存済みコピーも
カウントされます。読み取り不能または互換性のない既知のデータベースや、設定されたデータベースの欠落も、
暗黙的な送信を妨げます。無関係なインベントリやアクティビティのチェックをバイパスするには、`--codex-home` を
明示的に選択してください。解決されたシンボリックリンクのエイリアスおよび重複するパスは、1 つのホームとしてカウントされます。

競合する保存済みホームがない場合、ネイティブのキュー動作が維持されます。`list` は、
`--codex-home` が正確に 1 つを選択しない限り、既知のホームを集約します。一般的なファイルシステムスキャンやプロセス
環境の検査は行われず、プロセス引数は公開されません。アクティビティの
検査は、SSH 経由を含め、送信先マシン上で実行されます。POSIX の
`flock` または `lsof` を備えていないプラットフォームでは、競合するホームを自動的に解決できないため、
`--codex-home` を使用する必要があります。未設定/カスタムのレイアウトや、チェック後に作成された
コピーは見落とされる可能性があります。送信を行わずに、選択されたホーム、限定された候補、
実行可能ファイル、およびサポートされている状態 DB スキーマを検査するには、`session-peer doctor` を使用してください。
すべての送信と dry-run で、session-peer は UUID を保存する既知のホームをすべて検出し、
各ホームの正確な `thread-writer-locks/<uuid>.lock` を検査します。候補が 1 つの場合や明示的な
`--codex-home` も対象です。カーネルのアドバイザリロックを個別にプローブし、2 回の安定した
`lsof` 観測を通じてオープンしているプロセスを関連付けます。暗黙的な送信では、同一ユーザーの
安定した Codex ライターが唯一存在するホームを選択します。明示したホームはそのライターと一致する
必要があり、別のホームが唯一のライブライターを所有する場合、コマンドは構造化された競合を返し、
ホームを暗黙に変更しません。選択された PID、プロセス開始時刻、および保持中のロックは、キューへの
投入直前に再確認されます。空きロックや古いロックは、単にファイルが存在するだけでは選択されません。

不明なエビデンス、複数のライブライター、`lsof` の欠落、権限エラー、PID/開始時刻/inode の変動、
および競合するエビデンスは、キューイング前にフェイルクローズします。アーカイブされた保存済みコピーも
カウントされます。読み取り不能または互換性のない既知のデータベースや、設定されたデータベースの欠落も
送信を妨げます。すべての保存済みコピーが非アクティブな場合、将来の resume 用に意図してキューへ
入れるには、明示的な `--codex-home` と `--allow-inactive-codex-home` を併用する必要があります。
`--wake` はすでに明示的なアクティベーションの opt-in として扱われます。明示したホームなしで
inactive フラグだけを指定すると拒否されます。解決されたシンボリックリンクのエイリアスおよび
重複するパスは 1 つのホームとしてカウントされます。

`list` は `--codex-home` が正確に 1 つを選択しない限り、既知のホームを集約します。一般的な
ファイルシステムスキャンやプロセス環境の検査は行われず、プロセス引数は公開されません。アクティビティの
検査は SSH 経由を含め送信先マシン上で実行されます。POSIX の `flock` または `lsof` を備えていない
プラットフォームではライブライターの所有権を確立できず、そのエビデンスが必要な場合はフェイルクローズ
します。未設定/カスタムのレイアウトや、チェック後に作成されたコピーは見落とされる可能性があります。
送信を行わずに、選択されたホーム、限定された候補、実行可能ファイル、およびサポートされている状態 DB
スキーマを検査するには、`session-peer doctor` を使用してください。

### 送信と JSON 結果

Expand Down Expand Up @@ -501,7 +505,7 @@ Codex メッセージは、測定された Codex サーバーの制限ではな
- `codexHomeResolution`: スキーマバージョン付きの `status`、`selected`、`reason`、および
限定された候補のエビデンス。ステータスは `explicit`、`selected`、`ambiguous`、または
`unknown` です。候補には、プロセスの引数や環境変数の値を含めることなく、
保存されたスレッド、ライターロック、および安定した所有者 PID の事実が開示されます。
保存されたスレッド、ライターロック、安定した所有者 PID、およびプロセス開始時刻の事実が開示されます。
- `submitted`: キュー CLI が正常に完了した後にのみ `true`、dry-run の場合は `false`。
- `consumptionConfirmed`: 常に `false`。queued も validated も消費を確立するものではありません。

Expand Down
Loading
Loading