projmux 0.15.3 → 0.16.1

package/README-ko.md

@@ -72,8 +72,8 @@ projmux create claude --project mobile-client -- "마이그레이션 계획 초
 
 - [Resource Inspector](docs/resource-attribution.md) — 프로젝트·창·pane별 CPU와
   RSS를 실시간으로 봅니다.
-- [Session State](docs/session-restore.md) — 창 배치와 작업 디렉터리를 스냅샷으로
-  남깁니다.
+- [Project Startup](docs/session-restore.md) — 닫힌 프로젝트를 Registry에 저장된
+  창 구성으로 이어 열거나 새로 만듭니다.
 - 검색 루트, 키 설정, 업데이트는 설정에서 바꿉니다.
 
 ## 요구 사항
@@ -93,8 +93,7 @@ projmux create claude --project mobile-client -- "마이그레이션 계획 초
 [상태 표시줄](docs/statusbar.md) ·
 [훅](docs/hooks.md) ·
 [사용량 추적](docs/usage-tracking.md) ·
-[운영 진단](docs/operational-diagnostics.md) ·
-[에이전트 작업 흐름](docs/agent-workflow.md)
+[운영 진단](docs/operational-diagnostics.md)
 
 ## 개발
 

package/README.md

@@ -72,7 +72,8 @@ Templates and naming conventions are in
 
 - Live per-project, per-window, and per-pane CPU/RSS in the
   [Resource Inspector](docs/resource-attribution.md).
-- Layout and cwd snapshots in [Session State](docs/session-restore.md).
+- Registry-based Continue project and Clear layout and open in
+  [Project Startup](docs/session-restore.md).
 - Search roots, keybindings, and updates in Settings.
 
 ## Requirements
@@ -92,8 +93,7 @@ Templates and naming conventions are in
 [Statusbar](docs/statusbar.md) ·
 [Hooks](docs/hooks.md) ·
 [Usage tracking](docs/usage-tracking.md) ·
-[Operational Diagnostics](docs/operational-diagnostics.md) ·
-[Agent Workflow](docs/agent-workflow.md)
+[Operational Diagnostics](docs/operational-diagnostics.md)
 
 ## Development
 

package/docs/agent-message-replies.md

@@ -1,10 +1,24 @@
 # Explicit reply recovery
 
 An explicit Claude reply names the original request with `--reply-to`. The
-broker preserves that request's `conversationRef`, reverses its exact source
-and target routes, and retains peer, untrusted, coordination-only authority.
-Both activations and the original deadline must still be current. A reply
-cannot extend that deadline. Source metadata remains an unverified routing
+broker preserves that request's `conversationRef`, reverses its source and
+target Agents, and retains peer, untrusted, coordination-only authority. The
+reply goes to each Agent's current activation, and the original deadline must
+still be current. A reply cannot extend that deadline.
+
+Correlation follows the Agent and its provider conversation, not one
+activation. Either Agent may have been relaunched into the same conversation
+since the original, for example by `agent relaunch`: it now runs in a new Pane
+under a new activation, and a reply to the earlier message still commits and
+is delivered there. A reply to another Agent or on another provider is still
+refused as `invalid-explicit-reply-correlation`. When one of the original's
+Agents is now in another provider conversation (another Claude session), the
+reply is refused with `explicit-reply-conversation-changed` and stores
+nothing; the original cannot be answered there, so send a new message without
+`--reply-to`. A `--dialogue-reply-only` Agent's reply tool follows the same
+rule for the original's sender: it still permits a reply to a sender
+relaunched into the same conversation, and denies one to a sender now in
+another conversation. Source metadata remains an unverified routing
 claim; an explicit reply also requires the registered provider's descendant
 caller and any existing qualification and execution guard.
 
@@ -33,12 +47,75 @@ execution guard, use the existing bounded command without that flag:
 projmux agent message send uid:<original-source-agent> --reply-to <original-request-ref> -- '<corrected reply>'
 ```
 
+Operator input from an operator client has no Agent route to reverse, so a reply
+to it is refused with `explicit-reply-operator-origin` and stores nothing.
+
+Within the same provider session, a reply also commits after the Claude lease
+helper was replaced, for example by compact. The new helper did not push the
+original, so it reads the original from the durable store and judges it by the
+same checks. It reads the store only while its own route is the Registry's
+current authority for the Agent; a replaced or unregistered helper reads and
+writes nothing, and is refused with `broker-reply-helper-not-current`.
+`broker-reply-original-not-found` means the original is in neither the helper
+nor the store.
+
+## Reply refusal tokens
+
+Each refusal names its cause with one token. The CLI prints it after
+`replyTo=<ref>:`, the Claude helper returns it as the `reply-refused` reason,
+and the store returns it as the reply conflict reason. A token asks for one
+action, so two causes that need different actions never share one.
+`invalid-explicit-reply-correlation` is kept for a reply that does not match
+its original. Every refusal here except `broker-reply-outcome-unknown` comes
+before the reply is written anywhere: no provider saw it, so following the
+action cannot duplicate it. The retry rules below govern an attempt that was
+stored.
+
+| Token | Cause | Action |
+| --- | --- | --- |
+| `invalid-explicit-reply-correlation` | The reply's Agents, providers, or `conversationRef` do not match the original. | Check that `--reply-to` names a message you received and that the positional Agent is its sender. |
+| `explicit-reply-conversation-changed` | One of the original's Agents is now in another provider conversation. | Send a new message without `--reply-to`. |
+| `invalid-explicit-reply-envelope` | The reply itself is not a valid envelope, for example a payload over the limit. | Correct the reply, for example shorten it, and send it with a fresh ref. |
+| `explicit-reply-operator-origin` | The original is operator input from an operator client. | There is no Agent to answer; do not reply to it. |
+| `explicit-reply-deadline-expired` | The original's deadline has passed. | Send a new message without `--reply-to`. |
+| `explicit-reply-deadline-extended` | The reply's deadline is later than the original's. | Send the reply without a longer `--ttl`. |
+| `explicit-reply-source-route-stale`, `explicit-reply-target-route-stale` | The replying or the answered Agent's route is not its current one, for example during a relaunch, or the helper serving the reply is not the replying Agent's. | Wait until the Agent is registered again, then send the reply. |
+| `explicit-reply-route-stale` | The helper found a route no longer current at the moment it committed. | As above. |
+| `broker-reply-original-not-found` | The original is in neither the helper nor the store, for example because it was reclaimed. | Send a new message without `--reply-to`. |
+| `broker-reply-original-not-delivered` | The original never reached its target, so there is nothing to answer. | Inspect the original with `agent message status`; do not reply to it. |
+| `broker-reply-original-without-envelope` | The helper holds the ref, but not as an Agent message it can answer. | Send a new message without `--reply-to`. |
+| `broker-reply-helper-closed` | The replying Agent's Claude helper is shutting down, for example for a restart. | Wait for the new helper to register, then send the reply. |
+| `broker-reply-helper-not-current` | The Registry no longer names this helper as the Agent's current one; it was replaced. | Wait for the current helper to register, then send the reply. |
+| `broker-reply-unavailable` | The helper runs without a message broker and can commit no reply. | Relaunch the Agent so it starts a helper with one. |
+| `broker-reply-store-unavailable` | The helper could not use the durable message store. | Check the state directory, then send the reply. |
+| `broker-reply-store-busy` | Another writer held the message store. | Send the reply again. |
+| `broker-reply-store-malformed` | The message store file could not be read as a store. | Inspect the store; do not resend until it reads. |
+| `broker-reply-store-capacity` | The store is full and nothing can be reclaimed; see below. | Wait for records to be reclaimed. |
+| `reply-already-committed` | Another reply to the original was already committed. | Inspect it with `previousRef`; do not resend. |
+| `reply-ref-envelope-mismatch` | The same reply ref was used before with different content. | Use a fresh ref. |
+| `broker-reply-outcome-unknown` | A commit was attempted and its result is not known. | Inspect the reply status; do not resend. |
+
+A Claude helper that started before a build keeps that build's tokens until it
+is replaced. An older helper therefore still reports most of these causes as
+`invalid-explicit-reply-correlation`, and the CLI prints whichever token the
+helper sent.
+
+## Retries
+
 A same-ref call returns the original immutable receipt and never pushes again.
 Changing its payload is refused with the earlier ref and cause. A fresh ref
 allows one new attempt only when every previous attempt is known-zero. Failed
 records and the original request remain available; recovery never deletes or
-resets them. Store capacity can refuse a new attempt rather than discard its
-history.
+resets them.
+
+Store capacity treats the two kinds of attempt differently. A first attempt,
+one whose original has no stored attempt yet, is a new acceptance rather than a
+recovery, so a full store reclaims room for it under the same rule a new
+message uses, while pinning the original and every attempt already stored
+against it. A recovery attempt, which follows an earlier known-zero attempt, is
+still refused with a capacity error rather than discarding the history it is
+recovering from. Either way a reclaimed record moves to the history log below
+instead of being deleted, and a store with nothing reclaimable refuses both.
 
 Delivered replies, partial writes, unknown outcomes, pending attempts, expired
 deadlines, and stale routes must not be resent. Inspect their status and the
@@ -47,3 +124,69 @@ the stored state and specific zero-write reason must agree. These rules also
 apply after store reload and to concurrent callers. Automatic resend is
 disabled, and replies whose delivery target is Codex do not gain a new retry
 policy here.
+
+## Reclaimed records move to a history log
+
+The store is a bounded hot inbox. When it accepts a new message, or a first
+explicit reply attempt, it first reclaims records that went terminal more than
+24 hours ago, and then, if it is still at its record limit, the oldest
+unprotected terminal record. Before either step it expires any accepted or
+held record whose deadline has passed, exactly as a status read would, so such
+a record becomes terminal at that moment and follows the same reclaim rules;
+its 24 hours count from that expiry, not from its deadline. Reclaiming is not
+deleting: every reclaimed record is appended to
+`<state>/agent-messages/history.jsonl`, one JSON object per line, under the same
+file lock and with the same private directory and file permissions as the store.
+
+The append is fsynced before the store renames its own new file into place, so a
+crash in that window can leave a record in both the store and the log, but never
+in neither.
+
+Each line carries the envelope's own key names:
+
+```json
+{"schemaVersion":1,"evictedAt":"…","reason":"retention","adapter":"claude-coordination",
+ "messageRef":"…","conversationRef":"…","replyTo":"…",
+ "state":"delivered","deliveryReason":"unspecified","handoffObserved":false,
+ "acceptedAt":"…","terminalAt":"…","payloadBytes":466,"payloadSHA256":"…",
+ "source":{"agentUID":"…","provider":"…"},
+ "target":{"agentUID":"…","provider":"…"}}
+```
+
+`reason` is `retention` for the 24-hour rule and `capacity` for the record
+limit. `replyTo` is omitted when the record is not a reply. `outcomeUnknown`
+appears, as `true`, only on a failed record whose outcome is unknown; it is
+absent otherwise. `source` and `target` carry only `agentUID` and `provider`:
+the Pane and activation generation fence a live delivery, and the incarnation
+follows the provider conversation; all three mean nothing once the record has
+left the store. The envelope's `deadline` is not written. A line for operator
+input (see [Operator input](claude-coordination-endpoints.md#operator-input)) carries
+`"origin":{"kind":"operator","client":"<client>"}` in place of `source`; an Agent
+message's line has no `origin`. Every other key is always present.
+
+Lines written by earlier builds may still be in the same file. They carry full
+routes (`paneUID`, `activationGeneration`, `incarnation`), a `deadline`, and
+`outcomeUnknown` even when it is `false`, and they read the same way: a reader
+ignores keys it does not expect and reads an absent key as its zero value, so
+both shapes give the same edges, states and times. Lines written before the
+payload digest existed have no `payloadSHA256` key and read with an empty
+digest, which means "not recorded", not a mismatch; earlier lines are not
+backfilled. All of these are `schemaVersion` 1: every added key is additive.
+
+`schemaVersion` starts at 1 and follows the same rule as the
+coordination frame's field of that name: an absent or zero value reads as 1, and
+a reader that meets a higher version reads the fields it knows rather than
+discarding the line or failing. It is independent of the durable envelope
+version and of the store file version.
+
+The log does not keep the message body. It records `payloadBytes`, the original
+payload length, and `payloadSHA256`, the SHA-256 of the payload's exact bytes
+as 64 lowercase hex characters, and has no `payload` key at all: the log is
+unbounded in time, and its intended consumers need the message graph, not its
+text. The digest lets a consumer that holds the text elsewhere, such as a
+transcript, prove it is the same message; the reader and its consumers compute
+it with the same function (`PayloadSHA256` in `internal/core/agentmessage`).
+
+The active log rotates to `history.jsonl.1` once it would pass 8 MiB, replacing
+any earlier `history.jsonl.1`. At most two generations exist, so the log's disk
+use is bounded even though its history is not complete.

package/docs/ai-agent-shortcuts.md

@@ -53,11 +53,12 @@ Everything after `--` reaches the configured provider executable. Placeholder
 model, permission, and agent flags are private customization examples, not
 project defaults. Omit the separator when there is no payload.
 
-Settings > AI Settings > Enabled providers controls whether Claude, Codex, and
-Antigravity may launch. Canonical create routes respect that setting. There is
-no shared command-line override for a disabled provider; change Settings when
-the provider should become available. For a plain shell split use `projmux
-create pane`, not an Agent provider.
+`Settings > Global > AI > Enabled providers` controls whether Claude, Codex,
+and Antigravity may launch. Canonical create routes respect that setting.
+There is no per-launch override for a disabled provider; enable it in Settings
+or with `projmux config providers --enable <id>` (`--disable <id>` turns one
+off), which goes through the same writer. For a plain shell split use
+`projmux create pane`, not an Agent provider.
 
 Interactive provider and resume selection belong to the app's picker surfaces.
 CLI automation should choose an explicit provider or use `projmux agent resume