diff --git a/.agents/skills/afk/SKILL.md b/.agents/skills/afk/SKILL.md index 95f64b11e03..aba6e3fb00c 100644 --- a/.agents/skills/afk/SKILL.md +++ b/.agents/skills/afk/SKILL.md @@ -92,14 +92,15 @@ The daemon never injects into an in-use pane. Two checks run before every injection, dispatched through `bin/fm-backend.sh` for the supervisor's own backend (tmux or herdr; see "Auto-discovered supervisor pane" below): -- **`pane_is_busy`** - the harness shows a busy footer (agent mid-turn) on tmux (shared with `fm-send.sh` via `bin/fm-tmux-lib.sh`); on herdr, tries the native `agent.get`-backed busy state first, trusts only `busy` outright, and corroborates every non-`busy` verdict with the same regex-over-capture reader. +- **Primary-pane busy guard** - `pane_is_busy` trusts Herdr native `busy` when available, otherwise matches rendered output against only the detected primary harness's signature. + This narrow delivery guard never classifies a recorded worker task and never uses a global union of vendor patterns. - **Composer-state guard** - `inject_msg` reads the full `empty`/`pending`/`unknown` verdict from `fm_backend_composer_state` and injects only when it is affirmatively `empty`. `pending` means real unsubmitted text, while `unknown` includes an unreadable pane and a bare shell prompt left after the agent exits, so both defer. The shared `bin/fm-composer-lib.sh` owns the content decision after each backend captures and structurally identifies its own composer row. It preserves idle bordered composers such as claude's `│ > … │` and bare agent glyphs as empty, but a bare shell glyph is unknown unless inside a genuine bordered composer box; see `docs/herdr-backend.md` "Composer and injection safety" for the complete contract. `pane_input_pending` remains the tested predicate for callers that only need to know whether real unsubmitted text is present, but it is insufficient for an injection-safety decision because it cannot distinguish `empty` from `unknown`. -Either condition, or any composer verdict other than `empty`, defers the injection; the buffered escalation survives in `state/.subsuper-escalations` and is retried on the next housekeeping tick. +A busy primary pane, or any composer verdict other than `empty`, defers the injection; the buffered escalation survives in `state/.subsuper-escalations` and is retried on the next housekeeping tick. In afk mode the composer guard is belt-and-suspenders (no human is typing), but it protects against the race window between the captain returning and their message landing, a dead shell, and the daemon's own previous injection sitting unsent. **Max-defer escape (the daemon must never silently wedge).** @@ -181,14 +182,14 @@ the operational prefix lets firstmate distinguish it from a real captain message - **Single-line digest** - embedded newlines are collapsed to a literal separator before injection, so submission is unambiguous regardless of harness. -- **Composer guard on the supervisor pane** - before injecting, the daemon checks `pane_is_busy` (harness busy footer means agent mid-turn) and reads `fm_backend_composer_state` directly. +- **Busy and composer guards on the supervisor pane** - before injecting, the daemon runs the detected-primary-harness rendered busy guard and reads `fm_backend_composer_state` directly. Only `empty` permits injection; `pending` protects half-typed or swallowed input, and `unknown` protects unreadable panes and bare dead-shell prompts. Every other result preserves the buffer for retry, so the daemon never merges its digest into the captain's half-typed line or types it into a shell. - The shared composer classifier receives a candidate row only after the active backend performs its own capture and structural row recognition. tmux and herdr route their raw styled candidate rows through the shared `fm_composer_strip_ghost` extractor, which removes dim/faint and dark-TRUECOLOR ghost/placeholder text before classification. They read the composer shape from a separately ANSI-stripped plain row because a dark TRUECOLOR border can be stripped with ghost content. A ghost-only or idle bordered composer such as claude's `│ > ... │` therefore reads empty without allowing an unbordered shell prompt to do the same. - `FM_COMPOSER_IDLE_RE` still overrides tmux empty-composer matching after shared ghost and border stripping, and `FM_BUSY_REGEX` overrides busy footers. + `FM_COMPOSER_IDLE_RE` still overrides tmux empty-composer matching after shared ghost and border stripping, and `FM_BUSY_REGEX` overrides the rendered delivery guards plus Grok's isolated task-state fallback. - **Max-defer escape** - the daemon must never silently wedge. If anything stays buffered past `FM_MAX_DEFER_SECS` (default 300s), the daemon attempts one normal flush, which still requires an idle pane and an affirmatively empty composer. If that diff --git a/.agents/skills/bootstrap-diagnostics/SKILL.md b/.agents/skills/bootstrap-diagnostics/SKILL.md index 2b708799415..477980b8df1 100644 --- a/.agents/skills/bootstrap-diagnostics/SKILL.md +++ b/.agents/skills/bootstrap-diagnostics/SKILL.md @@ -2,7 +2,7 @@ name: bootstrap-diagnostics description: >- Agent-only handling playbook for session-start bootstrap diagnostics. - Use whenever the session-start digest's bootstrap section prints an actionable diagnostic line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, CREW_DISPATCH invalid, FLEET_SYNC, PR_CHECK_MIGRATION, SECONDMATE_SYNC, SECONDMATE_LIVENESS, NUDGE_SECONDMATES, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one of those lines. + Use whenever the session-start digest's bootstrap section prints an actionable diagnostic line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, STARTUP_MEMORY_BUDGET, CREW_DISPATCH invalid, FLEET_SYNC, PR_CHECK_MIGRATION, SECONDMATE_SYNC, SECONDMATE_LIVENESS, NUDGE_SECONDMATES, or FMX - or when a standalone bin/fm-bootstrap.sh run prints one of those lines. A silent bootstrap section, or a BOOTSTRAP_INFO fact, means no skill load. user-invocable: false metadata: @@ -27,6 +27,7 @@ When any diagnostic needs captain attention, report the plain consequence and re - `TANGLE: ` - the primary checkout is stranded on a feature branch instead of its default branch; `AGENTS.md` section 8 explains why this guard exists and what it protects. The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C checkout `, then re-validate that branch in a proper worktree. This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing. +- `STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - ` - the visible startup-memory budget is not a safe one-line positive decimal file; do not infer the default or propagate it. Correct the local primary file, then rerun session start so the normal convergence path can deliver the validated value to secondmate homes. - `CREW_DISPATCH: invalid config/crew-dispatch.json - ` - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, or invalid harness/effort pair rather than falling back around it or selecting a bad profile. - `FLEET_SYNC: : skipped: ` - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work. A skip can also report the bounded fleet-refresh timeout (`FM_FLEET_SYNC_BOOTSTRAP_TIMEOUT`, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup. diff --git a/.agents/skills/firstmate-coding-guidelines/SKILL.md b/.agents/skills/firstmate-coding-guidelines/SKILL.md index 8bbb275dae8..ac1da34dd84 100644 --- a/.agents/skills/firstmate-coding-guidelines/SKILL.md +++ b/.agents/skills/firstmate-coding-guidelines/SKILL.md @@ -44,7 +44,7 @@ Every contract - a data format, a state machine, a decision procedure - is state Every other mention of it is a one-line cross-reference, never a restatement. A single deliberate one-line reinforcement at a genuine risk point is allowed, for example a "don't forget X" placed exactly where forgetting X is costly. Restating the contract's substance a second time is not allowed: the two copies will drift the moment only one is edited. -When you touch a contract, grep the repo for its other mentions and update the cross-references, not duplicate the change into a second full copy. +When you touch a contract, patch, replace, or prune the owner's existing language rather than appending a new clause or paragraph wherever possible, then grep the repo for its other mentions and update the cross-references, not duplicate the change into a second full copy. ## Inline-stub pattern @@ -61,7 +61,7 @@ Apply the decision tree above to every line you are about to add to `AGENTS.md`. If an addition needs more than a few lines of conditional detail (detail that matters only in a specific situation) or reference detail (a wire format, an exact schema, historical rationale), you are almost certainly adding it to the wrong file. `AGENTS.md`'s token cost is paid by every session of every fleet member, every time, whether or not that session ever hits the situation the new lines describe. A skill's cost is paid only by the sessions that actually load it. -When in doubt, write the fact into the skill or doc first, and add only the one-line trigger to `AGENTS.md`. +When in doubt, write the fact into the skill or doc first by patching that owner's existing language, and add only the one-line trigger to `AGENTS.md`. ## Trigger hygiene diff --git a/.agents/skills/fmx-respond/SKILL.md b/.agents/skills/fmx-respond/SKILL.md index 762afb8d76b..94beca00a1f 100644 --- a/.agents/skills/fmx-respond/SKILL.md +++ b/.agents/skills/fmx-respond/SKILL.md @@ -4,7 +4,8 @@ description: >- Agent-only playbook for handling X mode mentions and follow-ups. Use on an "x-mention " check wake to read the stashed mention, classify it, act autonomously on eligible requests, reply or dismiss, and link spawned work. Also use on an "x-mode-error ..." check wake to report the X-mode configuration blocker instead of answering a mention. - Also use on milestone and terminal wakes for an X-mode-linked task before posting completion follow-ups, ending terminal outcomes with --final. + Also use on milestone and terminal wakes for an X-mode-linked task before posting completion follow-ups, using typed promised-final reconciliation when registered and --final otherwise. + Also use on a "public-followup ..." check wake, and whenever a promised final public reply must be created, reconciled, or delivered. Loaded only when X mode is enabled. user-invocable: false metadata: @@ -56,7 +57,7 @@ How the reply lands depends on whether the work finishes during this turn: The exact resolution and fail-safe posting contract is owned by `docs/configuration.md`. If a recovery respawns the same relay request onto a successor task, relink with the paired `--carry-count --carry-ts ` flags plus any prior `x_platform=` and `x_reply_max_chars=` as `--carry-platform --carry-max ` so the successor keeps the consumed follow-up count, original 7-day window, and reply split budget. 4. **Follow up on genuine milestones, sparingly.** Firstmate gets up to **three** follow-ups per mention, within a 7-day window, chained in the same thread - spend them only on changes the captain would actually want to hear about (e.g. investigation done and a build started, work shipped or ready, or the task failing), never on routine internal churn. - The task's final outcome - shipped / reported / merged / failed - is always posted with `--final`, which clears the link regardless of how many follow-ups remain. + A task without a promised-final commitment posts its final outcome - shipped / reported / merged / failed - with `--final`, which clears the link regardless of how many follow-ups remain. A typed promised-final commitment uses the deterministic consumer instead. That posting happens on the task's milestone and completion wakes (see "Completion follow-up" below), not this turn. So every drained mention sorts into one of three cases (the worthiness judgment, widened): @@ -141,7 +142,7 @@ Treat `state/x-inbox/` as the source of truth and process **every** file you fin **If the request spawned a real, longer-running task** (you ran `bin/fm-spawn.sh`), link that task to this mention so milestone and completion follow-ups can be posted: `bin/fm-x-link.sh `. **Link here, in step 2c, before the step 2f inbox cleanup** - `bin/fm-x-link.sh` can copy both the mention's reply platform and explicit budget from the still-present inbox payload without a relay lookup. If that local context is incomplete it uses the durable resolution contract in `docs/configuration.md` and warns loudly, while the follow-up path refuses to post unless both values can be resolved authoritatively. - Then step 2d's reply is an **acknowledgement** ("on it, captain"), and genuine milestone updates plus the final outcome come later as follow-ups (see "Completion follow-up" below), with the terminal one posted using `--final`. + Then step 2d's reply is an **acknowledgement** ("on it, captain"), and genuine milestone updates plus the final outcome come later as follow-ups (see "Completion follow-up" below), with the terminal one posted using `--final` when no typed promised-final commitment exists. If the work completed in this turn (a backlog item filed, a question answered), there is no task to link and step 2d reports the outcome directly. d. **Compose the reply.** For a **question**, answer `.text` from the fleet state gathered in step 1. For an **actionable request that completed now**, report the outcome of step 2c (what was done, or - for escalated work - that it has been flagged for the captain). For an **actionable request that spawned a linked task**, acknowledge that you have the order and are on it - milestone updates and the final outcome follow later as completion follow-ups, so do not promise a result you do not yet have. Either way keep it short, in firstmate's voice, and public-safe. Conversation continuity: when `in_reply_to` is present this is a conversation reply - read `in_reply_to.text` (what `in_reply_to.author_handle` said just before) as **context** and continue that thread, resolving "it", "that", "and then?" against the parent; for a fresh mention (`in_reply_to` is null) answer on its own. @@ -198,14 +199,50 @@ This skill's own responsibility during the mention-handling turn is linking the - On each such milestone, firstmate checks whether a follow-up is still due with `bin/fm-x-followup.sh --check ` (prints the `request_id` when the link exists, the count is under the cap, and the window has not lapsed; silent otherwise, pruning an exhausted or expired link). - If due, it composes a short, public-safe update and posts it with `bin/fm-x-followup.sh --text-file ` (or stdin), which posts via the relay's follow-up endpoint; a successful non-final post increments the counter and keeps the link so a later milestone can still post against it. When the update carries one real visual artifact, add `--image `; the helper forwards it to `bin/fm-x-reply.sh --followup` so the same image contract used for ordinary replies applies here too. -- On a terminal wake (PR merged / scout report / local merge / failed), firstmate posts the task's **final** outcome ("done, here's the result"; for a failure, an honest "this one didn't pan out") with `bin/fm-x-followup.sh --final --text-file `, which always clears the link after that post regardless of how many follow-ups remain under the cap. +- On a terminal wake (PR merged / scout report / local merge / failed), firstmate posts the task's **final** outcome ("done, here's the result"; for a failure, an honest "this one didn't pan out") with `bin/fm-x-followup.sh --final --text-file ` only when no promised-final public commitment is registered for that work. When the promised-final procedure above applies, `bin/fm-public-followup.sh consume` and `deliver` own the terminal reply and clear the legacy link at the validated receipt boundary, so do not call `fm-x-followup.sh --final` for the same outcome. If delivery reports that link cleanup needs reconciliation, do not post anything else; `bin/fm-x-followup.sh --clear ` is the clear-only recovery command in the bound work home. - Every follow-up is held to the exact same public-safety bar as every reply here: outcomes only, no task ids, internals, captain-private material, or secrets. Past the window, past the cap, or on the relay's own rejection of an exhausted binding, a follow-up attempt is skipped silently and the link is cleared - never treated as a failure worth retrying. - If either a follow-up's platform or explicit budget cannot be authoritatively resolved from per-request context, inbox payload, or relay answer, `bin/fm-x-followup.sh` does NOT post it: the fail-safe holds it (the link is kept, exit non-zero) rather than use a local default. This is a retryable hold - a later milestone wake retries it once both values are recoverable. +## Promised final replies (the commitment that must survive compaction) + +The follow-up budget above is a courtesy. +A **promised final reply** - "I'll report back when this lands" - is a commitment, and forgetting it is publicly visible. +Never carry one in your head: the moment you promise a specific outcome in a public thread, turn it into durable state and let the scripts reconcile it. +This section is the sole owner of that procedure. +`tasks-axi public-followup --help` owns the typed obligation, its states, and its file contracts; `bin/fm-public-followup.sh --help` owns firstmate's flags; do not restate either here. + +**When you promise a final:** + +1. Create the typed obligation with `tasks-axi public-followup add` and bind the work with `bind-work`, keeping the public-safe summary and the opaque thread binding in the obligation and the full request context where the poll already put it. +2. Register it with `bin/fm-public-followup.sh register --relation --work-home > --work-id --generation `. + This is what makes the commitment reconcilable without you. +3. Put `bin/fm-public-followup.sh brief ` output straight into the worker's brief. + It prints the exact reporting command for that binding. + Never ask a worker to find the thread or post the reply: only this home holds the relay consent and the thread binding. + +**When work reports back, or on a `public-followup ...` check wake, or when the session-start digest lists a public commitment:** + +1. Run `bin/fm-public-followup.sh consume`. + It reconciles every typed terminal result from disk and prints `ready ` for each commitment that became deliverable. + A refusal prints `rejected : ` and quarantines that event; read the reason rather than re-emitting blindly. +2. For each ready commitment, run `bin/fm-public-followup.sh deliver `. + With no `--text-file` it reuses the accepted terminal outcome exactly, which is the preferred path for a landed result. + Only pass `--text-file` when the outcome genuinely needs composing, and hold it to the same public-safety bar as every other reply here. + Delivery clears the bound task's legacy X link at the validated receipt boundary; if it reports a cleanup failure, use its reconciliation message and do not post a legacy final. +3. Read the outcome and stop guessing at anything it refuses: + - "still waiting on its bound work" means the work has not reported a typed terminal result yet - do not post. + - "recorded as retryable" means nothing was posted; retry on a later wake. + - "held" means the thread's platform or budget is unresolvable right now; retry once it is recoverable. + - "mid-delivery" means a previous post started and its outcome was never recorded. Do NOT deliver again. Establish whether that post landed, then either close it with `record-posted --attempt --chunks ` or escalate. Posting again would put a second reply in a public thread. + - "the relay no longer accepts a follow-up" is a captain decision, not a retry. + +Cleanup refuses while a commitment is still owed for that exact work, so never reach for `--force` to get past it. +Treat a commitment as kept only after a validated posted receipt or an explicit captain waiver. + ## Notes - The direct author is always your own captain (owner-only routing), and in live mode you answer and act on eligible requests **autonomously**: enabling X mode is the captain's standing authorization, so never ask the captain before posting and never hold a worthwhile reply for a chat-side OK. For reply-worthy mentions, dry-run (`FMX_DRY_RUN`) is the only non-posting path; pure acknowledgments use the relay dismiss path instead. -- An actionable mention is **acted on** through the normal lifecycle (intake, backlog, dispatch, investigate, ship), not merely replied to. Work that finishes now gets one outcome reply; work that spawns a real task gets an **acknowledgement now** plus up to three **completion follow-ups** over time, ending with a `--final` one (link the task with `bin/fm-x-link.sh` so those follow-ups can post). A reply alone, with no work behind an actionable ask, is the bug to avoid. +- An actionable mention is **acted on** through the normal lifecycle (intake, backlog, dispatch, investigate, ship), not merely replied to. Work that finishes now gets one outcome reply; work that spawns a real task gets an **acknowledgement now** plus up to three **completion follow-ups** over time, ending with a `--final` one when no typed promised-final commitment exists (link the task with `bin/fm-x-link.sh` so those follow-ups can post). A reply alone, with no work behind an actionable ask, is the bug to avoid. - Destructive, irreversible, or security-sensitive asks are flagged to the captain through the trusted channel first and never run straight from a mention; the public reply says only that it has been flagged. - One answered mention = one reply (plus up to three completion follow-ups for a spawned task, spent only on genuine milestones); a skipped mention posts no reply but is **dismissed at the relay** (`bin/fm-x-dismiss.sh`) so the relay drops it rather than re-offering it (which would otherwise churn every poll and end in an "offline" auto-reply). A single wake may cover several pending mentions - drain them all. - Conversations: `in_reply_to` carries the parent post for continuity; a pure acknowledgment with nothing to answer is dismissed at the relay and skipped, not replied to. The relay already guards against self-replies and caps replies per conversation, so you only judge "is there something to answer here?". diff --git a/.agents/skills/harness-adapters/SKILL.md b/.agents/skills/harness-adapters/SKILL.md index 5c6719b4001..947a3f6b78e 100644 --- a/.agents/skills/harness-adapters/SKILL.md +++ b/.agents/skills/harness-adapters/SKILL.md @@ -12,7 +12,7 @@ Use this reference before any harness-specific firstmate operation: spawn, recov Crewmates default to the same harness firstmate is running on unless `config/crew-harness` records an adapter name. Optional dispatch profiles in `config/crew-dispatch.json` can override that static default for one crewmate or scout dispatch by selecting concrete harness, model, and effort axes at intake. -When a matched rule or default is a profile array, load `quota-array-dispatch` for the pace-aware candidate choice after this skill establishes harness and model/provider facts. +When a matched rule or default is a profile array, load `quota-array-dispatch` for the completion-aware candidate choice after this skill establishes harness and model/provider facts. The captain may override that file at session start or later; a per-task instruction such as "run this one on codex" overrides it for that dispatch only. `default` means mirror firstmate's own harness. @@ -29,12 +29,13 @@ Each adapter splits into mechanics and knowledge. The per-task mechanics, including launch command, autonomy flag, and any enabled crewmate turn-end hook, live in `bin/fm-spawn.sh`. The primary-session "no turn ends blind" guard contract and harness hook installation paths live in `docs/turnend-guard.md`. The primary-session watcher wake protocols are rendered from `docs/supervision-protocols/` by `bin/fm-supervision-instructions.sh`. -The supervision knowledge lives here: busy signature, exit command, interrupt, dialogs, resume behavior, skill invocation, and quirks. +The supervision knowledge lives here: busy state, exit command, interrupt, dialogs, resume behavior, skill invocation, and quirks. +Each adapter's `Busy state` row names only which semantic source that harness uses; `bin/fm-busy-lib.sh` owns the contract itself, including verdicts, source attribution, and the verification gates that keep an unverified harness at unknown. Never dispatch a crewmate or secondmate on an unverified adapter. If `config/crew-harness` or `config/secondmate-harness` names an unverified adapter, tell the captain under `AGENTS.md` section 9 that the requested worker runtime is not verified yet, use firstmate's own verified runtime for current work, and ask only whether to verify the requested runtime before future use. Do not pause current work for that future-verification choice, and never launch an unverified adapter. -If the captain asks for a new harness, propose verifying it first: spawn a trivial supervised task using `fm-spawn`'s raw-launch-command escape hatch, confirm every fact empirically, then record the mechanics in `fm-spawn`, the busy signature in `fm-watch.sh` and `fm-tmux-lib.sh` defaults, any needed `FM_COMPOSER_IDLE_RE` empty-composer override plus any novel bare agent prompt glyph in `bin/fm-composer-lib.sh`'s shared composer classifier (the one fleet-wide owner of the empty/dead-shell/pending decision, so a new harness's own idle composer is not misread as a dead shell), the tmux agent-process liveness classification in `bin/backends/tmux.sh` when the harness can launch a secondmate, and the verified knowledge here. +If the captain asks for a new harness, propose verifying it first: spawn a trivial supervised task using `fm-spawn`'s raw-launch-command escape hatch, confirm every fact empirically, then record the mechanics in `fm-spawn`, its semantic busy source and trust gate in `bin/fm-busy-lib.sh`, any needed `FM_COMPOSER_IDLE_RE` empty-composer override plus any novel bare agent prompt glyph in `bin/fm-composer-lib.sh`'s shared composer classifier (the one fleet-wide owner of the empty/dead-shell/pending decision, so a new harness's own idle composer is not misread as a dead shell), the tmux agent-process liveness classification in `bin/backends/tmux.sh` when the harness can launch a secondmate, and the verified knowledge here. ## Detection @@ -132,6 +133,7 @@ The supported launch-profile flags below are verified locally; each row records | kimi | `--model ` | none | Verified 2026-07-25 on Kimi Code CLI 0.29.1. | The concrete `harness` field owns adapter identity independently of the model provider: `harness=pi` with `model=xai/grok-*` is Pi using xAI, not `harness=grok`, and does not require Grok CLI login; `harness=grok` remains the standalone Grok Build CLI adapter. +No script resolves that split for you: establish which credential store a tuple reads from the discovery surfaces below plus `quota-axi auth --json`'s per-provider sources, and show that reasoning rather than inferring it from a harness, model, or source name. ### Model support discovery @@ -148,7 +150,8 @@ Use the discovery surface in the current authenticated environment because suppo | kimi | Run `kimi provider list --json`, which lists the current provider and model configuration. | For an unfamiliar harness or model namespace, establish support and provider identity from that harness's authoritative CLI help, model listing, or current documentation rather than guessing from a name or prefix. -If those sources do not establish the relationship needed for dispatch, fail loudly and report the unresolved candidate. +A listing that reaches the account and does not contain the model is concrete evidence the model is unsupported: block that candidate and quote the result. +A discovery surface you could not reach establishes nothing; report that as uncertainty rather than turning it into a supported or unsupported verdict. When a requested effort value is outside the harness-specific accepted set, `fm-spawn` records the requested `effort=` in meta but emits no effort flag for that harness. This preserves launch success instead of passing a known-bad value. @@ -171,11 +174,11 @@ A send or key action reporting success is not proof that the intended action hap OpenCode can accept and queue an Enter while leaving text visible, Grok can consume Enter in its slash popup without submitting, and Kimi can silently drop a message sent before readiness even though the send returns success. The shared symptom is a healthy-looking pane with no work in progress, so each adapter must verify the observable postcondition that is specific to its TUI. -## claude (VERIFIED; busy signature re-verified 2026-07-25 on Claude Code 2.1.220) +## claude (VERIFIED; busy-state hooks live-verified 2026-07-28 on Claude Code 2.1.220) | Fact | Value | |---|---| -| Busy-pane signature | Current turns match the harness-scoped `…[[:space:]]+\([0-9]+[smh]` shape after a rotating glyph and word, for example `✢ Pollinating… (16s · ...)`; legacy `esc to interrupt` remains accepted, while `Worked for 31s` is idle. | +| Busy state | Owned lifecycle hooks: `UserPromptSubmit` opens a turn, `Stop`, `StopFailure`, and `SessionEnd` close it. Claude fires no hook for a manual interrupt, so a firstmate-initiated interrupt must record the clear itself. | | Exit command | `/exit` | | Interrupt | single Escape | | Skill invocation | `/` (e.g. `/no-mistakes`) | @@ -205,7 +208,7 @@ Claude Code's primary watcher protocol is Stop-owned: the auto-arm hook fires on | Fact | Value | |---|---| -| Busy-pane signature | `esc to interrupt` (shown as `• Working (Xs • esc to interrupt)`) | +| Busy state | Unknown until a semantic source is live-verified: the app-server turn lifecycle is unreachable for a pane worker, and project lifecycle hooks did not fire for a firstmate-launched worker. | | Exit command | `/quit` (slash popup needs about 1 second between text and Enter; `fm-send` handles it) | | Interrupt | single Escape | | Skill invocation | `$` (e.g. `$no-mistakes`); `/` is claude-only and codex rejects it as "Unrecognized command" | @@ -236,7 +239,7 @@ The checkpoint is deliberately foreground and bounded so Codex regains control r | Fact | Value | |---|---| -| Busy-pane signature | `esc interrupt` (dotted spinner footer; note no "to") | +| Busy state | The Firstmate-owned plugin's semantic `session.status`: `busy` and `retry` are active, `idle` is inactive, latched to the worker's own session. | | Exit command | `/exit` | | Interrupt | double Escape; known flaky while a long shell command runs, so a wedged pane may need `/exit` and relaunch | @@ -273,7 +276,7 @@ The follow-up was verified in the interactive TUI; `opencode run` can exit befor | Fact | Value | |---|---| -| Busy-pane signature | `Working...` (braille spinner prefix; no `esc to interrupt` text) | +| Busy state | The Firstmate-owned extension's `agent_start` (busy) and `agent_settled` confirmed by `ctx.isIdle()` (idle), which covers retries, compaction, tool loops, and queued continuations. | | Exit command | `/quit` | | Interrupt | single Escape | @@ -311,7 +314,7 @@ For Grok's supported reasoning-effort values and omission behavior, see the [lau | Fact | Value | |---|---| -| Busy-pane signature | `Ctrl+c:cancel` (the mid-turn cancel hint in grok's keybind bar, shown iff a turn is running; the spinner line is a braille glyph + `… N.Ns` + `[stop]`, e.g. `⠹ Thinking… 1.1s … [stop]`). Idle keybind bar shows only `Shift+Tab:mode │ Ctrl+.:shortcuts`. The ASCII `Ctrl+c:cancel` is the busy regex (avoids locale fragility of matching braille). | +| Busy state | The one remaining rendered-tail fallback, isolated to Grok until its structured lifecycle is live-verified: `Ctrl+c:cancel`, the mid-turn cancel hint shown in grok's keybind bar iff a turn is running. The idle bar shows only `Shift+Tab:mode │ Ctrl+.:shortcuts`. ASCII is matched rather than the braille spinner to avoid locale fragility. | | Exit command | `/exit` typed into the composer exits the TUI cleanly and prints `Resume this session with: grok --resume `; `Ctrl+Q` double-press within 1000ms remains a fallback; `Ctrl+D` is the quit key in VS Code family terminals; `Ctrl+C` is the interrupt, not the exit. | | Interrupt | single `Ctrl+C` (cancels the current turn; the footer shows `Ctrl+c:cancel` mid-turn). `Esc` only moves focus to the scrollback, it does NOT interrupt. | | Skill invocation | `/` (e.g. `/no-mistakes`), same as claude. Opens a slash-autocomplete popup, so a too-fast Enter selects the popup entry instead of sending. For an argument-taking command that first Enter does not submit at all - it expands the selection into an argument-hint placeholder in the composer (e.g. `/compact` -> `/compact compaction instructions`, live-verified), leaving real text still sitting there unsubmitted; a genuine second Enter is required. `fm-send`'s retried Enter lands it on BOTH backends, but only because each backend's own submit-verification correctly recognizes that placeholder-filled text as still-pending - see the incident below. | @@ -368,7 +371,7 @@ Kimi Code CLI launches from the absolute path resolved from `PATH`, falling back | Binary | Executable `kimi` from `PATH`, then executable `$HOME/.kimi-code/bin/kimi`; spawning refuses if neither exists. | | Launch | Bare interactive TUI with `--auto`, followed by readiness-gated pointer delivery; positional prompts are rejected. | | Models | `kimi-code/kimi-for-coding` (default), `kimi-code/kimi-for-coding-highspeed`, `kimi-code/k3`, and `kimi-code/k3-256k`. | -| Busy-pane signature | A transient line with optional leading whitespace, a rotating moon-phase glyph, required whitespace on both sides of `·`, and optional trailing content; the line is absent when idle. | +| Busy state | Standalone Kimi is unknown until a semantic source is live-verified; prefer Wire's `prompt` request lifetime, then documented hooks including `Interrupt`. Kimi behind Pi uses Pi's lifecycle. Its moon-phase spinner is not a state source. | | Exit command | `/exit` | | Interrupt | Single Escape, which prints `Interrupted by user`. | | Skill invocation | `/`, for example `/no-mistakes`; firstmate skills are discovered. | @@ -390,12 +393,12 @@ The startup input-readiness window is the established cause of Kimi's first-Ente An early Enter can expand Kimi's composer to multiple content rows, leaving the pointer text on the first row and the cursor on an empty later row, which is the same single-cursor-row reading defect exposed by Grok's bottom-border cursor quirk. The shared tmux reader now locates the complete bordered composer and treats real text on any content row as positive evidence that submission is still pending. No rendering signal is trustworthy for proving that Kimi will accept input during this window, so delivery retries Enter through the shared submit core and retains the existing postcondition verification rather than relaxing readiness or delivery checks. -Kimi's footer tip rotates independently and can display `ctrl+c: cancel` while completely idle, so tip text is never used as its busy signature without the leading moon-plus-middot spinner structure. +Kimi's footer tip rotates independently and can display `ctrl+c: cancel` while completely idle, which is one reason no Kimi rendered signature is a state source. The idle status bar can contain lowercase `thinking`, which is the model's effort label rather than a busy signal. -The spinner match covers the full moon-phase glyph set rather than one frame, but it remains locale- and emoji-font-sensitive because Kimi exposes no stable ASCII busy token. +The delivery-only spinner match covers the full moon-phase glyph set rather than one frame, but it remains locale- and emoji-font-sensitive because Kimi exposes no stable ASCII busy token. [`docs/turnend-guard.md`](../../../docs/turnend-guard.md) owns Kimi's verified global hook surface and captain-approved crew wake integration. `fm-spawn.sh` installs one marker-delimited Firstmate entry in `$HOME/.kimi-code/config.toml`, one silent always-zero hook script, and one private token registry under `$HOME/.kimi-code/fm-turn-end.d/`. Each Kimi crew worktree receives a gitignored `.fm-kimi-turnend` token pointer, and the global hook touches that task's `state/.turn-ended` only when the Stop payload's `cwd`, pointer, and registry entry all agree. A guarded silent hook cannot be verified from absence of effect, so prove invocation with an unguarded probe before concluding that the hook did not fire. -The guarded turn-end signal supplements the pane busy signature, whose locale- and emoji-font-sensitive limits still apply while a turn is running. +The guarded turn-end signal remains a wake notification; standalone Kimi has no busy-state source until one is live-verified. diff --git a/.agents/skills/quota-array-dispatch/SKILL.md b/.agents/skills/quota-array-dispatch/SKILL.md index c384553a859..11b84058125 100644 --- a/.agents/skills/quota-array-dispatch/SKILL.md +++ b/.agents/skills/quota-array-dispatch/SKILL.md @@ -2,7 +2,7 @@ name: quota-array-dispatch description: >- Agent-only decision procedure for resolving a matched crew-dispatch profile - array from current quota-axi output, including quota-window pace signals. + array from current quota-axi output, including effective headroom and usable-runway evidence. Load when a dispatch rule or default resolves to more than one profile candidate. user-invocable: false metadata: @@ -11,25 +11,64 @@ metadata: # quota-array-dispatch -This skill is the single owner of the pace-aware profile-array selection procedure. +This skill is the single owner of the completion-aware profile-array selection procedure. `AGENTS.md` section 4 owns the always-loaded intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning/tie safety rules. `harness-adapters` owns harness verification, model/provider discovery, and effort fallback. -`quota-axi` remains data-only and never recommends a route. +`quota-axi` remains data-only, reports whatever granularity the vendor supplies, and never recommends, selects, ranks, or infers a route. Do not add a daemon, opaque composite score, routing wrapper, hard-coded model-specific policy, or producer-side route recommendation. +Deterministic shell owns only schema, configuration, and version validation plus concrete spawn safeguards; every model-to-provider, provider-to-credential, and quota-applicability relation is yours to establish transparently and to show your evidence for. ## Collect facts Run `quota-axi --json` once per intake and reuse that snapshot for every candidate. +Do not take a second snapshot to settle a candidate, and read `quota-axi auth --json` when a candidate's credential surface is in question. For each candidate, preserve explicit `harness`, `model`, and `provider`; `harness-adapters` owns identity, and model/provider never infer harness: - task/profile fit and required reasoning class -- raw applicable headroom (`effectivePercentRemaining` or tightest applicable percentage) -- effective pace, signed reserve per window, and worst reserve (`worstReservePercentPoints` or minimum signed reserve) -- whether applicable windows/summary are ahead, or pace is `unknown` -- schema note when pace fields are absent +- applicable effective headroom (`effectivePercentRemaining`) from the established provider/model scope +- usable runway status, `usableRunwaySeconds`, `projectedExhaustedAt`, `limitingWindowId`, `projectionConfidence`, `projectionBasis`, and any `unmeasurableWindowIds` +- the task-completion horizon and the evidence and confidence used to estimate it +- effective pace, signed reserve per window, and worst reserve (`worstReservePercentPoints` or minimum signed reserve) for later diagnostic tie-breaking +- schema notes when runway or pace fields are absent -Stale raw windows are diagnostic, never headroom. -Read all windows named by `boundedBy`, `limitingWindowIds`, `aheadWindowIds`, `behindWindowIds`, `onPaceWindowIds`, and `unknownWindowIds`. +Stale raw windows are diagnostic, never headroom or fabricated runway. +Grok's `credits.remaining` is a prepaid balance unrelated to `percentRemaining`; never read it as exhaustion. +Read all windows named by `boundedBy`, `limitingWindowIds`, `aheadWindowIds`, `behindWindowIds`, `onPaceWindowIds`, `unknownWindowIds`, and `unmeasurableWindowIds`. +The compact default output intentionally omits numeric reserve, while `--json` and `--full` retain reserve diagnostics. + +## Establish the provider relation before reading quota + +Deterministic shell must never map a model to a provider, a provider to a credential store, or a name prefix to a family. +You establish those relations yourself, in the open, from the candidate's own authoritative catalog (`harness-adapters` owns the per-harness discovery surface) plus the one intake snapshot. +Name the evidence for each relation you assert so the conclusion is inspectable. + +1. Confirm the catalog lists the candidate's model and record the provider family it reports. + A model the authoritative catalog does not list is concrete contradictory evidence: block that candidate and quote the catalog result. +2. Apply quota at the granularity the vendor actually supplies. + A provider-level or `all_models`/`all_products` scope bounds every model you established in that family, including one with no window of its own. + A named-model or named-product scope is an additional bound for that model alone and is irrelevant to every other model in the family. + Read `quotaSemantics.description`, which states the vendor's own bounding rule. +3. Record what remains unknown instead of converting it into a verdict. + +## Authentication is scoped to the selected surface + +A candidate authenticates through its own tuple's surface; another harness's CLI can never gate it, and `harness=pi` with `model=xai/grok-*` is Pi using xAI rather than the standalone Grok CLI. +`quota-axi auth --json` lists each provider's credential sources independently, so read the one source the candidate actually uses rather than collapsing a provider to a single status. +A provider can carry a healthy source beside a missing or expired one; the unused source's state is not the candidate's state. +A Pi-hosted family may authenticate through the vendor's own store with no `pi:`-prefixed source at all, which is normal and never evidence against the candidate. + +Uncertainty and ineligibility are different findings: + +- No model-level window, no matching auth source, an absent `state.authStatus`, an unmeasurable or `unknown` scope, or a surface quota-axi does not model at all is disclosed uncertainty. + Keep the candidate eligible, state the unknown, and prefer known sustainable evidence when otherwise comparable. +- An expired credential is a short-lived session token the owning vendor renews on next use, not a sign-out. +- Only concrete contradictory evidence blocks: an authoritative catalog proving the model unsupported, or proof that the credential the candidate actually selects is unusable. +- Reserve login wording for that proven-unusable case, and name the harness, model, surface, and evidence. + +When a credential's local classification is the only thing standing between a candidate and a block, get ground truth before blocking. +`bin/fm-vendor-auth-probe.sh` is the only approved vendor-credential probe; its `--help` owns the registered probes and mechanics. +It takes no harness, model, or provider and returns a fact, not a route: only `authenticated` and `unauthenticated` are ground truth, while `indeterminate`, `timeout`, and `unavailable` establish nothing and must never be read as either outcome. +Never launch a vendor CLI yourself, and never probe a credential store the candidate does not use. ## Pace semantics @@ -43,23 +82,32 @@ Conservation pressure is present for effective pace status `ahead`, effective pa ## Selection order Apply only among candidates satisfying required fit and strongest reasoning class. -Never use pace or raw headroom to silently replace that reasoning class. - -1. Unresolved relationship or quota: stop and report the tuple and concrete evidence. -2. All-tight: keep strongest reasoning; dispatch inside it or report if blocked. -3. Comparable fit/reasoning: prefer no ahead pressure over pressure, even with higher raw headroom. -4. Among pressured candidates, prefer the least-negative worst applicable reserve. -5. Sustainable candidates: use known pace plus raw headroom. - Prefer known sustainable evidence over `unknown` when comparable. - Do not collapse those facts into an opaque composite score. -6. If unresolved pace changes the choice, report uncertainty. -7. Absent pace or older schema: do not crash, fabricate pace, or treat absence as healthy/`on_pace`. - Compare raw headroom only, state pace is unavailable, and keep safety rules. -8. Genuine ties: stop and report every tied candidate for captain choice. +Never use headroom, runway, pace, or reserve to silently replace that reasoning class. + +1. Concrete contradictory evidence or malformed configuration: stop and report the tuple and that evidence. + Unmeasurable quota, a missing model-level window, an absent runway field, and a credential surface quota-axi does not model are uncertainty, never this rule. +2. Honor any explicit captain instruction that sets a floor for that candidate before the generic comparison. + Do not invent a generic percentage floor or treat a low percentage as an automatic failure. +3. Keep the strongest-reasoning class when every candidate is tight or completion evidence is poor. + Dispatch inside that class when a candidate can proceed, or report that its strongest-class choice cannot proceed rather than downgrading it to conserve quota. +4. Compare comparable-fit candidates on their applicable effective headroom and usable runway. + Eliminate a candidate only when another candidate Pareto-dominates it on both dimensions, with at least one dimension strictly better. + Establish dominance only from comparable known evidence, never by treating absent, `unknown`, or unmeasurable headroom or runway as zero or as a healthy value. +5. Prefer supported runway evidence that projects availability through the inspectable likely-completion horizon. + Known evidence that does not reach that horizon is inferior to known evidence that does, even when its signed reserve is less negative. + Preserve projection confidence and basis, the limiting window, and the horizon estimate in the rationale rather than hiding them in a score or model-specific heuristic. +6. Resolve remaining uncertainty explicitly. + An authenticated candidate with unknown or unmeasurable headroom or runway stays eligible and cannot be silently excluded or assumed sustainable. + Prefer known viable evidence when otherwise comparable, and report uncertainty or ask the captain when it still prevents a justified choice. +7. Use pace and signed reserve only as later diagnostic tie-break evidence among candidates still unresolved after headroom, runway, likely-completion viability, and uncertainty. + Pace and reserve never rescue a clearly inferior completion prospect. + Do not collapse these facts into an opaque composite score. +8. Older schemas or absent runway/pace fields: do not crash, fabricate runway or pace, treat absence as healthy, or silently exclude a candidate. + State which evidence is unavailable, retain the candidate, and apply only the comparisons the snapshot supports. +9. Genuine ties: stop and report every tied candidate for captain choice. Do not select by array order, harness name, or another arbitrary identity ordering. Report duplicate concrete profiles as a configuration error. -Name the inspectable facts used for every candidate. -After selecting, check auth only through that tuple's surface; another harness CLI cannot block it. +Account for every candidate visibly before selecting or escalating, naming its catalog evidence, provider relation, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, effective headroom, usable runway, likely-completion reasoning, and later pace or reserve evidence when used. A blocked credential report must name `harness`, `model`, authentication surface, and concrete failure evidence; never emit a bare `Grok unauthenticated` statement. Never conclude with an unexplained "best quota" label. diff --git a/.agents/skills/secondmate-provisioning/SKILL.md b/.agents/skills/secondmate-provisioning/SKILL.md index f9e68937ab9..978f4a954aa 100644 --- a/.agents/skills/secondmate-provisioning/SKILL.md +++ b/.agents/skills/secondmate-provisioning/SKILL.md @@ -24,6 +24,7 @@ Keep the always-inline routing rules in `AGENTS.md` authoritative: route by natu ``` Each registry entry stays concise and single-line: the summary is one sentence naming the durable charter, `scope:` is the natural-language intake responsibility, `projects:` is the non-exclusive clone list, and any extra prose is limited to genuinely domain-specific hard rules that change routing or safety for that secondmate. +Natural-language summary and `scope:` text may contain parentheses and semicolons; keep the generated `(home: ...; scope: ...; projects: ...; added ...)` suffix intact so operational consumers resolve its explicit field markers. The `home:` path points to the seeded home containing `data/charter.md`; no extra registry pointer field is needed. The home-seeded `data/charter.md` is the sole owner of boilerplate idle-by-default behavior, the normal delegation lifecycle, and standard escalation contracts, so point to that charter rather than restating those contracts in the registry entry. The `scope:` field is used during intake. @@ -78,7 +79,7 @@ This section is the single owner of the secondmate sync and inherited-local-mate Before launch, `fm-spawn.sh --secondmate` locally fast-forwards the home to the primary firstmate checkout's current default-branch commit when it is safe; dirty, diverged, or in-flight homes launch unchanged with a warning. The locked session-start bootstrap sweep runs the same guarded fast-forward for every live secondmate home, discovered from `state/.meta` records with `kind=secondmate` (`data/secondmates.md` only backfills `home=` for older records). That no-fetch path is a purely local fast-forward of tracked files, never an origin fetch, and it never touches the gitignored operational dirs, so a secondmate's backlog, projects, and in-flight work are never disturbed; a linked worktree advances immediately, while a standalone clone that lacks the target receives firstmate updates through `/updatefirstmate`'s origin refresh. -The same launch and the same locked bootstrap sweep also propagate the primary's declared inherited local material: `config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, and the one shared captain-preference file `data/captain-shared.md`. +The same launch and the same locked bootstrap sweep also propagate the primary's declared inherited local material: `config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`, and the one shared captain-preference file `data/captain-shared.md`. Because these paths are gitignored, that propagation is a separate, primary-authoritative copy independent of the tracked-files fast-forward: it re-converges every live home whether or not its tracked files advanced, and it touches only the declared items. Propagation failures warn without blocking secondmate launch or session-start continuation, and the destination keeps whatever safely validated state the helper left behind. Inheritance copies the literal `config/crew-harness` file, so a secondmate's own crewmates use the primary's crewmate harness only when it names a concrete adapter such as `codex`; an unset or `default` value has nothing concrete to inherit, and the secondmate's own crewmates fall back to the secondmate's own or detected harness instead. @@ -99,7 +100,7 @@ Keep every `data/learnings.md` fully local by captain decision; route fleet-gene No AGENTS.md reread nudge is needed at spawn or respawn because the agent reads instructions fresh on launch; only the bootstrap sweep's running-home instruction-surface advance needs that AGENTS.md re-read. Bootstrap reports successful AGENTS.md re-read sends as `BOOTSTRAP_INFO:` and only emits `NUDGE_SECONDMATES:` when that send fails and needs retry. A separate, literal-content config reread is required whenever inherited `config/*` material changes under an already-running secondmate. -After each successful allowlisted config write, both the locked bootstrap convergence path and mid-session `bin/fm-config-push.sh` use the shared propagation report to build one per-home generation-specific private instruction file from the validated destination post-write bytes for only the allowlisted config items that actually changed for that home (`config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`), in deterministic allowlist order. +After each successful allowlisted config write, both the locked bootstrap convergence path and mid-session `bin/fm-config-push.sh` use the shared propagation report to build one per-home generation-specific private instruction file from the validated destination post-write bytes for only the allowlisted config items that actually changed for that home (`config/crew-dispatch.json`, `config/crew-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`), in deterministic allowlist order. Each changed path is printed with clear begin/end delimiters and the destination file's full exact new bytes unparsed, or the explicit token `ABSENT` when propagation removed the destination copy. The instruction uses only minimal framing that these are defaults/rules and do not remove judgment; it never includes SHA values, selected profiles, parsed summaries, or any other generated interpretation. `data/captain-shared.md` is not a config file and is never inlined into this instruction file or message. @@ -116,7 +117,7 @@ It uses the same live-home discovery and propagation helper as bootstrap, report `bin/fm-home-seed.sh` refuses to copy a missing or placeholder charter. Direct seed without a preexisting brief requires `FM_SECONDMATE_CHARTER`. -Run `bin/fm-home-seed.sh validate` when checking registry integrity; it refuses duplicate ids, duplicate homes, and nested or overlapping homes. +Run `bin/fm-home-seed.sh validate` when checking registry integrity; its header owns the complete validation and refusal mechanics. Seeding is transactional. If validation, cloning, no-mistakes initialization, or registry update fails, generated briefs, new homes, new project clones, and registry edits are rolled back. diff --git a/.agents/skills/stow/SKILL.md b/.agents/skills/stow/SKILL.md index 4c2c2a337ae..672894bd56d 100644 --- a/.agents/skills/stow/SKILL.md +++ b/.agents/skills/stow/SKILL.md @@ -10,56 +10,76 @@ metadata: # stow -Sweep this session for durable knowledge that only exists in conversation right now, and write it to the disk locations firstmate already prints in the next session-start context digest. -The goal is a session that is safe to reset or destroy because everything durable has already been captured. +Sweep this session for durable knowledge that exists only in conversation, then leave the next session with a compact current operating map rather than an accumulating journal. +This skill writes only through the existing Firstmate ownership and write boundaries. -## What it does +## Required startup-memory pass -1. **Sweep the session for uncaptured durable knowledge.** - Read back over this conversation and look for: - - Operational learnings: fleet-local facts and gotchas discovered while operating firstmate (a script's sharp edge, a harness quirk, a recurring false alarm and its real cause). - - Captain preferences expressed in passing: a working-style or approval preference the captain stated conversationally rather than through the destination selected by AGENTS.md's knowledge-routing table. - - Project-intrinsic facts discovered: build, test, release, or architecture facts about a project that belong in that project's own `AGENTS.md`. - - Decisions made: a standing choice the captain made this session that should outlive it. - - Undone next steps: anything left open that has not yet been filed as backlog work. +Every `/stow` invocation performs this complete pass, even when the session contains no new finding: -2. **Route each finding using AGENTS.md's knowledge-routing table.** - AGENTS.md (section 6, "Knowledge routing") is the single source of truth for where each kind of knowledge belongs. - Read that table and route each finding there instead of re-deriving the mapping here. +1. Run `bin/fm-startup-memory-budget.sh report` before considering a write. + Record its effective budget and each file's estimated-token total. + The helper's stable estimate is the documented conservative local approximation, not provider-exact accounting. + If it rejects the setting or a memory file, do not infer a default or silently continue. + Report that concrete exception and do not call the session reset-safe. +2. Read every current memory file completely: `data/captain.md`, `data/captain-shared.md`, and `data/learnings.md`. + Treat an absent local file as absent, not as an invitation to manufacture content. + In a primary home, all three are curation inputs under their existing ownership rules. + In a secondmate home, `data/captain-shared.md` is a read-only primary-owned input: count it, never edit it, and curate only the editable local files. +3. Build one whole-file retention plan before editing. + Retain, in order: current captain preferences, authority and safety boundaries, and recurring working style; stable home-local operating facts that repeatedly affect future work and are expensive to rediscover; then concise pointers to an existing authoritative report, project document, configuration, or backlog item. + Retain lower-priority material only while budget remains. +4. Consolidate every editable memory file as needed, not only the file apparently related to a new finding. + Prefer one concise current rule or authoritative pointer over duplicate prose. + Remove, merge, or route completed incident and release chronology, stale versions and paths, transient task state, resolved alternatives, old metrics, superseded claims, duplicates, and report-sized procedures. + Do not remove a unique current fact unless it is preserved directly elsewhere through a stronger existing owner. +5. Run `bin/fm-startup-memory-budget.sh report` again after the complete pass. + Finish at or below the effective budget unless a concrete inability remains. + A secondmate must explicitly report `primary-owned-shared-file-alone-exceeds-budget` when the inherited shared file alone exceeds its allowance, because local curation cannot resolve it. + Any other unresolved excess must identify the fact that cannot safely be removed or routed and why. + +A net increase is allowed only for a genuinely new current fact with no stronger owner. +Before allowing it, consolidate enough lower-priority material to remain within budget. +Never describe the session as reset-safe while the memory total is over budget or an exception is unresolved. + +## Knowledge sweep and routing -3. **Write within firstmate's existing write boundaries.** - This skill does not grant any new write permission; it only prompts firstmate to use the boundaries that already exist (AGENTS.md section 1): - - Captain preferences and fleet-local operational facts: hand-write directly to the destination selected by AGENTS.md's knowledge-routing table, using inspect-then-update every time. - Before writing, inspect the destination, find the existing bullet or section the finding duplicates or supersedes, and rewrite it in place rather than adding a new trailing entry. - `data/learnings.md` may not exist yet; create it on first local learning, in the same dated, evidence-backed, curated style as the captain-preference files. - - Project-intrinsic knowledge: never hand-write a project's `AGENTS.md`. - Route it through a normal ship task so a crewmate records it via `bin/fm-ensure-agents-md.sh` and commits it through that project's delivery pipeline, exactly as section 6 describes. - If the fleet is live, delegate this to a crewmate rather than doing it inline. - - Knowledge generalizable to every firstmate user: this repo's own `AGENTS.md` (or other shared, tracked material), shipped through the normal branch -> no-mistakes -> PR -> captain-merge pipeline for this repo (section 1), never hand-committed straight to `main`. - - Task-scoped notes: inspect the relevant backlog item with `tasks-axi show --full`, judge whether the new note is new, duplicate, superseding, or obsolete, then write a considered replacement body with `tasks-axi update --body-file `. - When the replacement intentionally supersedes prior state that should remain recoverable, add `--archive-body` to that update command so the prior body stays recoverable without copying it into the replacement. +1. **Sweep the session for uncaptured durable knowledge.** + Look for operational learnings, captain preferences expressed in passing, project-intrinsic facts, standing decisions, and undone next steps. +2. **Route each finding using AGENTS.md's knowledge-routing table.** + AGENTS.md section 6 is the source of truth for destinations. + Do not re-derive or duplicate that mapping here. +3. **Write within the existing boundaries.** + - Captain preferences and fleet-local operational facts belong in the destination selected by AGENTS.md after the required whole-file curation pass. + Create `data/learnings.md` only for a genuinely new local learning with no stronger owner. + - In a primary home, curate shared captain preferences only under the existing primary-authoritative shared-preference contract. + In a secondmate home, route a newly discovered shared preference to the main firstmate through marked status or a document pointer instead of editing the inherited file. + - Project-intrinsic knowledge never goes directly into a project's `AGENTS.md`. + Route it through a normal ship task so a crewmate records it with `bin/fm-ensure-agents-md.sh` and the project's delivery path. + - Knowledge general to every Firstmate user belongs in this repo's shared tracked material through the normal branch, no-mistakes, PR, and captain-merge path. + - For task-scoped notes, inspect the item with `tasks-axi show --full`, classify the change as new, duplicate, superseding, or obsolete, then use a considered replacement body through `tasks-axi update --body-file `. + Use `--archive-body` when recoverability matters. Never append. - If hand-editing `data/backlog.md` per the active backend, make the same inspect-then-update edit in place. - - Undone next steps: file each as a queued backlog item (section 10), with `blocked-by` recorded if it genuinely depends on something else. + - File each undone next step as a queued backlog item with a genuine `blocked-by` dependency when applicable. +4. **Use inspect-then-update.** + For every retained fact, ask which current statement it supersedes, whether it can be a one-sentence rewrite, and whether a stale entry should be deleted, retired, or routed to an existing stronger owner. + The only graduation moves are promotion to tracked shared material through a PR, folding a learning into the captain-preference destination selected by AGENTS.md, or deletion of a stale entry. + Do not invent another graduation path. + +## Completion receipt + +Report the outcome in plain captain-facing language with all of these facts: -4. **Curate with inspect-then-update.** - Every write starts by reading the current destination and deciding how the finding changes what is already there. - Use this checklist before writing: - - Which existing bullet, section, or task body does this supersede? - - Can this be a one-sentence rewrite instead of a new entry? - - Should an older bullet or note be deleted, retired, or archived because it is now obsolete? - When a finding overlaps or supersedes something already on disk, rewrite or prune the existing entry instead of piling on a new one. - Graduation moves are limited to exactly three: promote a learning to the shared `AGENTS.md` via PR, fold it into the captain-preference destination selected by AGENTS.md, or delete a stale entry. - Do not invent other graduation paths. +- effective startup-memory budget and total estimated tokens before and after; +- one or more actions for each of `data/captain.md`, `data/captain-shared.md`, and `data/learnings.md`: `unchanged`, `added`, `rewritten`, `pruned`, or `routed`; +- each durable finding filed outside memory and its authoritative owner; +- every unresolved exception, including a primary-owned shared-file constraint in a secondmate home; +- whether the session is safe to reset, only when all durable findings are captured and the post-pass result is within budget with no exception. -5. **Report to the captain.** - Summarize, in plain outcome language (section 9): what was stowed and where, what was filed to the backlog, and whether the session is now safe to reset or destroy - i.e. whether every durable finding from this sweep now lives on disk rather than only in this conversation. - If something could not be captured yet (for example, project-intrinsic knowledge waiting on a crewmate to land it), say so explicitly rather than reporting the session fully safe. +Do not hide an over-budget result behind a reset-safe claim. ## Scope exclusion: no skill storage -`/stow` must **never** store, create, or edit a skill as a destination for any finding. +`/stow` must never store, create, or edit a skill as a destination for any finding. There is no "graduate this to a skill" move in this skill's routing. -This is a deliberate, standing exclusion, not an oversight: even with the two-tier skill layout, a stow sweep is a memory-routing operation, not a way to author or mutate skills. -Writing learnings into either `.agents/skills/` or public `skills/` would still risk mixing fleet-local material with shared firstmate behavior or standalone installer-facing behavior. -Until a human deliberately scopes a skill change as firstmate repo work, route generalizable knowledge to the shared `AGENTS.md` (or other shared, tracked material) via the pipeline, and fleet-local knowledge to `data/`, never to a skill. +Until a human deliberately scopes a skill change as Firstmate repository work, route generalizable knowledge to shared tracked material through its pipeline and fleet-local knowledge to `data/`, never to `.agents/skills/` or public `skills/`. diff --git a/.pi/extensions/fm-calm.ts b/.pi/extensions/fm-calm.ts index f78c1b5acd9..1fb9cf12c48 100644 --- a/.pi/extensions/fm-calm.ts +++ b/.pi/extensions/fm-calm.ts @@ -1,9 +1,11 @@ // Firstmate's home-persistent Pi transcript presentation toggle. // // Verified against Pi 0.81.1 and 0.82.0, which expose built-in ToolDefinitions, per-slot -// renderers, renderShell: "self", session_start replacement reasons, -// ExtensionUIContext.setToolsExpanded(), setWorkingVisible(), and -// setHiddenThinkingLabel(). The focused tests pin those assumptions but never reject a +// renderers, renderShell: "self", session_start replacement reasons, agent_start and +// agent_settled, ExtensionUIContext.setToolsExpanded(), setWorkingVisible(), setWidget() +// with a disposable component factory, and setHiddenThinkingLabel(). +// ./lib/fm-calm-working-ship.ts owns the animated working presentation this file +// installs. The focused tests pin those assumptions but never reject a // newer Pi solely for its version. The collapsed-thinking and operational-user // presentation adapters probe the exact API they patch and degrade independently with a // diagnostic (see installCalmPresentationAdapter below) if a future Pi removes it; Pi @@ -21,6 +23,7 @@ import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import type { ExtensionAPI, + ExtensionUIContext, ToolDefinition, ToolRenderResultOptions, } from "@earendil-works/pi-coding-agent"; @@ -37,6 +40,11 @@ import { Box, Container, getKeybindings, type Component } from "@earendil-works/ import type { TSchema } from "typebox"; import { installCalmAssistantLayout } from "./lib/fm-calm-assistant-layout.ts"; import { installCalmOperationalUserLayout } from "./lib/fm-calm-operational-user-layout.ts"; +import { + CALM_WORKING_SHIP_WIDGET_KEY, + createCalmWorkingShipAnimation, + createCalmWorkingShipWidget, +} from "./lib/fm-calm-working-ship.ts"; import { calmPresentationHides, calmPresentationIsActive, @@ -93,6 +101,36 @@ export default function (pi: ExtensionAPI) { let exportRendering = false; let removeTerminalInputHandler: (() => void) | undefined; + // One logical agent run, tracked from agent_start through agent_settled rather than + // from turns or tool calls, so the boat never flickers between tool calls, automatic + // continuations, retries, or compaction that stay inside the same run. + let agentRunActive = false; + let workingShipShown = false; + // One animation instance per extension lifetime. Hiding the working widget freezes + // this state; the next working period resumes it. session_start resets it so a fresh + // Pi session starts at the normal initial position. Never module-global. + const workingShipAnimation = createCalmWorkingShipAnimation(); + + // Single owner of Calm's working-row presentation choice. The widget is only created + // or removed on a real transition, so repeated starts cannot duplicate its timer. + const applyWorkingPresentation = ( + ui: ExtensionUIContext, + forceStockVisibility = false, + ): void => { + const showShip = agentRunActive && calmPresentationIsActive(); + if (showShip !== workingShipShown) { + workingShipShown = showShip; + ui.setWidget( + CALM_WORKING_SHIP_WIDGET_KEY, + showShip + ? (tui) => createCalmWorkingShipWidget(tui, workingShipAnimation) + : undefined, + ); + ui.setWorkingVisible(!showShip); + } else if (forceStockVisibility && !showShip) { + ui.setWorkingVisible(true); + } + }; const fmHome = process.env.FM_HOME || process.env.FM_ROOT_OVERRIDE || root; const configDirectory = process.env.FM_CONFIG_OVERRIDE || resolve(fmHome, "config"); @@ -241,7 +279,11 @@ export default function (pi: ExtensionAPI) { setCalmPresentation(loadCalmPreference()); setCalmStockExportRendering(false); publishPresentationState(); - ctx.ui.setWorkingVisible(true); + agentRunActive = false; + workingShipShown = false; + // A genuine new session lifetime starts the boat at the normal initial position. + workingShipAnimation.reset(); + applyWorkingPresentation(ctx.ui, true); ctx.ui.setHiddenThinkingLabel(calmPresentationIsActive() ? "" : undefined); ctx.ui.setStatus("firstmate-calm", undefined); removeTerminalInputHandler?.(); @@ -271,6 +313,22 @@ export default function (pi: ExtensionAPI) { }); }); + pi.on("agent_start", (_event, ctx) => { + agentRunActive = true; + applyWorkingPresentation(ctx.ui); + }); + + // agent_settled is emitted from a finally block, so it also covers abort and failure. + pi.on("agent_settled", (_event, ctx) => { + agentRunActive = false; + applyWorkingPresentation(ctx.ui); + }); + + pi.on("session_shutdown", (_event, ctx) => { + agentRunActive = false; + applyWorkingPresentation(ctx.ui); + }); + pi.registerCommand("calm", { description: "Toggle Firstmate's supported conversation-only transcript presentation.", handler: async (_args, ctx) => { @@ -278,7 +336,7 @@ export default function (pi: ExtensionAPI) { persistCalmPreference(active); setCalmPresentation(active); publishPresentationState(); - ctx.ui.setWorkingVisible(true); + applyWorkingPresentation(ctx.ui, true); ctx.ui.setHiddenThinkingLabel(active ? "" : undefined); ctx.ui.setStatus("firstmate-calm", undefined); diff --git a/.pi/extensions/lib/fm-calm-working-ship.ts b/.pi/extensions/lib/fm-calm-working-ship.ts new file mode 100644 index 00000000000..390e28baebf --- /dev/null +++ b/.pi/extensions/lib/fm-calm-working-ship.ts @@ -0,0 +1,243 @@ +// Firstmate's Calm-only animated working presentation. +// +// Calm replaces Pi's stock working row with a tiny SSHHIP-derived boat while one +// logical agent run is active. This module owns only the sprite geometry, the bounce +// track, the two animation cadences, the session-scoped freeze/resume state, and the +// temporary TUI widget; `.pi/extensions/fm-calm.ts` owns when the presentation is +// installed and removed, and stays the sole caller of setWorkingVisible(). +// docs/calm.md owns the captain-facing contract. +// +// Cadence: one scheduler drives two logically independent clocks. Every tick advances +// the water phase, and only every CALM_WORKING_SHIP_TICKS_PER_MOVE-th tick moves the +// boat, so the water visibly ripples several times between boat steps and the boat +// itself reads as calm. Both clocks stop together when the widget is disposed. Ticks, +// not wall-clock timestamps, drive every state change, so tests can seek time exactly. +// +// Continuity: one extension-owned animation instance survives hide/show within the same +// Pi process and Calm extension lifetime. Disposing the widget freezes column, +// direction, water phase, and tick cadence without advancing them for hidden wall +// time. The next working period resumes from that exact logical state. A fresh session +// or new extension lifetime calls reset() and starts at the normal initial position. +// State is never a module-level or process-global singleton. +// +// Verified against Pi 0.81.1 declarations and the Pi 0.82.0 CLI, which expose +// ExtensionUIContext.setWidget() with a component factory, per-widget dispose(), and +// TUI.requestRender(). Pi renders a widget through Component.render(width), so this +// module recomputes its track from that width on every frame instead of caching a +// terminal size that a resize would invalidate. A resize while the boat is hidden is +// applied on the first resumed frame through the same clamp path. +import type { Component, TUI } from "@earendil-works/pi-tui"; + +// The hull is symmetric and replaces waves on its row rather than adding a third row. +const HULL = "\\__/"; +// A mainsail extends aft of the mast, so it trails behind the bow relative to travel. +const SAIL_RIGHT = "<|"; +const SAIL_LEFT = "|>"; +// Centers the two-cell sail over the four-cell hull. +const SAIL_OFFSET = 1; +const HULL_WIDTH = HULL.length; +const SAIL_WIDTH = SAIL_RIGHT.length; + +// Bounded deterministic fixed-cell water phases. Every entry is exactly one column, so +// advancing the phase ripples the surface without changing visible width or row count. +const WAVE_CYCLE = ["~", "~", "-", "~"] as const; + +// Standard ANSI foreground codes only: no theme lookup, bright variant, or 256/RGB. +const BLUE = "\u001b[34m"; +const YELLOW = "\u001b[33m"; +// Restores the default foreground so color never bleeds into padding or later frames. +const RESET = "\u001b[39m"; + +export const CALM_WORKING_SHIP_WIDGET_KEY = "firstmate-calm-working-ship"; +/** Scheduler period. One tick advances the water by one phase. */ +export const CALM_WORKING_SHIP_TICK_MS = 220; +/** Boat moves one column every Nth tick, so it travels at 220 * 4 = 880ms per column. */ +export const CALM_WORKING_SHIP_TICKS_PER_MOVE = 4; + +export type CalmWorkingShipAnimation = { + /** Render one frame that exactly fits `width`, clamping the track to it first. */ + render(width: number): string[]; + /** Advance one scheduler tick: water every tick, boat on its slower cadence. */ + tick(): void; + restoreLastRendered(): void; + /** Restore the normal initial column, direction, water phase, and cadence. */ + reset(): void; + /** + * Clamp the frozen column and direction to `width` without advancing time. + * Used when a terminal resize lands while the working presentation is hidden. + */ + clampToWidth(width: number): void; + /** Current hull column, exposed for deterministic motion assertions. */ + position(): number; + /** Current travel direction: 1 travelling right, -1 travelling left. */ + direction(): number; + /** Current water phase, exposed for deterministic ripple assertions. */ + waterPhase(): number; +}; + +/** Longest hull start column that still fits the sprite in `width` usable cells. */ +function trackSpan(width: number): number { + if (width >= HULL_WIDTH) return width - HULL_WIDTH; + if (width >= SAIL_WIDTH) return width - SAIL_WIDTH; + return 0; +} + +export function createCalmWorkingShipAnimation(): CalmWorkingShipAnimation { + let position = 0; + let direction = 1; + let span = 0; + let phase = 0; + let ticks = 0; + let renderedPosition = position; + let renderedDirection = direction; + let renderedSpan = span; + let renderedPhase = phase; + let renderedTicks = ticks; + + // Reversing the moment the boat lands on an endpoint means the endpoint frame itself + // already shows the new heading, so no frame at or after a bounce shows the old sail. + const settleDirectionAtEdges = (): void => { + if (span <= 0) return; + if (position >= span) direction = -1; + else if (position <= 0) direction = 1; + }; + + const applyWidth = (width: number): void => { + if (width <= 0) { + span = 0; + position = 0; + return; + } + span = trackSpan(width); + position = Math.min(position, span); + settleDirectionAtEdges(); + }; + + const commitRenderedState = (): void => { + renderedPosition = position; + renderedDirection = direction; + renderedSpan = span; + renderedPhase = phase; + renderedTicks = ticks; + }; + + const restoreLastRenderedState = (): void => { + position = renderedPosition; + direction = renderedDirection; + span = renderedSpan; + phase = renderedPhase; + ticks = renderedTicks; + }; + + /** One colored run of water covering absolute columns [from, from + count). */ + const water = (from: number, count: number): string => { + if (count <= 0) return ""; + let cells = ""; + for (let column = from; column < from + count; column += 1) { + cells += WAVE_CYCLE[(column + phase) % WAVE_CYCLE.length]; + } + return `${BLUE}${cells}${RESET}`; + }; + + const boat = (text: string): string => `${YELLOW}${text}${RESET}`; + + return { + position: () => position, + direction: () => direction, + waterPhase: () => phase, + + restoreLastRendered: restoreLastRenderedState, + + reset(): void { + position = 0; + direction = 1; + span = 0; + phase = 0; + ticks = 0; + commitRenderedState(); + }, + + clampToWidth(width: number): void { + applyWidth(width); + }, + + tick(): void { + ticks += 1; + phase = (phase + 1) % WAVE_CYCLE.length; + if (ticks % CALM_WORKING_SHIP_TICKS_PER_MOVE !== 0) return; + if (span <= 0) { + position = 0; + return; + } + position = Math.min(span, Math.max(0, position + direction)); + settleDirectionAtEdges(); + }, + + render(width: number): string[] { + if (width <= 0) return []; + + // A resize lands here before the next frame, so recompute and clamp the track + // immediately rather than trusting a position measured against the old width. + applyWidth(width); + + const sail = direction >= 0 ? SAIL_RIGHT : SAIL_LEFT; + + let frame: string[]; + if (width < SAIL_WIDTH) { + // Too narrow for even the sail: a deterministic single row of water. + frame = [water(0, width)]; + } else if (width < HULL_WIDTH) { + // Too narrow for the hull: the sail alone rides the water row. + frame = [ + water(0, position) + + boat(sail) + + water(position + SAIL_WIDTH, width - position - SAIL_WIDTH), + ]; + } else { + frame = [ + " ".repeat(position + SAIL_OFFSET) + boat(sail), + water(0, position) + + boat(HULL) + + water(position + HULL_WIDTH, width - position - HULL_WIDTH), + ]; + } + + commitRenderedState(); + return frame; + }, + }; +} + +/** + * Build the temporary Calm working widget bound to one caller-owned animation. + * Pi disposes the previous component before installing a replacement under the same + * key and when it clears extension widgets, so the single scheduler driving both + * cadences cannot outlive the widget or duplicate. Disposing freezes the shared + * animation in place; the next widget bound to the same animation resumes without + * applying hidden wall time. + */ +export function createCalmWorkingShipWidget( + tui: TUI, + animation: CalmWorkingShipAnimation = createCalmWorkingShipAnimation(), +): Component & { dispose(): void } { + let disposed = false; + const timer = setInterval(() => { + if (disposed) return; + animation.tick(); + tui.requestRender(); + }, CALM_WORKING_SHIP_TICK_MS); + // The animation must never keep Pi's process alive on its own. + timer.unref?.(); + + return { + render: (width) => (disposed ? [] : animation.render(width)), + // Every frame is rebuilt from fixed standard ANSI codes, so there is no cache. + invalidate: () => {}, + dispose: () => { + if (disposed) return; + disposed = true; + clearInterval(timer); + animation.restoreLastRendered(); + }, + }; +} diff --git a/AGENTS.md b/AGENTS.md index 78eb851a5b5..902e81a7599 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Hard rules, in priority order: Those paths never authorize forcing, stashing, discarding unlanded work, or hand-writing a project's `AGENTS.md`. Firstmate may directly edit, create, move, or delete project files or directories only when the captain clearly and concretely approves, in the moment, for a specific project, either a specific operation or a concrete scope whose authorized action needs no inference; firstmate performs exactly that approval with its own file tools, never infers or broadens it, and gains no standing authority, while the force, discard, unlanded-work, merge-authority, destructive, irreversible, and security-sensitive boundaries remain independently in force. 2. **Never merge a PR without the captain's explicit word.** - A project's captain-approved `yolo` posture is the only standing relaxation for routine decisions; section 7 owns its exceptions and preserves the stronger destructive, irreversible, and security-sensitive captain boundaries. + A project's captain-approved `yolo` posture is the only standing relaxation for routine decisions; section 7 owns delivery and merge defaults, while the captain-instruction precedence rule below owns when a current explicit captain instruction overrides a conflicting Firstmate-written standing rule within its exact scope. 3. **Never tear down unlanded work.** Uncommitted changes are never landed, and `bin/fm-teardown.sh` owns the complete landed-work test. Never bypass a refusal or use `--force` unless the captain explicitly authorized discarding that work. @@ -70,6 +70,7 @@ config/secondmate-harness harness the PRIMARY uses to launch SECONDMATE agents, config/backlog-backend backlog backend override; LOCAL, gitignored; absent or "tasks-axi" = default tasks-axi backend, "manual" = force routine backlog updates to hand-editing; inherited by secondmate homes (section 10) config/backend runtime session-provider backend override for new tasks; LOCAL, gitignored; absent = falls through to runtime auto-detection (the runtime firstmate itself is executing inside), then tmux; tmux is the verified reference backend (docs/tmux-backend.md), while herdr, zellij, orca, and cmux are experimental spawn backends (docs/herdr-backend.md, docs/zellij-backend.md, docs/orca-backend.md, docs/cmux-backend.md) - herdr and cmux can also be selected by runtime auto-detection, zellij and orca never are (always explicit), and codex-app is not accepted; see docs/codex-app-backend.md; inherited by secondmate homes under the primary-authoritative contract in secondmate-provisioning config/calm Pi Calm presentation preference; LOCAL, gitignored, and not inherited; see docs/configuration.md "Pi Calm preference" +config/startup-memory-budget primary-authoritative per-home startup-memory budget; LOCAL, gitignored, materialized as 7,500 estimated tokens by locked primary bootstrap and inherited into secondmate homes; see docs/configuration.md "Startup memory budget" config/herdr-presentation-spaces optional presence flag for Herdr's default-off disposable single-task visual projection; LOCAL, gitignored; inherited by secondmate homes; see docs/herdr-backend.md "Optional presentation spaces" config/cmux-socket-password optional cmux control-socket password; LOCAL, gitignored; read fresh on every cmux CLI call and passed through without ever overriding an operator's own ambient CMUX_SOCKET_PASSWORD when absent (docs/cmux-backend.md "Setup") config/wedge-alarm optional away-mode wedge-alarm active-alert directives; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md @@ -107,6 +108,7 @@ state/ volatile runtime signals; gitignored x-inbox/ generated X-mode pending mention payloads; fmx-respond drains it (section 14) x-context/ generated X-mode durable per-request reply context and one-wake offer markers, keyed by request_id; survives inbox cleanup and expires within seven days (section 14; bin/fm-x-lib.sh) x-outbox/ generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14) + public-followup/ generated private transport for promised public replies: commitment registrations, typed terminal-result inbox, accepted/rejected ledgers (section 14; bin/fm-public-followup.sh) x-poll.error x-poll.claim-error generated X-mode relay and offer-claim diagnostic dedupe markers .wake-queue durable queued wakes: epochseqkindkeypayload .afk durable away-mode flag; present = sub-supervisor may inject escalations (set by /afk, cleared on user return) @@ -169,18 +171,21 @@ If static `config/crew-harness` or `config/secondmate-harness` names an unverifi `docs/configuration.md` owns dispatch-profile and runtime-backend schemas, `bin/fm-harness.sh` owns static resolution, and `bin/fm-spawn.sh` owns launch flags and fail-closed validation. When dispatch profiles exist, consult them at every crewmate or scout intake and pass the resolved concrete profile required by `fm-spawn`. Routing precedence is an explicit per-task captain override, then the best-fit configured rule, then the configured default, then the static crewmate harness. -Firstmate alone resolves a matched profile array: run `quota-axi --json` at that intake, evaluate every configured candidate against that current output, and choose with inspectable real headroom including quota-window pace. -Account for every candidate; if any harness/model/provider relationship, applicable quota data, or interpretation cannot be established, stop and report that candidate instead of omitting it, guessing, falling back, or calling the result quota-informed. +Firstmate alone resolves a matched profile array: run `quota-axi --json` at that intake, evaluate every configured candidate against that current output, and choose with inspectable effective headroom and usable runway, using pace and reserve only later when needed. +Account for every candidate with the catalog evidence, provider relationship, applicable quota and authentication facts, remaining uncertainty, fit and reasoning class, and the headroom, runway, and later pace or reserve evidence used in selection; never omit a candidate, guess, fall back silently, or call the result quota-informed without them. +Establish model support and provider family from that harness's own authoritative catalog, then read `quota-axi` at the granularity the vendor actually supplies: provider-level or all-model evidence applies to every model established in that family, and a named-model window bounds only that model. +Missing model-level quota, a missing authentication source, unmeasurable headroom, or unmodeled authentication is disclosed uncertainty that keeps a candidate eligible, never a credential or login escalation. +Only concrete contradictory evidence blocks a candidate, such as an authoritative catalog proving the model unsupported or proof that the credential selected for that surface is unusable; never infer a credential store, provider family, or quota mapping from a harness, model, or source name, and never launch another harness's CLI to judge a candidate. Preserve malformed profile configuration as an actionable error rather than selecting around it. When every candidate is tight, preserve the captain's strongest-reasoning class rather than silently downgrading it solely to conserve quota; stop and report the tight choice if that class cannot proceed. -Break genuine headroom ties without array-order or harness bias. +Break genuine evidence ties without array-order or harness bias. `quota-axi` owns how model or product windows relate to bounding account windows and remains data-only. -Load `quota-array-dispatch` before choosing among a matched profile array; that skill is the single owner of the pace-aware selection procedure. +Load `quota-array-dispatch` before choosing among a matched profile array; that skill is the single owner of the completion-aware selection procedure. The generic effort fallback and its precedence are owned by `harness-adapters`: explicit captain and standing configured effort win; otherwise use low for well-understood explicit work, xhigh for ambiguous investigation or design, intermediate levels proportionally, and never max without explicit captain preference. Do not add model-specific versions of that policy. `secondmate-provisioning` owns secondmate harness pins and inherited local material, while `harness-adapters` owns the harness consequences. -Dispatch only on a backend that `fm-spawn` validates as spawn-capable. +Dispatch only on a backend that `fm-spawn` validates as spawn-capable; pass an explicit per-spawn `--backend` only under that exact task's own authority, never as later-task precedent (selection contract: [`docs/configuration.md`](docs/configuration.md) "Runtime backend"). A missing dependency, authentication failure, unsupported backend, or version refusal is a blocker; never silently retry on another backend. ## 5. Recovery @@ -287,11 +292,12 @@ The path's worker, automated gates, and captain approval remain authoritative: Delivery mode and `yolo` are orthogonal. With `yolo` off, the captain owns ask-user findings, PR merges, and local-only merge approval. -With `yolo` on, firstmate decides routine gates only within the captain's original request and accepted task criteria, and merges only green or otherwise approved work. +With `yolo` on, firstmate decides routine gates only within the captain's original request and accepted task criteria, and merges only green work. Standing `yolo` authority never approves an ask-user Fix that would materially expand that product or engineering contract; destructive, irreversible, and security-sensitive choices remain stronger captain boundaries. Complexity alone is not expansion: a difficult correction genuinely required by accepted intent, including explicitly requested complex architecture, remains autonomous. Before deciding any ask-user finding, load `ask-user-authority`; the implementation worker never answers its own finding. Never merge a red PR. +Without a current explicit captain instruction that states the concrete merge, that default stands, and standing `yolo` cannot authorize a red merge; section 1 owns when such an instruction overrides a Firstmate-written standing rule within its exact scope. Use `bin/fm-pr-merge.sh` for every task PR merge so merge metadata is recorded, and use `bin/fm-merge-local.sh` for approved local-only landing; never call a lower-level merge command around their guards. After an autonomous merge, give the captain a one-line full-URL or local-main outcome. @@ -302,6 +308,13 @@ The task worker that starts a no-mistakes run drives the pipeline and owns every Firstmate never invokes `no-mistakes axi respond` for a crew-owned run. Once validation starts, prefer routing new requirements to follow-up work rather than expanding the current task, unless a new requirement completely invalidates the work being validated; however, the smallest downstream changes needed to keep already accepted product or engineering behavior correct, add behavioral tests where an executable contract exists, or keep documentation accurate remain within the current task even when they touch files not named at intake, and corrections required to satisfy already accepted intent are not new requirements. +Only a current, explicit captain instruction that completely invalidates the work being validated keeps the task with the same worker instead of routing it to follow-up work or handing it to a replacement. +That worker cancels the active run through no-mistakes axi's supported abort command and confirms through axi status that the run has stopped before changing any code. +The worker then follows `branch_sync.next_action` from structured axi status: use axi sync's supported guarded recovery only when its code is `recover_custody`, and otherwise proceed only when structured status confirms that branch ownership is already returned and no recovery is required. +Custody recovery settles branch ownership, not content: the worker must replace the obsolete work from the correct pre-invalidation base rather than building on top of the recovered-but-obsolete head, keeping the obsolete run's own pipeline-fix commits out of what gets validated and shipped. +Apart from that single supported abort, do not hand-edit, commit, restart, or start a second validation run while the obsolete run still owns the branch. +Once ownership is settled, validate exactly once against that final head so no obsolete or intermediate head is ever treated as authoritative. + An ask-user finding returns as `needs-decision`; firstmate decides only when the configured authority permits, otherwise escalates to the captain. Send the same worker one exact decision naming the decision key, step, action, affected finding IDs, instructions where needed, and exact response command. Require the matching `resolved` event, forbid `--yes`, and require the worker to process every synchronous return until completion or a genuinely new escalation. @@ -309,7 +322,7 @@ Resume fleet supervision immediately after the decision lands. Judge validation by the current-code-matched run step through `bin/fm-crew-state.sh`, not by shell liveness or the last status event. Running, fixing, or CI states remain working; parked approval or fix-review states require the worker to follow the active gate help; passed or checks-passed is done; failed or cancelled is failed. -A worker hand-editing, committing, aborting, or restarting during an active validation run duplicates pipeline ownership; steer it back to the gate response flow. +A worker hand-editing, committing, aborting, or restarting during an active validation run duplicates pipeline ownership outside the supersession sequence above; steer it back to the gate response flow. The worker reports the PR when CI first becomes green rather than waiting for merge monitoring to finish. ### PR ready, landing, and teardown @@ -361,7 +374,7 @@ Handle actionable wakes as follows: 4. For `heartbeat:`, review the whole fleet from the structured fleet view, reconcile suspicious tasks and PR state, update the backlog, and never report an unchanged fleet as progress. When any wake reports a merged PR for a project cloned in this home, refresh that clone through the guarded fleet-sync path. -When X-linked work reaches a milestone or terminal state, load `fmx-respond`; before terminal teardown, always post the final completion follow-up so the link clears even if earlier follow-ups were spent. +When X-linked work reaches a milestone or terminal state, load `fmx-respond`; before terminal teardown, use its promised-final reconciliation when a typed public commitment exists, otherwise post the final completion follow-up so the link clears even if earlier follow-ups were spent. A secondmate's idle endpoint is healthy, and parent supervision relies on its routed status rather than treating a quiet pane as stale. Waiting on a healthy supervision cycle is silent; empty polls, elapsed time, and no-change updates are not captain-facing progress. @@ -482,7 +495,7 @@ It performs guarded fast-forward updates of firstmate and registered secondmate These skills are not captain-invocable; load them only at their precise triggers. -- `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap section prints an actionable diagnostic line (`MISSING:`, `MISSING_MANUAL:`, `BACKEND_INVALID:`, `NEEDS_GH_AUTH`, `TANGLE:`, `CREW_DISPATCH: invalid`, `FLEET_SYNC:`, `PR_CHECK_MIGRATION:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `NUDGE_SECONDMATES:`, or `FMX:`); silence and `BOOTSTRAP_INFO:` need no load. +- `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap section prints an actionable diagnostic line (`MISSING:`, `MISSING_MANUAL:`, `BACKEND_INVALID:`, `NEEDS_GH_AUTH`, `TANGLE:`, `STARTUP_MEMORY_BUDGET:`, `CREW_DISPATCH: invalid`, `FLEET_SYNC:`, `PR_CHECK_MIGRATION:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `NUDGE_SECONDMATES:`, or `FMX:`); silence and `BOOTSTRAP_INFO:` need no load. - `diagnostic-reasoning` - load before scoping a reported bug and before acting on a diagnostic report. - `ask-user-authority` - load before deciding any ask-user finding, regardless of the project's `yolo` posture. - `quota-array-dispatch` - load before choosing among a matched crew-dispatch profile array from current quota-axi output. @@ -493,7 +506,7 @@ These skills are not captain-invocable; load them only at their precise triggers - `stuck-crewmate-recovery` - load when the session-start digest reports an ordinary direct report's endpoint dead or its metadata has no window, or after a stale wake, looping pane, repeated confusion, an answered-by-brief question, an unresponsive crewmate, or a failed steer. - `secondmate-provisioning` - load before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited local material into, or retiring a secondmate home, and before editing `data/secondmates.md`. - `decision-hold-lifecycle` - load before treating an investigation or visual review as complete, before ending a visual review that exposed a decision, and when recording or routing the captain's answer. -- `fmx-respond` - load on an `x-mention ` `check:` wake to handle the mention, on an `x-mode-error ...` `check:` wake to report the X-mode configuration blocker, and on any milestone or terminal wake for an X-mode-linked task before posting its completion follow-up; relevant only when X mode is on. +- `fmx-respond` - load on an `x-mention ` `check:` wake to handle the mention, on an `x-mode-error ...` `check:` wake to report the X-mode configuration blocker, on a `public-followup ...` `check:` wake or a startup-surfaced public commitment, and on any milestone or terminal wake for an X-mode-linked task before posting its completion follow-up; relevant only when X mode is on. - `firstmate-codexapp` - load before coordinating a visible Codex Desktop thread, evaluating a Codex App backend request, or reconciling Codex Desktop host-tool smoke evidence for Firstmate work. - `firstmate-coding-guidelines` - load before changing firstmate's shared, tracked material, as defined by section 1's list, whether editing directly or briefing a crewmate for a firstmate-repo task. @@ -505,7 +518,20 @@ That token is consent for public replies and normal reversible lifecycle actions An X-only home still requires the live supervision cycle so mentions can wake it without fleet work. On an `x-mention ` or `x-mode-error ...` check wake, load `fmx-respond`, which owns classification, public-safety policy, reply or dismissal, task linking, and follow-ups. -For every X-linked terminal outcome, load that owner and post the final completion follow-up before teardown, regardless of earlier milestone follow-ups. +For every X-linked terminal outcome, load that owner and use the promised-final reconciliation when a typed public commitment exists, otherwise post the final completion follow-up before teardown. + +A promised final public reply is durable state, never conversation memory. +Load `fmx-respond` before promising one, on a `public-followup ...` check wake, and whenever the session-start digest lists a public commitment awaiting delivery. +Only the home holding the relay consent and thread binding ever posts it, so never ask a secondmate or crewmate to find the thread or send the reply, and never recover a terminal result by reading a `done:` sentence. + +## Captain instruction precedence + +A current, explicit, concrete captain instruction overrides any conflicting standing rule written above. +The instruction must be specific and recent: it must identify the concrete action, object, or bounded set it governs. +Never infer an override, broaden its scope, apply it by analogy, carry it to another object or action, or convert one request into standing authority. +Ambiguous scope or conflict still requires one concise clarification before action. +Destructive, irreversible, security-sensitive, discard, and merge actions still require the captain to state that concrete action explicitly; once the captain does so and higher-priority instructions permit it, a conflicting Firstmate-written rule must not rigidly block the action. +Standing `yolo` authority is not a substitute for a current explicit captain instruction where an explicit action is required. ## Maintaining this file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c3a1cab183..effd31a8912 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,7 +47,7 @@ See the [no-mistakes quick start](https://kunchenguid.github.io/no-mistakes/star Test scripts and helpers in `tests/` are plain bash too. `bin/fm-lint.sh` must pass: it is the single owner of the lint definition (the shellcheck file set, config, and pinned shellcheck version), and both CI and the no-mistakes pre-push gate run it, so local and CI can never diverge. It pins one exact shellcheck version and refuses to run under any other; print it with `bin/fm-lint.sh --required-version` and install that build locally. -- Changes to harness adapters (detection in `bin/fm-harness.sh`, launch and hook mechanics in `bin/fm-spawn.sh`, busy signatures in `bin/fm-watch.sh` and `bin/fm-tmux-lib.sh`, cleanup in `bin/fm-teardown.sh`, and facts in `.agents/skills/harness-adapters/SKILL.md`) must be verified empirically against the real harness, never written from documentation alone. +- Changes to harness adapters (detection in `bin/fm-harness.sh`, launch and hook mechanics in `bin/fm-spawn.sh`, semantic busy sources and trust gates in `bin/fm-busy-lib.sh`, delivery-only rendered guards in `bin/fm-tmux-lib.sh`, cleanup in `bin/fm-teardown.sh`, and facts in `.agents/skills/harness-adapters/SKILL.md`) must be verified empirically against the real harness, never written from documentation alone. - Changes to runtime session backends (`bin/fm-backend.sh`, `bin/backends/`, and the scripts that dispatch through them) keep current setup and limits in the relevant backend guide and active empirical evidence in [`docs/verification/runtime-backends.md`](docs/verification/runtime-backends.md). - [`docs/documentation-audiences.md`](docs/documentation-audiences.md) and its machine-consumed inventory own prose classification; run `bin/fm-doc-audience-check.sh` after documentation changes. - In Markdown, put each full sentence on its own line. diff --git a/README.md b/README.md index 3bb7dc943b7..de5da1b229b 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Launching a supported harness inside it instantiates your first mate - and makes - **Explicit project modes** - each project ships via `no-mistakes`, `direct-PR`, or `local-only`, with an optional `+yolo` autonomy flag. - **Optional secondmates** - opt in to persistent second mates that run from isolated firstmate homes with their own `FM_HOME`, state, projects, and session lock, supervising project clones or a project-less firstmate-repo domain, kept on the primary firstmate version by guarded local fast-forwards and checked for live agent processes at session start. - **Event-driven, zero-token supervision** - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you; Pi visibly relays queued decisions and blockers, and verified primary harnesses refuse a turn end while a home-local escalation is still undrained or work is under way without live supervision. -- **Optional X mode** - opt in with one local `.env` token so firstmate can answer your public `@myfirstmate` mentions, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days for genuine milestones and the final outcome without changing non-X behavior; dry-run preview records would-be replies and dismissals locally before go-live. +- **Optional X mode** - opt in with one local `.env` token so firstmate can answer your public `@myfirstmate` mentions, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days for genuine milestones and the final outcome without changing non-X behavior; a final reply promised in a thread becomes durable state that is reconciled from disk, so a restart or a compacted conversation cannot lose it; dry-run preview records would-be replies and dismissals locally before go-live. - **Strict project boundary** - the first mate is read-only over your projects except for the narrow guarded and captain-approved operations authorized by [hard rule 1](AGENTS.md#1-identity-and-prime-directives), including fleet sync's guarded safe branch pruning; crewmates make every other project change behind the configured merge authority. - **Restart-proof** - all state lives on disk and in the active session backend (tmux by hard default, herdr or cmux when selected or auto-detected, zellij/orca when explicitly selected); kill the session anytime and the next one reconciles, including confirmed-dead secondmate agents, and carries on. @@ -106,7 +106,7 @@ FM_PI_HARNESS=pi-signed pi-signed For Grok, `--trust` is needed once per clone so project hooks and the turn-end guard load; `/hooks-trust` inside Grok works too. For Pi, approve the project trust prompt once per clone on first launch so the tracked `.pi/extensions/*.ts` files auto-load. -Pi's `/calm` toggle hides supported transcript chrome, including canonically classified Firstmate operational user rows, while retaining native working activity and all model context and session data. +Pi's `/calm` toggle hides supported transcript chrome, including canonically classified Firstmate operational user rows, and uses a Calm-only animated working boat during active runs while preserving all model context and session data. The hidden operational inputs remain ordinary user-role messages with unchanged delivery, ordering, authority, persistence, and exports. The preference persists for the effective Firstmate home, and toggling it off restores ordinary rendering. [Calm's current behavior and supported limits](docs/calm.md) are separate from its [version-scoped maintainer evidence](docs/calm-mode-feasibility.md). diff --git a/bin/backends/herdr.sh b/bin/backends/herdr.sh index b88f38b5ac1..65811b71fd4 100644 --- a/bin/backends/herdr.sh +++ b/bin/backends/herdr.sh @@ -27,9 +27,17 @@ # duplicate-agent risk is independently absent. # Target resolution stays parallel to the tmux adapter in both layouts. # Projected create, move, and cleanup operations capture the named session's -# exact active workspace and tab. Herdr 0.7.4's last-pane close can focus an -# unrelated neighbor, so projected cleanup serializes and restores only the -# exact pre-close tab id, while refusing to close the active tab itself. +# exact active workspace and tab. On Herdr 0.7.5, an explicit close that +# empties a non-focused workspace moves focus to that workspace's neighbor +# (upstream discussion #1328, fixed by PR #1877), while a pane-death removal +# preserves focus exactly when the dying workspace sits behind the focused +# one or the focused one is last (upstream issue #1621, fixed by PR #1912); +# both fixes are merged upstream but in no release. Projected cleanup +# therefore serializes under the session lock, repositions a doomed workspace +# behind the focused one when needed, and ends its verified lone idle shell +# so Herdr removes the emptied workspace through the focus-preserving +# pane-death path, with the exact pre-close tab restore as the backstop and a +# refusal to close the active tab itself. # # Target string shape: ":", e.g. "default:w1:p2" (the # pane id itself contains a colon; the session is always the FIRST field, the @@ -462,18 +470,15 @@ fm_backend_herdr_presentation_lock_namespace_valid() { # it would turn JSON null into the literal string "null"). Canonicalizes the # parent directory when that directory exists so symlink parents such as /tmp # -> /private/tmp cannot yield two lock identities for the same socket. -fm_backend_herdr_presentation_session_socket_path() { # - local session=$1 sessions socket sock_dir sock_base - [ -n "$session" ] || return 1 - sessions=$(fm_backend_herdr_cli "$session" session list --json 2>/dev/null) || return 1 - socket=$(printf '%s' "$sessions" | jq -er --arg want "$session" ' - [.sessions[]? - | select(.name == $want and .running == true) - | select((.socket_path | type) == "string") - | select((.socket_path | length) > 0) - | .socket_path] - | if length == 1 then .[0] else empty end - ' 2>/dev/null) || return 1 +# fm_backend_herdr_canonical_socket_path: normalize one absolute Unix-socket +# path so two spellings of the same socket compare equal. Refuses a relative +# or empty path. An unresolvable directory is left as-is rather than treated as +# a failure, so a socket whose directory was removed still compares by its own +# literal path. Single owner for every socket-identity comparison in this +# adapter (the presentation session lock and the launcher-identity same-session +# proof both use it). +fm_backend_herdr_canonical_socket_path() { # + local socket=$1 sock_dir sock_base [ -n "$socket" ] || return 1 case "$socket" in /*) ;; @@ -489,6 +494,21 @@ fm_backend_herdr_presentation_session_socket_path() { # printf '%s' "$socket" } +fm_backend_herdr_presentation_session_socket_path() { # + local session=$1 sessions socket + [ -n "$session" ] || return 1 + sessions=$(fm_backend_herdr_cli "$session" session list --json 2>/dev/null) || return 1 + socket=$(printf '%s' "$sessions" | jq -er --arg want "$session" ' + [.sessions[]? + | select(.name == $want and .running == true) + | select((.socket_path | type) == "string") + | select((.socket_path | length) > 0) + | .socket_path] + | if length == 1 then .[0] else empty end + ' 2>/dev/null) || return 1 + fm_backend_herdr_canonical_socket_path "$socket" +} + fm_backend_herdr_presentation_session_lock_path() { # local session=$1 socket key dir hash [ -n "$session" ] || return 1 @@ -546,8 +566,11 @@ fm_backend_herdr_projection_focus_snapshot() { # # fm_backend_herdr_projection_focus_restore: verify that one presentation # mutation preserved the exact active workspace and tab captured immediately # before it. -# Herdr 0.7.4's pane.close can focus an unrelated neighboring workspace when -# it removes a non-focused workspace's last pane. +# This is the backstop for every focus-unsafe instant: on Herdr 0.7.5 an +# explicit pane.close that empties a non-focused workspace moves focus to +# that workspace's neighbor (upstream #1328/#1877), and a pane-death removal +# before a non-last focused workspace moves focus to the focused workspace's +# right neighbor (upstream #1621/#1912); both fixes are unreleased. # A single tab.focus on the exact response-independent pre-operation tab id # restores both the workspace and tab atomically. fm_backend_herdr_projection_focus_restore() { # @@ -587,9 +610,17 @@ fm_backend_herdr_projection_focus_restore() { # [required-agent-state] local session=$1 pane_id=$2 required_agent_state=${3:-} - local before active_tab info target_pane target_tab close_status state + local before active_tab info target_pane target_tab target_ws close_status state plan plan_shell_pid plan_move_record workspace_presence FM_BACKEND_HERDR_PROJECTION_CLOSE_AGENT_STATE="" [ -n "$pane_id" ] || return 0 before=$(fm_backend_herdr_projection_focus_snapshot "$session") || { @@ -603,6 +634,7 @@ fm_backend_herdr_projection_close_pane_focus_preserving() { # /dev/null) target_tab=$(printf '%s' "$info" | jq -r '.result.pane.tab_id // empty' 2>/dev/null) + target_ws=$(printf '%s' "$info" | jq -r '.result.pane.workspace_id // empty' 2>/dev/null) if [ "$target_pane" != "$pane_id" ] || [ -z "$target_tab" ]; then echo "warning: herdr presentation cleanup received an ambiguous exact-pane response; refusing focus-unsafe pane close" >&2 return 1 @@ -616,20 +648,380 @@ fm_backend_herdr_projection_close_pane_focus_preserving() { # /dev/null 2>&1; then + plan=plain + plan_shell_pid= + plan_move_record= + if [ -n "$target_ws" ]; then + plan=$(fm_backend_herdr_emptying_close_plan "$session" "$pane_id" "$target_ws" "$target_tab" "${before%%$'\t'*}") + case "$plan" in + moved$'\t'*) + plan_move_record=${plan%%$'\n'*} + plan=${plan##*$'\n'} + ;; + esac + case "$plan" in + death\ *) + plan_shell_pid=${plan#death } + plan=death + ;; + *) + plan=plain + ;; + esac + fi + if [ "$plan" = death ]; then + if fm_backend_herdr_death_close_pane "$session" "$pane_id" "$plan_shell_pid"; then + close_status=0 + elif fm_backend_herdr_explicit_close_pane_confirmed "$session" "$pane_id"; then + close_status=0 + else + close_status=1 + fi + elif fm_backend_herdr_explicit_close_pane_confirmed "$session" "$pane_id"; then close_status=0 else - close_status=$? + close_status=1 + fi + if [ "$close_status" -eq 0 ] && [ -n "$plan_move_record" ]; then + workspace_presence=$(fm_backend_herdr_workspace_presence_state "$session" "$target_ws") + if [ "$workspace_presence" != dead ]; then + echo "warning: herdr presentation cleanup did not confirm removal of the repositioned workspace" >&2 + close_status=1 + fi + fi + if [ "$close_status" -ne 0 ]; then + fm_backend_herdr_emptying_move_rollback "$plan_move_record" || true fi fm_backend_herdr_projection_focus_restore "$session" "$before" "pane close" || return 2 [ "$close_status" -eq 0 ] } +# Herdr 0.7.5 workspace-removal focus rules (verified against the installed +# 0.7.5 binary, its v0.7.5 tag source, and the isolated named lab): +# - An EXPLICIT close that empties a workspace (API pane.close of its last +# pane, tab close, or workspace close) routes through +# close_selected_workspace, which assigns focus to the closing workspace's +# right neighbor (or the new last workspace when it was last), ignoring the +# previously focused workspace entirely (upstream discussion #1328, fixed +# by PR #1877, commit 165dca45). +# - A PANE-DEATH removal (handle_pane_died) keeps the focused index stale, +# which preserves the exact focused workspace whenever the dying workspace +# sat behind it (or the focused workspace was last), and moves focus to the +# focused workspace's right neighbor otherwise (upstream issue #1621, fixed +# by PR #1912, commit a979916). +# Both fixes are merged upstream but in no release as of 2026-07-28. +# Firstmate therefore removes a doomed non-focused workspace by ending its +# verified lone idle shell (the pane-death path), repositioning it behind the +# focused workspace first when needed. Moving it to the end preserves every +# other workspace's relative order, so no presentation ordering change +# persists. A release carrying both fixes preserves focus on both paths, so +# this stays safe without any version gate. + +# fm_backend_herdr_workspace_move_capable: verify that one guarded raw +# workspace.move request is possible in : python3 for the transport, +# the minimum protocol, and the exact whitelisted method and parameter +# schema. Silent; each caller owns its own warning wording. +# Return codes: 1 python3 missing, 2 protocol unreadable, 3 protocol too old, +# 4 schema unreadable, 5 method or parameter schema unsupported. +fm_backend_herdr_workspace_move_capable() { # + local session=$1 protocol schema + command -v python3 >/dev/null 2>&1 || return 1 + protocol=$(fm_backend_herdr_cli "$session" status --json 2>/dev/null | jq -r '.client.protocol // empty' 2>/dev/null) + case "$protocol" in + ''|*[!0-9]*) return 2 ;; + esac + [ "$protocol" -lt "$FM_BACKEND_HERDR_MIN_WORKSPACE_MOVE_PROTOCOL" ] && return 3 + schema=$(fm_backend_herdr_cli "$session" api schema --json 2>/dev/null) || return 4 + printf '%s' "$schema" | jq -e ' + any(.schemas.request.oneOf[]?; .properties.method.const == "workspace.move") + and .schemas.request["$defs"].WorkspaceMoveParams.required == ["workspace_id", "insert_index"] + and .schemas.request["$defs"].WorkspaceMoveParams.properties.insert_index.type == "integer" + ' >/dev/null 2>&1 || return 5 +} + +# fm_backend_herdr_emptying_close_plan: choose the focus-safe removal for one +# exact pane. The LAST echoed line is the plan: "plain" (use the ordinary +# explicit close; the exact-tab restore backstop masks 0.7.5's focus move) +# or "death " (end the proved lone idle shell so Herdr removes +# the emptied workspace through its focus-preserving pane-death path). +# Whenever the repositioning mover was invoked, a preceding +# "moved" +# record line is echoed first so the caller can hand it to +# fm_backend_herdr_emptying_move_rollback when removal is not confirmed. +# Never fails; every ambiguity plans "plain". +# The death plan requires the close to empty the workspace (exactly one tab +# and one pane, both the target), the target workspace to sit behind the +# focused one (repositioned to the end first when it does not, with the move +# verified against the server-returned order and focus), and the exact pane +# to hold one provably lone idle recognized shell. +fm_backend_herdr_emptying_close_plan() { # + local session=$1 pane_id=$2 ws_id=$3 tab_id=$4 focused_ws=$5 + local tabs panes list indices r rest a len capable socket mover response move_status shell_pid before_order + [ -n "$ws_id" ] && [ -n "$tab_id" ] && [ -n "$focused_ws" ] || { printf 'plain\n'; return 0; } + tabs=$(fm_backend_herdr_cli "$session" tab list --workspace "$ws_id" 2>/dev/null) || { printf 'plain\n'; return 0; } + printf '%s' "$tabs" | jq -e --arg tab "$tab_id" ' + (.result.tabs | type) == "array" and (.result.tabs | length) == 1 + and .result.tabs[0].tab_id == $tab + ' >/dev/null 2>&1 || { printf 'plain\n'; return 0; } + panes=$(fm_backend_herdr_cli "$session" pane list --workspace "$ws_id" 2>/dev/null) || { printf 'plain\n'; return 0; } + printf '%s' "$panes" | jq -e --arg pane "$pane_id" ' + (.result.panes | type) == "array" and (.result.panes | length) == 1 + and .result.panes[0].pane_id == $pane + ' >/dev/null 2>&1 || { printf 'plain\n'; return 0; } + list=$(fm_backend_herdr_cli "$session" workspace list 2>/dev/null) || { printf 'plain\n'; return 0; } + indices=$(printf '%s' "$list" | jq -r --arg ws "$ws_id" --arg focused "$focused_ws" ' + (.result.workspaces // null) as $s + | select(($s | type) == "array" and ($s | length) > 1) + | ([range(0; $s | length) | select($s[.].workspace_id == $ws)]) as $w + | ([range(0; $s | length) | select($s[.].workspace_id == $focused)]) as $f + | select(($w | length) == 1 and ($f | length) == 1 and $w[0] != $f[0]) + | "\($w[0])\t\($f[0])\t\($s | length)" + ' 2>/dev/null) || indices= + if [ -z "$indices" ]; then + printf 'plain\n' + return 0 + fi + r=${indices%%$'\t'*} + rest=${indices#*$'\t'} + a=${rest%%$'\t'*} + len=${rest#*$'\t'} + case "$r:$a:$len" in + *[!0-9:]*) + printf 'plain\n' + return 0 + ;; + esac + if [ "$r" -lt "$a" ] && [ "$a" -lt $((len - 1)) ]; then + # The doomed workspace sits before the focused one, where the pane-death + # path would land focus on the focused workspace's right neighbor. + # Reposition it behind everything first: insert_index equal to the list + # length is the verified move-to-last form, and removing the moved + # workspace afterward leaves every other relative order untouched. + if fm_backend_herdr_workspace_move_capable "$session"; then + capable=0 + else + capable=$? + fi + if [ "$capable" -ne 0 ]; then + echo "warning: herdr presentation cleanup could not verify workspace.move support; closing without the focus-safe removal path" >&2 + printf 'plain\n' + return 0 + fi + socket=$(fm_backend_herdr_presentation_session_socket_path "$session") || { + echo "warning: herdr presentation cleanup found an ambiguous named session socket; closing without the focus-safe removal path" >&2 + printf 'plain\n' + return 0 + } + mover=${FM_BACKEND_HERDR_WORKSPACE_MOVER:-$FM_BACKEND_HERDR_ROOT/bin/backends/herdr-workspace-move.py} + before_order=$(printf '%s' "$list" | jq -c '[.result.workspaces[].workspace_id]' 2>/dev/null) + if response=$("$mover" "$socket" "$ws_id" "$len" 2>/dev/null); then + move_status=0 + else + move_status=$? + fi + # Every mover invocation is recorded, even an unverified one, so a later + # unconfirmed removal can restore the exact original order; restoring an + # unmoved workspace to its own position is a verified no-op. + printf 'moved\t%s\t%s\t%s\t%s\t%s\n' "$ws_id" "$r" "$socket" "$focused_ws" "$before_order" + if [ "$move_status" -ne 0 ] \ + || ! printf '%s' "$response" | jq -e --arg ws "$ws_id" --arg focused "$focused_ws" \ + --argjson before "$before_order" ' + ($before | map(select(. != $ws)) + [$ws]) as $expected + | .result.type == "workspace_list" + and ([.result.workspaces[].workspace_id] == $expected) + and ([.result.workspaces[] | select(.focused == true) | .workspace_id] == [$focused]) + ' >/dev/null 2>&1; then + echo "warning: herdr presentation cleanup could not move the doomed workspace behind the focused one; closing without the focus-safe removal path" >&2 + printf 'plain\n' + return 0 + fi + fi + if shell_pid=$(fm_backend_herdr_pane_idle_shell_pid "$session" "$pane_id"); then + printf 'death %s\n' "$shell_pid" + else + printf 'plain\n' + fi +} + +# fm_backend_herdr_emptying_move_rollback: restore the exact pre-move +# workspace order recorded by an emptying-close plan whose removal was not +# confirmed, under the caller's still-held session lock. +# is the plan's tab-separated +# "moved" +# line, or empty for a no-op when no move was attempted. +# The rollback is verified against the mover's returned order and focus and +# warns on any failure, so a lasting reorder is never silent. +fm_backend_herdr_emptying_move_rollback() { # + local record=$1 marker ws index socket focused order mover response + [ -n "$record" ] || return 0 + IFS=$'\t' read -r marker ws index socket focused order <&2 + return 1 + fi + case "$index" in + ''|*[!0-9]*) + echo "warning: herdr presentation cleanup has a malformed move record after a failed removal; the workspace order may remain changed" >&2 + return 1 + ;; + esac + mover=${FM_BACKEND_HERDR_WORKSPACE_MOVER:-$FM_BACKEND_HERDR_ROOT/bin/backends/herdr-workspace-move.py} + if ! response=$("$mover" "$socket" "$ws" "$index" 2>/dev/null) \ + || ! printf '%s' "$response" | jq -e --argjson expected "$order" --arg focused "$focused" ' + .result.type == "workspace_list" + and ([.result.workspaces[].workspace_id] == $expected) + and ([.result.workspaces[] | select(.focused == true) | .workspace_id] == [$focused]) + ' >/dev/null 2>&1; then + echo "warning: herdr presentation cleanup could not restore the original workspace order after a failed removal" >&2 + return 1 + fi +} + +# fm_backend_herdr_death_close_pane: end the exact pane's proved lone idle +# shell so Herdr removes the emptied workspace through its focus-preserving +# pane-death path, then confirm the pane is gone. +# Each signal is sent only while the exact pane still owns the recorded pid +# as its lone idle shell: SIGHUP relies on the proof taken just before, and +# the SIGKILL escalation re-reads the pane's process information and refuses +# unless the same pid is still the pane's strict bare idle shell, so an +# exited or reused pid is never signaled. +# Returns 0 only when the pane is confirmed gone. +fm_backend_herdr_death_close_pane() { # + local session=$1 pane_id=$2 shell_pid=$3 ps_bin attempt max_attempts presence resampled_pid + ps_bin=${FM_HERDR_PS_BIN:-ps} + case "$shell_pid" in + ''|*[!0-9]*) return 1 ;; + esac + command -v "$ps_bin" >/dev/null 2>&1 || return 1 + max_attempts=${FM_BACKEND_HERDR_DEATH_CLOSE_POLLS:-40} + fm_backend_herdr_pid_is_bare_shell "$ps_bin" "$shell_pid" || return 1 + kill -HUP "$shell_pid" 2>/dev/null || true + attempt=0 + while [ "$attempt" -lt "$max_attempts" ]; do + presence=$(fm_backend_herdr_pane_presence_state "$session" "$pane_id") + [ "$presence" = dead ] && return 0 + sleep 0.05 + attempt=$((attempt + 1)) + done + # SIGKILL escalation revalidates exact pane ownership, not just the pid: a + # fresh strict pane sample must still name the SAME shell pid, so a pid + # that exited and was reused by an unrelated process is never signaled. + resampled_pid=$(fm_backend_herdr_pane_idle_shell_sample "$session" "$pane_id") || return 1 + [ "$resampled_pid" = "$shell_pid" ] || return 1 + fm_backend_herdr_pid_is_bare_shell "$ps_bin" "$shell_pid" || return 1 + kill -KILL "$shell_pid" 2>/dev/null || true + attempt=0 + while [ "$attempt" -lt "$max_attempts" ]; do + presence=$(fm_backend_herdr_pane_presence_state "$session" "$pane_id") + [ "$presence" = dead ] && return 0 + sleep 0.05 + attempt=$((attempt + 1)) + done + return 1 +} + +# fm_backend_herdr_pid_is_bare_shell: currently resolves to a bare +# recognized shell process per . +# BSD ps reports comm as argv0, so a login shell arrives as "-zsh"; strip the +# login dash exactly like the idle-shell proof's argv0 normalization. +fm_backend_herdr_pid_is_bare_shell() { # + local comm + comm=$("$1" -p "$2" -o comm= 2>/dev/null) || return 1 + comm=$(printf '%s' "$comm" | tr -d '[:space:]') + comm=${comm#-} + comm=${comm##*/} + case "$comm" in sh|bash|zsh|dash|ksh|fish) return 0 ;; esac + return 1 +} + +# fm_backend_herdr_pane_idle_shell_pid: print the shell pid of only +# when the exact pane provably holds one lone idle recognized shell: pane +# process-info agrees on the pane id, the shell pid is both the foreground +# process group and the sole foreground process, the foreground process name +# and argv0 resolve to the same recognized shell, the operating-system +# process table shows exactly that one shell row with no child process, and +# the shell sits in a sleeping or idle state. +# An idle interactive shell transiently hosts short-lived prompt helpers +# (verified on the real 0.7.5 lab: a workspace.move relayout makes zsh redraw +# its prompt, spawning starship as a second foreground process for a few +# samples), so the proof retries strict single samples for a bounded settle +# window and succeeds on the first fully clean one; a genuinely busy pane +# fails every sample and still refuses. +# This is the single owner of the idle-shell proof; the session-start +# projection cleanup and every pane-death close path both rely on it. +fm_backend_herdr_pane_idle_shell_pid() { # + local attempt=0 max_attempts=${FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS:-10} + while :; do + if fm_backend_herdr_pane_idle_shell_sample "$1" "$2"; then + return 0 + fi + attempt=$((attempt + 1)) + [ "$attempt" -lt "$max_attempts" ] || return 1 + sleep 0.1 + done +} + +# fm_backend_herdr_pane_idle_shell_sample: one strict instantaneous +# observation for fm_backend_herdr_pane_idle_shell_pid, which owns the proof +# contract and the settle retry. +fm_backend_herdr_pane_idle_shell_sample() { # + local session=$1 pane=$2 info shell_pid foreground_pgid count + local process_pid name argv0 shell_name rows stat ps_bin + info=$(fm_backend_herdr_cli "$session" pane process-info --pane "$pane" 2>/dev/null) || return 1 + printf '%s' "$info" | jq -e --arg pane "$pane" ' + .result.type == "pane_process_info" + and .result.process_info.pane_id == $pane + ' >/dev/null 2>&1 || return 1 + shell_pid=$(printf '%s' "$info" | jq -er \ + '.result.process_info.shell_pid | select(type == "number" and . > 1) | floor' 2>/dev/null) || return 1 + foreground_pgid=$(printf '%s' "$info" | jq -er \ + '.result.process_info.foreground_process_group_id | select(type == "number" and . > 1) | floor' 2>/dev/null) || return 1 + [ "$foreground_pgid" = "$shell_pid" ] || return 1 + count=$(printf '%s' "$info" | jq -er \ + '.result.process_info.foreground_processes | select(type == "array") | length' 2>/dev/null) || return 1 + [ "$count" -eq 1 ] || return 1 + process_pid=$(printf '%s' "$info" | jq -er \ + '.result.process_info.foreground_processes[0].pid | select(type == "number") | floor' 2>/dev/null) || return 1 + [ "$process_pid" = "$shell_pid" ] || return 1 + name=$(printf '%s' "$info" | jq -er \ + '.result.process_info.foreground_processes[0].name | select(type == "string" and length > 0)' 2>/dev/null) || return 1 + argv0=$(printf '%s' "$info" | jq -er ' + .result.process_info.foreground_processes[0] as $process + | ($process.argv0 // $process.argv[0]) + | select(type == "string" and length > 0) + ' 2>/dev/null) || return 1 + shell_name=${name##*/} + argv0=${argv0#-} + argv0=${argv0##*/} + [ "$argv0" = "$shell_name" ] || return 1 + case "$shell_name" in sh|bash|zsh|dash|ksh|fish) ;; *) return 1 ;; esac + + ps_bin=${FM_HERDR_PS_BIN:-ps} + command -v "$ps_bin" >/dev/null 2>&1 || return 1 + rows=$("$ps_bin" -axo pid=,ppid= 2>/dev/null) || return 1 + printf '%s\n' "$rows" | awk -v shell="$shell_pid" ' + $1 == shell { found++ } + $2 == shell { child++ } + END { exit(found == 1 && child == 0 ? 0 : 1) } + ' || return 1 + stat=$("$ps_bin" -p "$shell_pid" -o stat= 2>/dev/null | tr -d '[:space:]') || return 1 + case "$stat" in S*|I*) ;; *) return 1 ;; esac + printf '%s\n' "$shell_pid" +} + # fm_backend_herdr_projection_order_best_effort: place the exact workspace id # returned by THIS projected create immediately after its owning parent's # contiguous child block and before the next parent. # # is the owning FM_HOME label (firstmate or 2ndmate-). +# Optional is that parent's EXACT id, which the caller +# already resolved from the launching agent's own herdr identity. When given it +# anchors the owning parent by id, so two workspaces sharing the home label no +# longer make the whole layout ambiguous; when omitted the parent is located by +# label exactly as before. With a unique label the two select the same +# workspace, so ordering behavior is unchanged in the ordinary case. # New-format └ ... · p: children and, for compatibility only, already # adjacent old-format firstmate/... or 2ndmate-/... projections may extend # the block read-only; they are never renamed or moved. @@ -644,8 +1036,8 @@ fm_backend_herdr_projection_close_pane_focus_preserving() { # - local session=$1 created=$2 parent=$3 list analysis current desired protocol schema socket mover response move_status focus_before +fm_backend_herdr_projection_order_best_effort() { # [] + local session=$1 created=$2 parent=$3 parent_ws=${4:-} list analysis current desired socket mover response move_status focus_before move_capable local before_existing after_existing [ -n "$parent" ] || { echo "warning: herdr presentation ordering missing owning parent label; leaving worker in Herdr's current order" >&2 @@ -655,9 +1047,12 @@ fm_backend_herdr_projection_order_best_effort() { # &2 return 0 } - analysis=$(printf '%s' "$list" | jq -c --arg created "$created" --arg parent "$parent" ' + analysis=$(printf '%s' "$list" | jq -c --arg created "$created" --arg parent "$parent" --arg parent_ws "$parent_ws" ' def is_parent: - (.label | type) == "string" and .label == $parent; + if ($parent_ws | length) > 0 + then .workspace_id == $parent_ws + else (.label | type) == "string" and .label == $parent + end; def is_top_level_parent: (.label | type) == "string" and ((.label == "firstmate") or (.label | test("^2ndmate-[^/]+$"))); @@ -732,33 +1127,34 @@ fm_backend_herdr_projection_order_best_effort() { # /dev/null 2>&1 || { - echo "warning: herdr presentation ordering requires python3; leaving worker in Herdr's current order" >&2 - return 0 - } - protocol=$(fm_backend_herdr_cli "$session" status --json 2>/dev/null | jq -r '.client.protocol // empty' 2>/dev/null) - case "$protocol" in - ''|*[!0-9]*) + if fm_backend_herdr_workspace_move_capable "$session"; then + move_capable=0 + else + move_capable=$? + fi + case "$move_capable" in + 0) ;; + 1) + echo "warning: herdr presentation ordering requires python3; leaving worker in Herdr's current order" >&2 + return 0 + ;; + 2) echo "warning: herdr presentation ordering could not verify the client protocol; leaving worker in Herdr's current order" >&2 return 0 ;; + 3) + echo "warning: herdr presentation ordering needs protocol $FM_BACKEND_HERDR_MIN_WORKSPACE_MOVE_PROTOCOL or newer; leaving worker in Herdr's current order" >&2 + return 0 + ;; + 4) + echo "warning: herdr presentation ordering could not read the API schema; leaving worker in Herdr's current order" >&2 + return 0 + ;; + *) + echo "warning: herdr presentation ordering API support is unavailable or ambiguous; leaving worker in Herdr's current order" >&2 + return 0 + ;; esac - if [ "$protocol" -lt "$FM_BACKEND_HERDR_MIN_WORKSPACE_MOVE_PROTOCOL" ]; then - echo "warning: herdr presentation ordering needs protocol $FM_BACKEND_HERDR_MIN_WORKSPACE_MOVE_PROTOCOL or newer; leaving worker in Herdr's current order" >&2 - return 0 - fi - schema=$(fm_backend_herdr_cli "$session" api schema --json 2>/dev/null) || { - echo "warning: herdr presentation ordering could not read the API schema; leaving worker in Herdr's current order" >&2 - return 0 - } - if ! printf '%s' "$schema" | jq -e ' - any(.schemas.request.oneOf[]?; .properties.method.const == "workspace.move") - and .schemas.request["$defs"].WorkspaceMoveParams.required == ["workspace_id", "insert_index"] - and .schemas.request["$defs"].WorkspaceMoveParams.properties.insert_index.type == "integer" - ' >/dev/null 2>&1; then - echo "warning: herdr presentation ordering API support is unavailable or ambiguous; leaving worker in Herdr's current order" >&2 - return 0 - fi socket=$(fm_backend_herdr_presentation_session_socket_path "$session") || { echo "warning: herdr presentation ordering found an ambiguous named session socket; leaving worker in Herdr's current order" >&2 return 0 @@ -779,14 +1175,19 @@ fm_backend_herdr_projection_order_best_effort() { # &2 return 0 fi - if ! printf '%s' "$response" | jq -e --arg created "$created" --arg parent "$parent" --argjson desired "$desired" ' + if ! printf '%s' "$response" | jq -e --arg created "$created" --arg parent "$parent" --arg parent_ws "$parent_ws" --argjson desired "$desired" ' + def is_parent: + if ($parent_ws | length) > 0 + then .workspace_id == $parent_ws + else (.label | type) == "string" and .label == $parent + end; .result.type == "workspace_list" and (.result.workspaces | type) == "array" and .result.workspaces[$desired].workspace_id == $created - and ([.result.workspaces[] | select(.label == $parent)] | length) == 1 + and ([.result.workspaces[] | select(is_parent)] | length) == 1 and ( [range(0; .result.workspaces | length) as $i - | select(.result.workspaces[$i].label == $parent) + | select(.result.workspaces[$i] | is_parent) | $i][0] < $desired ) ' >/dev/null 2>&1; then @@ -821,14 +1222,20 @@ fm_backend_herdr_server_ensure() { # return 1 } -# fm_backend_herdr_workspace_find: this HOME's own workspace id inside -# (fm_backend_herdr_workspace_label), or empty (never creates). -# Read-only, safe for recovery/list paths. Label-collision semantics -# (docs/herdr-backend.md "Label collisions"): herdr enforces no label -# uniqueness at all, so this adopts the FIRST matching workspace `jq` returns -# (list order, normally creation order/oldest) rather than disambiguating - -# identical in spirit to the pre-existing tab duplicate-label check below. -fm_backend_herdr_workspace_find() { # +# fm_backend_herdr_workspace_find_all: EVERY workspace id inside +# whose label equals this HOME's own label (fm_backend_herdr_workspace_label), +# one per line, in herdr's own list order (normally creation order, oldest +# first). Empty when none match. Never creates anything. +# +# Single owner of the home-label workspace query. Herdr enforces no workspace +# label uniqueness at all (docs/herdr-backend.md "Label collisions"), so this +# can legitimately return MORE THAN ONE id: a captain-owned workspace can +# collide by label, a cwd-basename-derived label can coincide, and concurrent +# first spawns can mint two same-labeled home workspaces. Callers decide what a +# duplicate means for them - fm_backend_herdr_workspace_ensure refuses to guess +# which one is the caller's, while the read-only recovery path below keeps its +# historical first-match behavior. +fm_backend_herdr_workspace_find_all() { # local session=$1 label list label=$(fm_backend_herdr_workspace_label) list=$(fm_backend_herdr_cli "$session" workspace list 2>/dev/null) || return 0 @@ -838,7 +1245,143 @@ fm_backend_herdr_workspace_find() { # # ALWAYS return empty and every spawn mint a fresh "firstmate" workspace # (the workspace leak). printf '%s' "$list" | jq -r --arg want "$label" \ - '.result.workspaces[]? | select(.label == $want) | .workspace_id' 2>/dev/null | head -1 + '.result.workspaces[]? | select(.label == $want) | .workspace_id' 2>/dev/null +} + +# fm_backend_herdr_workspace_find: this HOME's own workspace id inside +# , or empty (never creates). Read-only, safe for recovery/list +# paths, which address panes they already recorded and only need a container +# to scan. Keeps the historical FIRST-match behavior on a label collision - +# identical in spirit to the pre-existing tab duplicate-label check below. +# NOT the spawn-time resolver: placing a new worker by first label match is +# exactly the defect fm_backend_herdr_workspace_ensure now refuses. +fm_backend_herdr_workspace_find() { # + fm_backend_herdr_workspace_find_all "$1" | head -1 +} + +# fm_backend_herdr_launcher_identity: the EXACT herdr workspace that the +# process making this spawn is itself running in. +# +# Herdr 0.7.5 injects HERDR_ENV=1, HERDR_PANE_ID, HERDR_SESSION, +# HERDR_SOCKET_PATH, HERDR_TAB_ID, and HERDR_WORKSPACE_ID into every process it +# manages a pane for (docs/verification/runtime-backends.md), and a firstmate +# or secondmate agent's own tool calls inherit them. Older injection shapes are +# unverified and cannot establish launcher ancestry without both pane and +# socket identity. Workspace LABELS are mutable and herdr enforces no +# uniqueness on them, so a label search cannot tell one `firstmate` workspace +# from another, and herdr's globally focused workspace is whatever the captain +# happens to be looking at, not the launcher's. +# +# The injected HERDR_TAB_ID/HERDR_WORKSPACE_ID are deliberately NOT read as the +# answer. They are a snapshot taken when the pane's process started, and herdr +# can move a pane between tabs and workspaces afterwards without being able to +# rewrite a running process's environment. Only a live read is the CURRENT +# parent, which is what placement has to bind to. +# +# Sets, only on a 0 return: +# FM_BACKEND_HERDR_LAUNCHER_PANE_ID +# FM_BACKEND_HERDR_LAUNCHER_TAB_ID +# FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID +# +# Returns: +# 0 - one exact, self-consistent launcher pane/tab/workspace in . +# 2 - this process is NOT running in a herdr pane (no HERDR_PANE_ID at all), +# so there is no launcher workspace to inherit and the caller falls back +# to its per-home container. HERDR_ENV=1 on its own is only a backend +# SELECTION marker (bin/fm-backend.sh's fm_backend_detect), never a +# parent binding - herdr always injects the pane id alongside it. +# 1 - a launcher pane IS claimed but its binding is missing, stale, +# contradictory, or belongs to another herdr session. The caller must +# refuse before creating or publishing any worker endpoint rather than +# degrading to a label search. +fm_backend_herdr_launcher_identity() { # + local session=$1 pane=${HERDR_PANE_ID:-} claimed_session claimed_socket session_socket + local pane_out tab_out list tab workspace + FM_BACKEND_HERDR_LAUNCHER_PANE_ID="" + FM_BACKEND_HERDR_LAUNCHER_TAB_ID="" + FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID="" + [ -n "$pane" ] || return 2 + + # Same-session proof, before the pane id is trusted at all: herdr pane ids + # ("w2:p1") restart at the same low numbers in every session, so a pane id + # borrowed from another session can silently resolve to a real but unrelated + # workspace here. The injected socket path is the server identity herdr + # exposes, and the session name independently binds the named session. + claimed_session=$(fm_backend_herdr_session) + if [ "$claimed_session" != "$session" ]; then + echo "error: herdr launcher pane '$pane' reports session '$claimed_session' but this spawn targets session '$session'; refusing to place a worker from a cross-session parent identity" >&2 + return 1 + fi + claimed_socket=${HERDR_SOCKET_PATH:-} + if [ -z "$claimed_socket" ]; then + echo "error: herdr launcher pane '$pane' has no injected socket identity; refusing to place a worker from an unverifiable parent identity" >&2 + return 1 + fi + claimed_socket=$(fm_backend_herdr_canonical_socket_path "$claimed_socket") || { + echo "error: herdr launcher pane '$pane' reports an unusable socket path; refusing to place a worker from an unverifiable parent identity" >&2 + return 1 + } + session_socket=$(fm_backend_herdr_presentation_session_socket_path "$session") || { + echo "error: herdr session '$session' has no unambiguous socket to match against the launcher pane's own; refusing to place a worker from an unverifiable parent identity" >&2 + return 1 + } + if [ "$claimed_socket" != "$session_socket" ]; then + echo "error: herdr launcher pane '$pane' belongs to the server at '$claimed_socket', not session '$session' at '$session_socket'; refusing to place a worker from a cross-session parent identity" >&2 + return 1 + fi + + pane_out=$(fm_backend_herdr_cli "$session" pane get "$pane" 2>/dev/null) || { + echo "error: herdr launcher pane '$pane' could not be read in session '$session'; refusing to place a worker without its exact parent workspace" >&2 + return 1 + } + tab=$(printf '%s' "$pane_out" | jq -r --arg pane "$pane" ' + select(.result.pane.pane_id == $pane) + | select((.result.pane.tab_id | type) == "string" and (.result.pane.tab_id | length) > 0) + | .result.pane.tab_id + ' 2>/dev/null) + workspace=$(printf '%s' "$pane_out" | jq -r --arg pane "$pane" ' + select(.result.pane.pane_id == $pane) + | select((.result.pane.workspace_id | type) == "string" and (.result.pane.workspace_id | length) > 0) + | .result.pane.workspace_id + ' 2>/dev/null) + if [ -z "$tab" ] || [ -z "$workspace" ]; then + echo "error: herdr launcher pane '$pane' returned an ambiguous tab or workspace identity in session '$session'; refusing to place a worker without its exact parent workspace" >&2 + return 1 + fi + + # Independent second read: the tab must agree that it lives in the same + # workspace the pane just claimed. A restored-but-stale pane record that + # disagrees with its own tab is exactly the contradictory binding this must + # refuse rather than resolve. + tab_out=$(fm_backend_herdr_cli "$session" tab get "$tab" 2>/dev/null) || { + echo "error: herdr launcher tab '$tab' could not be read in session '$session'; refusing to place a worker without its exact parent workspace" >&2 + return 1 + } + if ! printf '%s' "$tab_out" | jq -e --arg tab "$tab" --arg workspace "$workspace" ' + .result.tab.tab_id == $tab and .result.tab.workspace_id == $workspace + ' >/dev/null 2>&1; then + echo "error: herdr launcher pane '$pane' and tab '$tab' disagree about their workspace in session '$session'; refusing to place a worker from a contradictory parent identity" >&2 + return 1 + fi + + list=$(fm_backend_herdr_cli "$session" workspace list 2>/dev/null) || { + echo "error: could not list herdr workspaces in session '$session' to confirm the launcher's own workspace '$workspace'; refusing to place a worker without its exact parent workspace" >&2 + return 1 + } + if ! printf '%s' "$list" | jq -e --arg workspace "$workspace" ' + (.result.workspaces | type) == "array" + and ([.result.workspaces[] | select(.workspace_id == $workspace)] | length) == 1 + ' >/dev/null 2>&1; then + echo "error: herdr launcher workspace '$workspace' is missing or duplicated in session '$session'; refusing to place a worker from a stale parent identity" >&2 + return 1 + fi + + # shellcheck disable=SC2034 # callers consume the verified binding's parts + FM_BACKEND_HERDR_LAUNCHER_PANE_ID=$pane + # shellcheck disable=SC2034 # callers consume the verified binding's parts + FM_BACKEND_HERDR_LAUNCHER_TAB_ID=$tab + FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID=$workspace + return 0 } # fm_backend_herdr_workspace_prune_seeded_default_tab: close EXACTLY @@ -903,11 +1446,13 @@ fm_backend_herdr_workspace_prune_seeded_default_tab() { # , creating it in if absent. Must be called as a PLAIN -# STATEMENT, never through command substitution ($(...)) - it communicates -# through these globals, not solely through stdout, and a command -# substitution forks a subshell that would discard them: +# fm_backend_herdr_workspace_ensure: the workspace this spawn's task tab +# belongs in inside - the launching agent's own exact workspace when +# it has one, otherwise this HOME's persistent workspace, created in if +# absent. Must be called as a PLAIN STATEMENT, never through command +# substitution ($(...)) - it communicates through these globals, not solely +# through stdout, and a command substitution forks a subshell that would +# discard them: # FM_BACKEND_HERDR_WS_ID - the resolved workspace_id (also echoed, # for callers that only need the id) # FM_BACKEND_HERDR_WS_SEEDED_TAB_ID - non-empty ONLY when THIS call just @@ -919,11 +1464,14 @@ fm_backend_herdr_workspace_prune_seeded_default_tab() { # - local session=$1 cwd=$2 wsid out label +# +# (3rd arg, default "launcher-home") says whether the +# container being ensured belongs to the SAME firstmate home as the process +# calling this: +# launcher-home - a crewmate or scout for the caller's own home. When the +# caller is itself running in a herdr pane, the worker MUST +# land in that exact workspace +# (fm_backend_herdr_launcher_identity), never in whichever +# same-labeled workspace happens to sort first. +# other-home - a --secondmate launch, which stands up a DIFFERENT home's +# own per-home workspace by design. The launcher's workspace +# is deliberately not inherited here. +# With no herdr ancestry at all there is no launcher workspace to inherit, so +# the per-home label lookup below stays the resolver - but it must then resolve +# to exactly ONE workspace. Two same-labeled home workspaces with no launcher +# identity to disambiguate them is an unresolvable placement, and adopting +# either one is the very defect this refuses. +# +# Returns 0 on success, 3 for a refusal whose exact reason is already on +# stderr, and 1 for a failed or unparseable herdr call. +fm_backend_herdr_workspace_ensure() { # [] + local session=$1 cwd=$2 relationship=${3:-launcher-home} wsid out label matches count status FM_BACKEND_HERDR_WS_ID="" FM_BACKEND_HERDR_WS_SEEDED_TAB_ID="" - wsid=$(fm_backend_herdr_workspace_find "$session") + if [ "$relationship" = launcher-home ]; then + fm_backend_herdr_launcher_identity "$session" && status=0 || status=$? + case "$status" in + 0) + FM_BACKEND_HERDR_WS_ID=$FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID + printf '%s' "$FM_BACKEND_HERDR_WS_ID" + return 0 + ;; + 2) ;; + *) return 3 ;; + esac + fi + label=$(fm_backend_herdr_workspace_label) + matches=$(fm_backend_herdr_workspace_find_all "$session") + count=$(printf '%s' "$matches" | grep -c '[^[:space:]]' || true) + if [ "$count" -gt 1 ]; then + echo "error: ${count} herdr workspaces in session '$session' are labeled '$label' (${matches//$'\n'/ }) and this spawn has no herdr parent pane to identify which one is its own; rename or close the extras, or run firstmate inside the workspace its workers belong in" >&2 + return 3 + fi + wsid=${matches%%$'\n'*} if [ -n "$wsid" ]; then FM_BACKEND_HERDR_WS_ID=$wsid printf '%s' "$wsid" return 0 fi - label=$(fm_backend_herdr_workspace_label) out=$(fm_backend_herdr_cli "$session" workspace create --cwd "$cwd" --label "$label" --no-focus 2>/dev/null) || return 1 wsid=$(printf '%s' "$out" | jq -r '.result.workspace.workspace_id // empty' 2>/dev/null) [ -n "$wsid" ] || return 1 @@ -974,13 +1560,18 @@ fm_backend_herdr_workspace_ensure() { # # CONTAINER=${RAW%%$'\t'*}; SEEDED_TAB_ID=${RAW#*$'\t'}. The seeded tab id # must be threaded through to fm_backend_herdr_create_task, which is the only # function allowed to prune it (fm_backend_herdr_workspace_prune_seeded_default_tab). -fm_backend_herdr_container_ensure() { # - local cwd=${1:-$PWD} session label +# is passed straight through to +# fm_backend_herdr_workspace_ensure, which owns its meaning. +fm_backend_herdr_container_ensure() { # [] + local cwd=${1:-$PWD} relationship=${2:-launcher-home} session label status fm_backend_herdr_version_check || return 1 session=$(fm_backend_herdr_session) fm_backend_herdr_server_ensure "$session" || return 1 - fm_backend_herdr_workspace_ensure "$session" "$cwd" >/dev/null || { label=$(fm_backend_herdr_workspace_label); echo "error: failed to ensure herdr workspace '$label' in session '$session'" >&2; return 1; } - if [ -z "$FM_BACKEND_HERDR_WS_ID" ]; then + fm_backend_herdr_workspace_ensure "$session" "$cwd" "$relationship" >/dev/null && status=0 || status=$? + # A 3 already reported the exact placement it refused to guess at; adding the + # generic message here would bury it. + [ "$status" -ne 3 ] || return 1 + if [ "$status" -ne 0 ] || [ -z "$FM_BACKEND_HERDR_WS_ID" ]; then label=$(fm_backend_herdr_workspace_label) echo "error: failed to ensure herdr workspace '$label' in session '$session'" >&2 return 1 @@ -988,6 +1579,43 @@ fm_backend_herdr_container_ensure() { # printf '%s:%s\t%s' "$session" "$FM_BACKEND_HERDR_WS_ID" "$FM_BACKEND_HERDR_WS_SEEDED_TAB_ID" } +# fm_backend_herdr_pane_presence_state: classify one exact pane get response +# as dead|present|unknown from its JSON body, never from process exit status. +fm_backend_herdr_pane_presence_state() { # + local session=$1 pane_id=$2 out code pid + out=$(fm_backend_herdr_cli "$session" pane get "$pane_id" 2>&1) + code=$(printf '%s' "$out" | jq -r '.error.code // empty' 2>/dev/null) + if [ -n "$code" ]; then + [ "$code" = "pane_not_found" ] && printf 'dead' || printf 'unknown' + return 0 + fi + pid=$(printf '%s' "$out" | jq -r '.result.pane.pane_id // empty' 2>/dev/null) + [ "$pid" = "$pane_id" ] && printf 'present' || printf 'unknown' +} + +fm_backend_herdr_workspace_presence_state() { # + local session=$1 workspace_id=$2 out matches + out=$(fm_backend_herdr_cli "$session" workspace list 2>&1) + matches=$(printf '%s' "$out" | jq -r --arg workspace "$workspace_id" ' + select((.result.workspaces | type) == "array") + | [.result.workspaces[] | select(.workspace_id == $workspace)] | length + ' 2>/dev/null) || matches= + case "$matches" in + 0) printf 'dead' ;; + 1) printf 'present' ;; + *) printf 'unknown' ;; + esac +} + +# fm_backend_herdr_explicit_close_pane_confirmed: issue one explicit close and +# succeed only when a structured follow-up proves the exact pane is gone. +fm_backend_herdr_explicit_close_pane_confirmed() { # + local session=$1 pane_id=$2 presence + fm_backend_herdr_cli "$session" pane close "$pane_id" >/dev/null 2>&1 || return 1 + presence=$(fm_backend_herdr_pane_presence_state "$session" "$pane_id") + [ "$presence" = dead ] +} + # fm_backend_herdr_pane_agent_state: classify in as one of # dead|no-agent|live|unknown, purely from the JSON body of two read-only # calls - never from process exit status, since a business-logic "not found" @@ -1020,24 +1648,13 @@ fm_backend_herdr_container_ensure() { # # refusal here, never toward closing - this is the conservative # backstop the husk check depends on. fm_backend_herdr_pane_agent_state() { # - local session=$1 pane_id=$2 out code pid status - # 2>&1, not 2>/dev/null: verified empirically that real herdr 0.7.1 writes - # an error response's JSON body to STDERR (success bodies go to stdout), so - # discarding stderr here would blind this function to exactly the - # error.code values (pane_not_found, agent_not_found) it exists to read - - # every OTHER call site in this file discards stderr safely only because - # its caller collapses both the error and the not-an-error paths to the - # same final answer, which this function's dead/no-agent/live/unknown - # distinction cannot afford to do. - out=$(fm_backend_herdr_cli "$session" pane get "$pane_id" 2>&1) - code=$(printf '%s' "$out" | jq -r '.error.code // empty' 2>/dev/null) - if [ -n "$code" ]; then - [ "$code" = "pane_not_found" ] && printf 'dead' || printf 'unknown' - return 0 - fi - pid=$(printf '%s' "$out" | jq -r '.result.pane.pane_id // empty' 2>/dev/null) - if [ "$pid" != "$pane_id" ]; then - printf 'unknown' + local session=$1 pane_id=$2 out code presence status + presence=$(fm_backend_herdr_pane_presence_state "$session" "$pane_id") + if [ "$presence" != present ]; then + case "$presence" in + dead|unknown) printf '%s' "$presence" ;; + *) printf 'unknown' ;; + esac return 0 fi out=$(fm_backend_herdr_cli "$session" agent get "$pane_id" 2>&1) @@ -1347,7 +1964,7 @@ fm_backend_herdr_projection_parent_workspace_exact() { # local session=$1 token=$2 workspace=$3 tab=$4 pane=$5 parent_workspace=$6 @@ -1373,7 +1990,6 @@ fm_backend_herdr_projection_live_binding_matches() { # # fm_backend_herdr_kill: remove the task's pane, best-effort (mirrors # tmux-kill-window's `|| true` contract). Verified: closing a tab's only pane # closes the tab too, so a separate tab close is unnecessary. +# When the close would empty a non-focused workspace, Herdr 0.7.5's explicit +# close moves focus to that workspace's neighbor with no restore anywhere in +# this path, so the kill follows the same focus-safe removal plan as +# projected cleanup (a verified pane-death removal with the doomed workspace +# repositioned behind the focused one when needed), keeping the exact-tab +# restore as the backstop. A close that empties the FOCUSED workspace moves +# focus legitimately, and every in-lock planning ambiguity or failure falls +# back to the plain close, matching the pre-hardening contract. +fm_backend_herdr_kill_serialized() { # + local session=$1 pane=$2 + local before active_tab info target_pane target_tab target_ws plan shell_pid plan_move_record close_failed workspace_presence + before=$(fm_backend_herdr_projection_focus_snapshot "$session") || before= + if [ -n "$before" ]; then + active_tab=${before#*$'\t'} + info=$(fm_backend_herdr_cli "$session" pane get "$pane" 2>/dev/null) || info= + target_pane=$(printf '%s' "$info" | jq -r '.result.pane.pane_id // empty' 2>/dev/null) + target_tab=$(printf '%s' "$info" | jq -r '.result.pane.tab_id // empty' 2>/dev/null) + target_ws=$(printf '%s' "$info" | jq -r '.result.pane.workspace_id // empty' 2>/dev/null) + if [ "$target_pane" = "$pane" ] && [ -n "$target_tab" ] && [ "$target_tab" != "$active_tab" ]; then + plan=$(fm_backend_herdr_emptying_close_plan "$session" "$pane" "$target_ws" "$target_tab" "${before%%$'\t'*}") + plan_move_record= + case "$plan" in + moved$'\t'*) + plan_move_record=${plan%%$'\n'*} + plan=${plan##*$'\n'} + ;; + esac + close_failed=0 + case "$plan" in + death\ *) + shell_pid=${plan#death } + if ! fm_backend_herdr_death_close_pane "$session" "$pane" "$shell_pid" \ + && ! fm_backend_herdr_explicit_close_pane_confirmed "$session" "$pane"; then + close_failed=1 + fi + ;; + *) + fm_backend_herdr_explicit_close_pane_confirmed "$session" "$pane" || close_failed=1 + ;; + esac + if [ "$close_failed" = 0 ] && [ -n "$plan_move_record" ]; then + workspace_presence=$(fm_backend_herdr_workspace_presence_state "$session" "$target_ws") + if [ "$workspace_presence" != dead ]; then + echo "warning: herdr task kill did not confirm removal of the repositioned workspace" >&2 + close_failed=1 + fi + fi + if [ "$close_failed" = 1 ]; then + fm_backend_herdr_emptying_move_rollback "$plan_move_record" || true + fi + fm_backend_herdr_projection_focus_restore "$session" "$before" "task kill" || true + return 0 + fi + fi + fm_backend_herdr_explicit_close_pane_confirmed "$session" "$pane" || true +} + fm_backend_herdr_kill() { # [tab-id] [expected-label] [workspace-id] + # Optional binding args recheck owning workspace/tab/pane at mutation time + # (fork safety for kill_endpoint_verified callers). When absent, the plain + # target-ready path is enough for best-effort teardown. local target=$1 tab=${2:-} expected_label=${3:-} workspace=${4:-} workspace_label - fm_backend_herdr_parse_target "$target" || return 0 if [ -n "$expected_label" ]; then + fm_backend_herdr_parse_target "$target" || return 0 [ -n "$tab" ] && [ -n "$workspace" ] || return 0 workspace_label=$(fm_backend_herdr_workspace_label) fm_backend_herdr_workspace_binding_matches \ @@ -2178,9 +2854,44 @@ fm_backend_herdr_kill() { # [tab-id] [expected-label] [workspace-id] fm_backend_herdr_task_binding_matches \ "$FM_BACKEND_HERDR_SESSION" "$workspace" "$tab" "$FM_BACKEND_HERDR_PANE" "$expected_label" || return 0 else - fm_backend_herdr_server_ensure "$FM_BACKEND_HERDR_SESSION" || return 0 + fm_backend_herdr_target_ready "$target" || return 0 + fi + local session=$FM_BACKEND_HERDR_SESSION pane=$FM_BACKEND_HERDR_PANE + local lock_path attempt=0 lock_held=0 + if ! declare -F fm_lock_try_acquire >/dev/null 2>&1; then + # shellcheck source=bin/fm-wake-lib.sh + . "$FM_BACKEND_HERDR_ROOT/bin/fm-wake-lib.sh" + fi + if lock_path=$(fm_backend_herdr_presentation_session_lock_path "$session"); then + while [ "$attempt" -lt 50 ]; do + if fm_lock_try_acquire "$lock_path"; then + lock_held=1 + break + fi + sleep 0.1 + attempt=$((attempt + 1)) + done + fi + if [ "$lock_held" = 1 ]; then + fm_backend_herdr_kill_serialized "$session" "$pane" + fm_lock_release "$lock_path" || true + else + echo "warning: herdr task kill could not acquire its session presentation lock; refusing an unlocked pane close" >&2 fi - fm_backend_herdr_cli "$FM_BACKEND_HERDR_SESSION" pane close "$FM_BACKEND_HERDR_PANE" >/dev/null 2>&1 || true +} + +# fm_backend_herdr_endpoint_confirmed_gone: gate durable-record removal on +# the exact recorded pane's structured presence +# (fm_backend_herdr_pane_presence_state), read-only, so a refused, skipped, +# or failed close never erases a live task's endpoint identity. +# Only a structured pane_not_found proves the endpoint gone; present and +# unknown presence refuse after every close path, and a missing or malformed +# target identity is ambiguity that also refuses, never proof of a gone pane. +fm_backend_herdr_endpoint_confirmed_gone() { # + local presence + fm_backend_herdr_parse_target "$1" || return 1 + presence=$(fm_backend_herdr_pane_presence_state "$FM_BACKEND_HERDR_SESSION" "$FM_BACKEND_HERDR_PANE") + [ "$presence" = dead ] } # fm_backend_herdr_classify_agent_status: map a raw `agent get` agent_status diff --git a/bin/fm-afk-launch.sh b/bin/fm-afk-launch.sh index 8e76ccc276b..25f5a36e48d 100755 --- a/bin/fm-afk-launch.sh +++ b/bin/fm-afk-launch.sh @@ -641,10 +641,15 @@ fm_afk_launch_stop() { fm_afk_launch_main() { local result - fm_afk_launch_lock_acquire || return 1 + # Traps first, lock second. Acquiring before the handlers exist leaves a + # window where a signal terminates this process by default action and leaks + # the lock directory, which then blocks the next away-mode launch until the + # stale-owner reclaim path clears it. fm_afk_launch_lock_release only removes + # a lock this process owns, so arming it before acquisition is safe. trap fm_afk_launch_lock_release EXIT trap 'exit 130' INT trap 'exit 143' TERM + fm_afk_launch_lock_acquire || return 1 case "${1:-start}" in start) fm_afk_launch_start ;; start-native) fm_afk_launch_start_native ;; diff --git a/bin/fm-backlog-handoff.sh b/bin/fm-backlog-handoff.sh index 66da67b8a87..29ab9cd2d66 100755 --- a/bin/fm-backlog-handoff.sh +++ b/bin/fm-backlog-handoff.sh @@ -53,21 +53,19 @@ REG="$DATA/secondmates.md" MAIN_BACKLOG="$DATA/backlog.md" # shellcheck source=bin/fm-tasks-axi-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-tasks-axi-lib.sh" +# shellcheck source=bin/fm-secondmate-registry-lib.sh +. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh" [ $# -ge 2 ] || { echo "usage: fm-backlog-handoff.sh ..." >&2; exit 1; } ID=$1 shift secondmate_home() { - local id=$1 line + local id=$1 home [ -f "$REG" ] || { echo "error: no secondmate registry at $REG" >&2; return 1; } - line=$(grep -E "^- $id( |$)" "$REG" | tail -1 || true) - [ -n "$line" ] || { echo "error: secondmate $id is not registered in $REG" >&2; return 1; } - # Match the (home: ...) field itself; do not require zero parentheses before it. - # Summary/scope prose often contains parentheticals (e.g. "(id is legacy)"), and - # ^[^(]* would leave those entries looking like "has no home". Greedy prefix so the - # last (home: ...) on the line wins. Empty when the field is absent. - printf '%s\n' "$line" | sed -n 's/.*(home:[[:space:]]*\([^;)]*\);.*/\1/p' | sed 's/[[:space:]]*$//' + home=$(secondmate_registry_field "$REG" "$id" home || true) + [ -n "$home" ] || { echo "error: secondmate $id has no home in $REG" >&2; return 1; } + printf '%s\n' "$home" } path_is_ancestor_of() { diff --git a/bin/fm-bootstrap.sh b/bin/fm-bootstrap.sh index 1383a383ed9..520e44f1889 100755 --- a/bin/fm-bootstrap.sh +++ b/bin/fm-bootstrap.sh @@ -8,6 +8,7 @@ # Lines: "MISSING: (install: )", # "MISSING_MANUAL: (instructions: )", "NEEDS_GH_AUTH", # "BACKEND_INVALID: (known: )", +# "STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - ", # "CREW_DISPATCH: invalid config/crew-dispatch.json - ", # "FLEET_SYNC: : skipped|recovered|STUCK: ", # "PR_CHECK_MIGRATION: ", @@ -54,7 +55,15 @@ # incompatible build reports MISSING like no-mistakes. A compatible # tasks-axi default backend is silent. quota-axi is required for the # agent-owned dispatch-profile array procedure in AGENTS.md section 4 -# and .agents/skills/quota-array-dispatch/SKILL.md. +# and .agents/skills/quota-array-dispatch/SKILL.md, and is also version +# gated by fm-quota-axi-lib.sh, which owns that floor and its rationale. +# An older build reports MISSING like no-mistakes rather than passing +# silently while emitting auth semantics dispatch cannot scope. +# On a primary home, the locked mutable path materializes the visible +# default config/startup-memory-budget=7500 when absent. It never +# guesses at malformed or unsafe existing files, and secondmate homes +# await the primary-authoritative inherited value instead of creating +# their own. # X mode is OPTIONAL and inert unless FM_HOME/.env has a non-empty # FMX_PAIRING_TOKEN. When opted in, bootstrap requires curl+jq, writes # the relay poll shim and 30s cadence config, and prints an FMX line. @@ -125,12 +134,16 @@ esac DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}" # shellcheck source=bin/fm-tasks-axi-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-tasks-axi-lib.sh" +# shellcheck source=bin/fm-quota-axi-lib.sh disable=SC1091 +. "$SCRIPT_DIR/fm-quota-axi-lib.sh" # shellcheck source=bin/fm-tangle-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-tangle-lib.sh" # shellcheck source=bin/fm-ff-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-ff-lib.sh" # shellcheck source=bin/fm-config-inherit-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-config-inherit-lib.sh" +# shellcheck source=bin/fm-startup-memory-budget-lib.sh disable=SC1091 +. "$SCRIPT_DIR/fm-startup-memory-budget-lib.sh" # shellcheck source=bin/fm-x-lib.sh disable=SC1091 . "$SCRIPT_DIR/fm-x-lib.sh" # shellcheck source=bin/fm-backend.sh disable=SC1091 @@ -556,31 +569,31 @@ if ! BACKEND_TOOLS=$(fm_backend_required_tools "$BACKEND"); then BACKEND_TOOLS="" fi TOOLS="$BACKEND_TOOLS $COMMON_TOOLS" -NO_MISTAKES_MIN_MAJOR=1 -NO_MISTAKES_MIN_MINOR=31 -NO_MISTAKES_MIN_PATCH=2 +NO_MISTAKES_MIN=1.31.2 treehouse_supports_lease() { treehouse get --help 2>&1 | grep -Eq '(^|[^[:alnum:]_-])--lease([^[:alnum:]_-]|$)' } -no_mistakes_version_parts() { - local output - command -v no-mistakes >/dev/null 2>&1 || return 1 - output=$(no-mistakes --version 2>/dev/null) || return 1 - printf '%s\n' "$output" | sed -nE 's/.*[vV]?([0-9]+)\.([0-9]+)\.([0-9]+).*/\1 \2 \3/p' | head -n 1 -} - -no_mistakes_compatible() { - local parts major minor patch extra - parts=$(no_mistakes_version_parts) || return 1 +# Shared semantic-version floor for the tool gates below. A version string that +# cannot be parsed into exactly one major.minor.patch triple is incompatible, +# never assumed current, so a development or vendored build cannot pass a floor +# it was never checked against. +tool_version_at_least() { # + local tool=$1 min=$2 output parts major minor patch extra + local min_major min_minor min_patch min_extra + command -v "$tool" >/dev/null 2>&1 || return 1 + output=$("$tool" --version 2>/dev/null) || return 1 + parts=$(printf '%s\n' "$output" | sed -nE 's/.*[vV]?([0-9]+)\.([0-9]+)\.([0-9]+).*/\1 \2 \3/p' | head -n 1) IFS=' ' read -r major minor patch extra <<< "$parts" [ -n "$major" ] && [ -n "$minor" ] && [ -n "$patch" ] && [ -z "$extra" ] || return 1 - [ "$major" -gt "$NO_MISTAKES_MIN_MAJOR" ] && return 0 - [ "$major" -eq "$NO_MISTAKES_MIN_MAJOR" ] || return 1 - [ "$minor" -gt "$NO_MISTAKES_MIN_MINOR" ] && return 0 - [ "$minor" -eq "$NO_MISTAKES_MIN_MINOR" ] || return 1 - [ "$patch" -ge "$NO_MISTAKES_MIN_PATCH" ] + IFS='.' read -r min_major min_minor min_patch min_extra <<< "$min" + [ -n "$min_major" ] && [ -n "$min_minor" ] && [ -n "$min_patch" ] && [ -z "$min_extra" ] || return 1 + [ "$major" -gt "$min_major" ] && return 0 + [ "$major" -eq "$min_major" ] || return 1 + [ "$minor" -gt "$min_minor" ] && return 0 + [ "$minor" -eq "$min_minor" ] || return 1 + [ "$patch" -ge "$min_patch" ] } x_mode_write_if_changed() { @@ -846,6 +859,18 @@ crew_dispatch_validate() { fi } +startup_memory_budget_setup() { + # Primary bootstrap owns default publication. A secondmate is deliberately + # passive here because its setting must converge from the primary through the + # inherited-local-material contract rather than becoming a local authority. + if [ -e "$FM_HOME/.fm-secondmate-home" ] || [ -L "$FM_HOME/.fm-secondmate-home" ]; then + return 0 + fi + if ! fm_startup_memory_budget_materialize "$CONFIG"; then + echo "STARTUP_MEMORY_BUDGET: invalid config/$FM_STARTUP_MEMORY_BUDGET_FILE - $FM_STARTUP_MEMORY_BUDGET_ERROR" + fi +} + if [ "${1:-}" = "install" ]; then shift [ $# -gt 0 ] || { echo "usage: fm-bootstrap.sh install ..." >&2; exit 1; } @@ -868,6 +893,7 @@ fi # runnable. Detect-only sessions never touch state. if [ "${FM_BOOTSTRAP_DETECT_ONLY:-0}" != 1 ]; then "$SCRIPT_DIR/fm-pr-check-migrate.sh" || true + startup_memory_budget_setup fi if [ "$BACKEND_VALID" -eq 0 ]; then @@ -887,9 +913,12 @@ if fm_backend_list_contains "$TOOLS" treehouse \ && command -v treehouse >/dev/null 2>&1 && ! treehouse_supports_lease; then echo "MISSING: treehouse (install: $(install_cmd treehouse))" fi -if command -v no-mistakes >/dev/null 2>&1 && ! no_mistakes_compatible; then +if command -v no-mistakes >/dev/null 2>&1 && ! tool_version_at_least no-mistakes "$NO_MISTAKES_MIN"; then echo "MISSING: no-mistakes (install: $(install_cmd no-mistakes))" fi +if command -v quota-axi >/dev/null 2>&1 && ! fm_quota_axi_compatible; then + echo "MISSING: quota-axi (install: $(install_cmd quota-axi))" +fi if command -v tasks-axi >/dev/null 2>&1 && ! fm_tasks_axi_compatible; then echo "MISSING: tasks-axi (install: $(install_cmd tasks-axi))" fi diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh index 7de7c4ea5e8..d976f212c37 100755 --- a/bin/fm-brief.sh +++ b/bin/fm-brief.sh @@ -344,6 +344,7 @@ Firstmate will then instruct you to run /no-mistakes to validate and ship a PR. You drive no-mistakes by responding to its gates, not by implementing fixes. Follow the guidance no-mistakes itself provides for the mechanics: it loads when you invoke /no-mistakes, and \`no-mistakes axi run --help\` plus the \`help\` lines in each \`axi\` response are authoritative and version-matched to the installed binary. +When starting no-mistakes, make \`--intent\` preserve all relevant content from this brief's \`# Task\` section plus every later accepted Firstmate requirement, clarification, constraint, exclusion, and supersession, carrying only each requirement's current accepted form; retain direct requirements instead of substituting a diff summary, and exclude generic operational, status, delivery, and other scaffold boilerplate unless it is task-specific. Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix. Two firstmate-specific rules layer on top of that guidance: diff --git a/bin/fm-busy-event.sh b/bin/fm-busy-event.sh new file mode 100755 index 00000000000..d5484c9d5c4 --- /dev/null +++ b/bin/fm-busy-event.sh @@ -0,0 +1,216 @@ +#!/usr/bin/env bash +# fm-busy-event.sh - the ONLY writer of the semantic busy-state contract +# owned by bin/fm-busy-lib.sh (record format, gen binding, and classification +# live there; this script owns mutation mechanics only). +# +# Subcommands: +# +# arm [--state busy|idle|unknown] [--source S] [--event E] +# Mint a fresh incarnation gen token, write the gen sidecar, and seed +# the record at seq=1 (default: busy, source fm-spawn, event +# launch-brief - the launch prompt IS a submitted turn). Prints the +# minted gen on stdout so the caller can embed it into adapter wiring. +# Arming again replaces the previous incarnation: late events carrying +# the old gen are rejected as stale from then on. +# +# apply (--gen G | --current-gen) +# --source S --event E +# Append one lifecycle event: validate the gen against the armed +# sidecar, advance seq under the lock, atomically replace the record. +# Adapter wiring passes the exact --gen embedded at arm time, so a +# hook that outlives its incarnation fails closed here. Firstmate-owned +# paths (fm-interrupt, fm-recovery) may pass --current-gen to bind to +# whatever incarnation is armed right now. +# +# retire (--gen G | --current-gen) +# Remove one incarnation's sidecar and record while holding the same +# writer lock used by arm and apply. An exact gen prevents teardown for +# an old task from retiring a newly armed incarnation. A missing sidecar +# is already retired, so any orphan record is removed idempotently. +# +# Exit codes: 0 applied; 1 refused (stale gen, unarmed task, lock timeout, +# invalid input); 2 usage. Adapter hook command lines append `|| true` so a +# refusal never breaks the harness's own lifecycle. +set -u + +usage() { + cat >&2 <<'EOF' +usage: + fm-busy-event.sh arm [--state busy|idle|unknown] [--source S] [--event E] + fm-busy-event.sh apply (--gen G | --current-gen) --source S --event E + fm-busy-event.sh retire (--gen G | --current-gen) +See the header comment for the full contract. +EOF + exit 2 +} + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# shellcheck source=bin/fm-busy-lib.sh +. "$SCRIPT_DIR/fm-busy-lib.sh" + +CMD=${1:-} +case "$CMD" in + arm|apply|retire) shift ;; + *) usage ;; +esac + +STATE=${1:-} +ID=${2:-} +[ -n "$STATE" ] && [ -n "$ID" ] || usage +shift 2 +case "$ID" in *[!A-Za-z0-9._-]*) echo "error: invalid task id" >&2; exit 1 ;; esac +[ -d "$STATE" ] || { echo "error: state dir not found: $STATE" >&2; exit 1; } + +NEW_STATE= +GEN= +USE_CURRENT_GEN=0 +SOURCE= +EVENT= +if [ "$CMD" = apply ]; then + NEW_STATE=${1:-} + case "$NEW_STATE" in busy|idle|unknown) shift ;; *) usage ;; esac +elif [ "$CMD" = arm ]; then + NEW_STATE=busy + SOURCE=fm-spawn + EVENT=launch-brief +fi +while [ $# -gt 0 ]; do + case "$1" in + --state) NEW_STATE=${2:-}; shift 2 || usage ;; + --gen) GEN=${2:-}; shift 2 || usage ;; + --current-gen) USE_CURRENT_GEN=1; shift ;; + --source) SOURCE=${2:-}; shift 2 || usage ;; + --event) EVENT=${2:-}; shift 2 || usage ;; + *) usage ;; + esac +done +if [ "$CMD" != retire ]; then + case "$NEW_STATE" in busy|idle|unknown) : ;; *) usage ;; esac + fm_busy_token_valid "$SOURCE" || { echo "error: invalid --source" >&2; exit 1; } + fm_busy_token_valid "$EVENT" || { echo "error: invalid --event" >&2; exit 1; } +fi + +REC=$(fm_busy_record_path "$STATE" "$ID") +GEN_FILE=$(fm_busy_gen_path "$STATE" "$ID") +LOCK="$REC.lock" + +# Serialize writers. The lock protects seq advancement and the sidecar/record +# pair; a holder that died mid-write is broken after FM_BUSY_LOCK_STALE_SECS. +lock_acquire() { + local tries=0 now mtime age + while ! mkdir "$LOCK" 2>/dev/null; do + tries=$((tries + 1)) + if [ "$tries" -ge 40 ]; then + now=$(date +%s) + mtime=$(stat -f %m "$LOCK" 2>/dev/null || stat -c %Y "$LOCK" 2>/dev/null || echo "$now") + age=$((now - mtime)) + if [ "$age" -ge "${FM_BUSY_LOCK_STALE_SECS:-5}" ]; then + rmdir "$LOCK" 2>/dev/null || rm -rf "$LOCK" 2>/dev/null || true + mkdir "$LOCK" 2>/dev/null && break + fi + echo "error: busy-state lock timeout for $ID" >&2 + return 1 + fi + sleep 0.05 + done + return 0 +} +lock_release() { rmdir "$LOCK" 2>/dev/null || true; } + +write_record() { # + local tmp + tmp="$REC.tmp.$$" + printf 'v1 gen=%s seq=%s state=%s source=%s event=%s ts=%s\n' \ + "$1" "$2" "$NEW_STATE" "$SOURCE" "$EVENT" "$(date +%s)" > "$tmp" || return 1 + mv -f "$tmp" "$REC" +} + +old_umask=$(umask) +umask 077 + +if [ "$CMD" = arm ]; then + GEN="g$(date +%s).$$.$RANDOM" + lock_acquire || exit 1 + { + printf '%s\n' "$GEN" > "$GEN_FILE.tmp.$$" && mv -f "$GEN_FILE.tmp.$$" "$GEN_FILE" \ + && write_record "$GEN" 1 + } || { lock_release; umask "$old_umask"; echo "error: arm failed for $ID" >&2; exit 1; } + lock_release + umask "$old_umask" + printf '%s\n' "$GEN" + exit 0 +fi + +# apply / retire +if [ "$USE_CURRENT_GEN" = 1 ] && [ "$CMD" != retire ]; then + GEN=$(fm_busy_current_gen "$STATE" "$ID") || { + umask "$old_umask" + echo "error: no armed busy-state gen for $ID" >&2 + exit 1 + } +fi +if [ "$USE_CURRENT_GEN" != 1 ] || [ "$CMD" != retire ]; then + fm_busy_token_valid "$GEN" || { umask "$old_umask"; echo "error: invalid --gen" >&2; exit 1; } +fi + +lock_acquire || { umask "$old_umask"; exit 1; } +CURRENT=$(fm_busy_current_gen "$STATE" "$ID") || { + if [ "$CMD" = retire ] && [ ! -e "$GEN_FILE" ] && [ ! -L "$GEN_FILE" ]; then + rm -f "$REC" || { + lock_release + umask "$old_umask" + echo "error: busy-state retirement failed for $ID" >&2 + exit 1 + } + lock_release + umask "$old_umask" + exit 0 + fi + lock_release + umask "$old_umask" + echo "error: no armed busy-state gen for $ID" >&2 + exit 1 +} +if [ "$CMD" = retire ] && [ "$USE_CURRENT_GEN" = 1 ]; then + GEN=$CURRENT +fi +if [ "$GEN" != "$CURRENT" ]; then + lock_release + umask "$old_umask" + echo "error: stale busy-state gen for $ID (event rejected)" >&2 + exit 1 +fi +if [ "$CMD" = retire ]; then + rm -f "$GEN_FILE" "$REC" || { + lock_release + umask "$old_umask" + echo "error: busy-state retirement failed for $ID" >&2 + exit 1 + } + lock_release + umask "$old_umask" + exit 0 +fi +OLD_SEQ=0 +if [ -f "$REC" ]; then + old_line=$(head -n 1 "$REC" 2>/dev/null || true) + case "$old_line" in + *" gen=$GEN "*) + old_seq_field=${old_line##* seq=} + old_seq_field=${old_seq_field%% *} + case "$old_seq_field" in + ''|*[!0-9]*) OLD_SEQ=0 ;; + *) OLD_SEQ=$old_seq_field ;; + esac + ;; + esac +fi +write_record "$GEN" $((OLD_SEQ + 1)) || { + lock_release + umask "$old_umask" + echo "error: record write failed for $ID" >&2 + exit 1 +} +lock_release +umask "$old_umask" +exit 0 diff --git a/bin/fm-busy-lib.sh b/bin/fm-busy-lib.sh new file mode 100755 index 00000000000..d12cebc3041 --- /dev/null +++ b/bin/fm-busy-lib.sh @@ -0,0 +1,376 @@ +#!/usr/bin/env bash +# fm-busy-lib.sh - the ONE owner of firstmate's semantic busy-state contract. +# +# Design source: the captain-approved semantic busy-state redesign +# (2026-07-28): each harness adapter reports turn lifecycle through a +# machine-readable semantic source it owns, classification always exposes +# which source produced it, and missing, malformed, stale, unsupported, or +# unverified semantic data is UNKNOWN - never idle. Endpoint death is the only +# process-level override and yields dead, never busy. Child processes, CPU, +# process sleep state, marker mtimes, and the old global UI-regex OR are not +# state signals here; state/.turn-ended files remain wake NOTIFICATIONS +# owned by the watcher, not current-state truth. +# +# Record file: state/.busy-state - exactly one line, atomically replaced +# by bin/fm-busy-event.sh (the only writer): +# +# v1 gen= seq= state= source= event= ts= +# +# Gen sidecar: state/.busy-gen - one token minted when the task's busy +# wiring is armed (fm-spawn, or a documented recovery re-arm). Every event +# must present the current gen; an event or record carrying any other gen is +# a stale incarnation and is rejected (written events) or classified unknown +# (read records). seq is a strictly increasing integer per gen, advanced +# under the writer's lock, so an out-of-order apply can never regress a +# newer record. +# +# Semantic sources written by adapters (fm_busy_sources_for_harness owns the +# per-harness trust table; a record whose source is not trusted for the +# task's recorded harness classifies unknown, so one adapter's writer can +# never classify another adapter): +# pi-ext Pi/pi-signed per-task extension (agent_start/agent_settled) +# opencode-plugin OpenCode per-task plugin (session.status) +# claude-hook Claude lifecycle hooks (UserPromptSubmit/Stop/StopFailure/SessionEnd) +# codex-hook, codex-appserver reserved: Codex, gated by +# fm_busy_codex_semantic_source +# kimi-wire, kimi-hook reserved: standalone Kimi, gated by fm_busy_kimi_verified +# Firstmate-owned sources accepted for every converted adapter: +# fm-spawn the launch-brief turn seeded at spawn +# fm-interrupt a firstmate-controlled interruption of the worker +# fm-recovery a documented recovery reset after relaunch +# Classifier-only sources (never written into a record): +# endpoint-gone, herdr-native, grok-regex, missing, malformed, +# gen-mismatch, source-mismatch, kimi-unverified, codex-unverified, +# capture-failed, no-target +# +# Classification (fm_busy_classify): busy | idle | unknown | dead, always +# with the producing source as the second token. Precedence: +# 1. dead endpoint (fm_busy_classify_live only) -> dead endpoint-gone +# 2. standalone Kimi before verification -> unknown kimi-unverified +# 3. a valid, gen-matching, source-trusted record -> its state and source +# 4. no record at all: herdr's native busy verdict is trusted as busy +# (generation state is sufficient for busy, not for idle), then the +# Grok-only temporary regex fallback classifies a grok task from its +# rendered tail, then unknown missing +# 5. malformed, stale, or untrusted records -> unknown, never a fallback +# The Grok arm is the ONLY rendered-text classification that survives the +# redesign, because Grok's structured lifecycle was not credited-live-verified +# in the approved audit; it is scoped to harness=grok and can never classify +# another adapter. The delivery guards in bin/fm-tmux-lib.sh match rendered +# footers for submit acknowledgement and away-mode supervisor injection only; +# neither is a recorded worker state source. +# +# Codex negotiation (fm_busy_codex_appserver_observable, +# fm_busy_codex_hooks_verified): the approved contract prefers Codex's +# app-server turn lifecycle with capability negotiation, and sanctions its +# stable lifecycle hooks as the intermediate. Neither is usable on the +# installed binary, so Codex classifies unknown codex-unverified rather than +# falling back to idle, and fm-spawn installs no Codex busy wiring. +# docs/verification/supervision.md owns the evidence for both probes. +# +# Sourcing: set -u and set -e safe; no subshell-unfriendly globals. + +FM_BUSY_LIB_VERSION=v1 + +# Standalone-Kimi verification gate. Empty means no installed Kimi version +# has passed live verification, so every standalone Kimi task classifies +# unknown kimi-unverified and fm-spawn wires no Kimi busy events. Kimi's +# rendered moon-phase spinner is deliberately NOT a state source here: the +# approved redesign forbids inventing a Kimi UI signature, and that spinner +# is locale- and emoji-font-sensitive. +# +# Preferred source, in order: Wire mode's JSON-RPC `prompt` request lifetime, +# whose outstanding request exactly brackets a turn and returns finished, +# cancelled, or max_steps_reached (so it covers interruption, which `Stop` +# does not); then the documented lifecycle hooks, which must include +# `Interrupt` because Kimi documents that `Stop` does not fire on interrupts. +# +# To open the gate: install Kimi, live-verify the chosen source brackets a +# real turn on a firstmate-launched worker including the interrupt path, +# record the version, exact commands, and observed output in +# docs/verification/supervision.md, add the verified version string(s) here, +# and land the wiring in fm-spawn behind this same gate in the same change. +FM_BUSY_KIMI_VERIFIED_VERSIONS="" + +fm_busy_kimi_verified() { + [ -n "$FM_BUSY_KIMI_VERIFIED_VERSIONS" ] +} + +# fm_busy_codex_appserver_observable: capability/version negotiation for the +# Codex app-server turn lifecycle. Returns 0 only when a pane worker's turns +# are observable through the app-server protocol on the installed binary. +# codex-cli 0.145.0 verdict (live, 2026-07-28): NOT observable. The v2 +# protocol does define the needed turn lifecycle (turn/started plus a +# turn/completed status of completed, interrupted, failed, or inProgress), +# but an interactive TUI worker neither starts nor attaches to the +# app-server daemon, and `codex app-server daemon start` refuses outside the +# managed standalone install, so no client can observe a pane worker's turns. +fm_busy_codex_appserver_observable() { + return 1 +} + +# fm_busy_codex_hooks_verified: the sanctioned intermediate - Codex's stable +# hooks engine (UserPromptSubmit to open a turn, Stop and SessionEnd to close +# it). Returns 0 only once those hooks are live-verified to fire for a +# firstmate-launched worker. codex-cli 0.145.0 verdict (live, 2026-07-28): +# NOT verified. Firstmate-written project hooks under /.codex/ +# never fired in an interactive pane whose directory trust was granted, nor +# under `codex exec`, in either case with --dangerously-bypass-hook-trust, +# while global hooks fired in the same runs. Codex additionally exposes no +# StopFailure hook, so an API-error turn end would need separate coverage +# even after the discovery problem is solved. +fm_busy_codex_hooks_verified() { + return 1 +} + +# fm_busy_codex_semantic_source: 0 when ANY verified Codex semantic source +# exists. fm-spawn arms and wires Codex only behind this gate, and the +# classifier reports unknown codex-unverified until it opens. +fm_busy_codex_semantic_source() { + fm_busy_codex_appserver_observable || fm_busy_codex_hooks_verified +} + +fm_busy_record_path() { # + printf '%s/%s.busy-state' "$1" "$2" +} + +fm_busy_gen_path() { # + printf '%s/%s.busy-gen' "$1" "$2" +} + +# fm_busy_token_valid: conservative token charset shared by gen, source, and +# event fields. Anything else is malformed. +fm_busy_token_valid() { # + case "${1:-}" in + ''|*[!A-Za-z0-9._-]*) return 1 ;; + esac + return 0 +} + +# fm_busy_current_gen: the task's armed gen token, or failure when the busy +# contract has never been armed for this task. +fm_busy_current_gen() { # + local gen_file gen + gen_file=$(fm_busy_gen_path "$1" "$2") + [ -f "$gen_file" ] || return 1 + IFS= read -r gen < "$gen_file" 2>/dev/null || gen= + fm_busy_token_valid "$gen" || return 1 + printf '%s' "$gen" +} + +# fm_busy_sources_for_harness: the semantic sources trusted to classify a +# task recorded with . One line, space-separated, possibly empty. +# The firstmate-owned sources are appended for every converted adapter. +# Grok deliberately trusts nothing: it has no semantic writer yet, and its +# temporary rendered-tail fallback lives in the classifier, not in records. +fm_busy_sources_for_harness() { # + local adapter= + case "${1:-}" in + claude*) adapter=claude-hook ;; + codex*) + fm_busy_codex_semantic_source || { printf ''; return 0; } + adapter='codex-hook codex-appserver' + ;; + opencode*) adapter=opencode-plugin ;; + pi|pi-signed) adapter=pi-ext ;; + kimi*) + fm_busy_kimi_verified || { printf ''; return 0; } + adapter='kimi-wire kimi-hook' + ;; + *) printf ''; return 0 ;; + esac + printf '%s fm-spawn fm-interrupt fm-recovery' "$adapter" +} + +fm_busy_source_trusted() { # + local trusted + trusted=$(fm_busy_sources_for_harness "$1") + case " $trusted " in + *" $2 "*) return 0 ;; + esac + return 1 +} + +# fm_busy_record_read: parse and validate state/.busy-state against the +# armed gen. Prints " " for a valid record. +# Non-zero returns name the reason on stdout instead: +# missing no record file (or no armed gen and no record) +# malformed unparseable line, bad tokens, or a missing armed gen for an +# existing record +# gen-mismatch a record from a stale incarnation +fm_busy_record_read() { # + local state=$1 id=$2 rec gen line extra ver f + local r_gen='' r_seq='' r_state='' r_source='' r_event='' r_ts='' + rec=$(fm_busy_record_path "$state" "$id") + if [ ! -f "$rec" ]; then + printf 'missing' + return 1 + fi + if ! gen=$(fm_busy_current_gen "$state" "$id"); then + # A record without an armed gen has no incarnation to bind to. + printf 'malformed' + return 1 + fi + # shellcheck disable=SC2034 # extra exists only to prove the record is one line + { IFS= read -r line && ! IFS= read -r extra; } < "$rec" 2>/dev/null || { + printf 'malformed' + return 1 + } + # `read -a` rather than `set --`: it never glob-expands a field and never + # touches the caller's positional parameters or shell options. + local -a fields + IFS=' ' read -r -a fields <<< "$line" + ver=${fields[0]:-} + [ "$ver" = "$FM_BUSY_LIB_VERSION" ] || { printf 'malformed'; return 1; } + for f in "${fields[@]:1}"; do + case "$f" in + gen=*) r_gen=${f#gen=} ;; + seq=*) r_seq=${f#seq=} ;; + state=*) r_state=${f#state=} ;; + source=*) r_source=${f#source=} ;; + event=*) r_event=${f#event=} ;; + ts=*) r_ts=${f#ts=} ;; + *) printf 'malformed'; return 1 ;; + esac + done + fm_busy_token_valid "$r_gen" || { printf 'malformed'; return 1; } + fm_busy_token_valid "$r_source" || { printf 'malformed'; return 1; } + fm_busy_token_valid "$r_event" || { printf 'malformed'; return 1; } + case "$r_seq" in ''|*[!0-9]*) printf 'malformed'; return 1 ;; esac + case "$r_ts" in ''|*[!0-9]*) printf 'malformed'; return 1 ;; esac + case "$r_state" in busy|idle|unknown) : ;; *) printf 'malformed'; return 1 ;; esac + if [ "$r_gen" != "$gen" ]; then + printf 'gen-mismatch' + return 1 + fi + printf '%s %s %s %s' "$r_state" "$r_source" "$r_event" "$r_seq" +} + +# fm_busy_grok_tail_busy: the Grok-only temporary rendered-tail fallback. +# Consumes the tail on stdin; 0 when Grok's verified busy signature matches. +# FM_BUSY_REGEX still globally overrides the signature, mirroring the +# historical operator escape hatch. +fm_busy_grok_tail_busy() { + grep -v '^[[:space:]]*$' | tail -12 \ + | grep -qiE "${FM_BUSY_REGEX:-${FM_TMUX_GROK_BUSY_REGEX_DEFAULT:-Ctrl\\+c:cancel}}" +} + +# fm_busy_classify: semantic classification for a task whose endpoint the +# caller has already established as present. Prints " ": +# busy|idle|unknown plus the producing source (see header). Never probes +# process state. is optional pre-captured plain output used only by +# the Grok arm; when absent the Grok arm captures through fm_backend_capture +# if available, else reports unknown capture-failed. +fm_busy_classify() { # [tail40] + local backend=$1 target=$2 harness=$3 id=$4 state=$5 tail40=${6-} + local out rc r_state r_source native + case "$harness" in + kimi*) + if ! fm_busy_kimi_verified; then + printf 'unknown kimi-unverified' + return 0 + fi + ;; + codex*) + if ! fm_busy_codex_semantic_source; then + printf 'unknown codex-unverified' + return 0 + fi + ;; + esac + out=$(fm_busy_record_read "$state" "$id") && rc=0 || rc=$? + if [ "$rc" = 0 ]; then + r_state=${out%% *} + out=${out#* } + r_source=${out%% *} + if fm_busy_source_trusted "$harness" "$r_source"; then + printf '%s %s' "$r_state" "$r_source" + else + printf 'unknown source-mismatch' + fi + return 0 + fi + case "$out" in + malformed|gen-mismatch) + printf 'unknown %s' "$out" + return 0 + ;; + esac + # No record at all. A native herdr busy verdict is semantic enough to trust + # for BUSY (streaming means a turn is running); native idle is narrower + # than turn state (a long foreground tool call reads idle) and stays + # unknown here. + if [ "$backend" = herdr ] && command -v fm_backend_busy_state >/dev/null 2>&1; then + native=$(fm_backend_busy_state "$backend" "$target" 2>/dev/null || true) + if [ "$native" = busy ]; then + printf 'busy herdr-native' + return 0 + fi + fi + case "$harness" in + grok*) + if [ -z "$tail40" ]; then + if command -v fm_backend_capture >/dev/null 2>&1; then + tail40=$(fm_backend_capture "$backend" "$target" 40 2>/dev/null) || { + printf 'unknown capture-failed' + return 0 + } + else + printf 'unknown capture-failed' + return 0 + fi + fi + if printf '%s' "$tail40" | fm_busy_grok_tail_busy; then + printf 'busy grok-regex' + else + printf 'idle grok-regex' + fi + return 0 + ;; + esac + printf 'unknown missing' +} + +# fm_busy_classify_live: fm_busy_classify behind the one process-level +# override - a gone endpoint is dead, never busy. Requires fm-backend.sh to +# be sourced for fm_backend_target_exists. +fm_busy_classify_live() { # [expected-label] + local backend=$1 target=$2 harness=$3 id=$4 state=$5 label=${6-} + if [ -z "$target" ]; then + printf 'unknown no-target' + return 0 + fi + if ! fm_backend_target_exists "$backend" "$target" "$label" 2>/dev/null; then + printf 'dead endpoint-gone' + return 0 + fi + fm_busy_classify "$backend" "$target" "$harness" "$id" "$state" +} + +# fm_busy_classify_meta: classify a task from its recorded metadata, so every +# consumer resolves backend, target, and harness the same way instead of +# re-deriving them. Requires fm-backend.sh to be sourced. is +# optional pre-captured plain output reused by the Grok arm. +fm_busy_classify_meta() { # [tail40] + local meta=$1 id=$2 state=$3 tail40=${4-} backend target harness + [ -f "$meta" ] || { printf 'unknown missing'; return 0; } + backend=$(fm_backend_of_meta "$meta") + target=$(fm_backend_target_of_meta "$meta") + harness=$(fm_meta_get "$meta" harness) + if [ -z "$target" ]; then + printf 'unknown no-target' + return 0 + fi + fm_busy_classify "$backend" "$target" "$harness" "$id" "$state" "$tail40" +} + +# fm_busy_is_busy: boolean view for callers that only gate on provable +# activity. 0 iff the classification verdict is exactly busy; idle, unknown, +# and dead all return 1, so an unknown can never be silently promoted to +# either boolean pole - callers that must distinguish idle from unknown read +# the full classification instead. +fm_busy_is_busy() { # [tail40] + local verdict + verdict=$(fm_busy_classify "$@") + [ "${verdict%% *}" = busy ] +} diff --git a/bin/fm-config-inherit-lib.sh b/bin/fm-config-inherit-lib.sh index 22109aa87aa..bffbd5234d7 100644 --- a/bin/fm-config-inherit-lib.sh +++ b/bin/fm-config-inherit-lib.sh @@ -6,7 +6,8 @@ # profile rules, primary config/crew-harness=codex makes a secondmate's crewmates # spawn on codex too, primary config/backlog-backend=manual makes that home # hand-edit backlog files too, primary config/backend pins that home's local -# runtime-backend default for future spawns, and primary +# runtime-backend default for future spawns, primary config/startup-memory-budget +# bounds that home's startup-memory curation, and primary # config/herdr-presentation-spaces enables the same default-off Herdr presentation # projection). It also pushes the one primary-authoritative shared # captain-preference file, data/captain-shared.md, into each secondmate home's @@ -32,6 +33,9 @@ # is deliberately NOT in the list: it is the primary's own setting for launching # secondmates, and a secondmate never spawns secondmates, so it must not flow # downstream. +# +# shellcheck source=bin/fm-startup-memory-budget-lib.sh +. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fm-startup-memory-budget-lib.sh" # The one shared data file in this inheritance contract. There is deliberately # no shared learnings file. @@ -42,7 +46,7 @@ FM_SHARED_CAPTAIN_MODE="444" # The declared inheritable set (space-separated, config-dir-relative item paths). # Extend here to inherit more of the primary's local config; override via the # environment only in tests. Items must not contain whitespace. -FM_INHERITABLE_CONFIG="${FM_INHERITABLE_CONFIG:-crew-dispatch.json crew-harness backlog-backend backend herdr-presentation-spaces}" +FM_INHERITABLE_CONFIG="${FM_INHERITABLE_CONFIG:-crew-dispatch.json crew-harness backlog-backend backend herdr-presentation-spaces startup-memory-budget}" fm_inherit_file_mode() { if [ "$(uname)" = Darwin ]; then @@ -401,6 +405,47 @@ propagate_inheritable_config() { esac src="$src_config/$item" dest="$dest_config/$item" + # This one scalar config is consumed as a local safety boundary, so reject + # every unsafe or malformed source/destination artifact before the generic + # byte-copy behavior below can treat it as ordinary inherited material. + if [ "$item" = "$FM_STARTUP_MEMORY_BUDGET_FILE" ]; then + if [ -e "$src_config" ] || [ -L "$src_config" ]; then + if ! fm_startup_memory_budget_config_dir_safe "$src_config"; then + reason="unsafe primary config directory: $FM_STARTUP_MEMORY_BUDGET_ERROR" + warn_inheritable_config_error "$item" "$src_config" "$reason" + record_inheritable_config_result "$item" error "$reason" + rc=1 + continue + fi + fi + if [ -e "$dest_config" ] || [ -L "$dest_config" ]; then + if ! fm_startup_memory_budget_config_dir_safe "$dest_config"; then + reason="unsafe destination config directory: $FM_STARTUP_MEMORY_BUDGET_ERROR" + warn_inheritable_config_error "$item" "$dest_config" "$reason" + record_inheritable_config_result "$item" error "$reason" + rc=1 + continue + fi + fi + if [ -e "$src" ] || [ -L "$src" ]; then + if ! fm_startup_memory_budget_file_valid "$src"; then + reason="unsafe or invalid primary source: $FM_STARTUP_MEMORY_BUDGET_ERROR" + warn_inheritable_config_error "$item" "$src" "$reason" + record_inheritable_config_result "$item" error "$reason" + rc=1 + continue + fi + fi + if [ -e "$dest" ] || [ -L "$dest" ]; then + if ! fm_startup_memory_budget_file_valid "$dest"; then + reason="unsafe or invalid destination: $FM_STARTUP_MEMORY_BUDGET_ERROR" + warn_inheritable_config_error "$item" "$dest" "$reason" + record_inheritable_config_result "$item" error "$reason" + rc=1 + continue + fi + fi + fi if [ -f "$src" ]; then if ! destination_allows_inherited_item "$dest_config" "$item"; then reason=$(inheritable_config_skip_reason) diff --git a/bin/fm-crew-state.sh b/bin/fm-crew-state.sh index 32dff236687..30fc7b7236e 100755 --- a/bin/fm-crew-state.sh +++ b/bin/fm-crew-state.sh @@ -62,6 +62,8 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}" . "$SCRIPT_DIR/fm-backend.sh" # shellcheck source=bin/fm-classify-lib.sh . "$SCRIPT_DIR/fm-classify-lib.sh" +# shellcheck source=bin/fm-busy-lib.sh +. "$SCRIPT_DIR/fm-busy-lib.sh" ID=${1:-} [ -n "$ID" ] || { echo "usage: fm-crew-state.sh " >&2; exit 2; } @@ -149,46 +151,19 @@ pane_readable() { # *) fm_backend_capture "$TASK_BACKEND" "$1" 1 "$EXPECTED_LABEL" >/dev/null 2>&1 ;; esac } -# crew_pane_is_busy: the busy-signature fallback, backend-aware the same way - -# fm_backend_busy_state's native semantic state (herdr's agent.get) when -# available, else the shared harness-scoped pane-regex reader -# (fm_pane_is_busy, bin/fm-tmux-lib.sh). -# -# `busy` alone is trusted outright. Both `idle` and unknown/unparseable fall -# through to the shared tail-regex corroboration, NOT just unknown: herdr's -# agent.get reports generation state ("working" while the model is streaming -# a turn, "done"/"idle" once it is not - docs/herdr-backend.md "Busy state"), -# which is a narrower signal than "this crew's turn/tool call is still in -# progress". A crew blocked on its own long-running foreground tool call (e.g. -# `no-mistakes axi run` without --yes, which blocks synchronously until a gate -# or outcome - AGENTS.md section 7) is not generating for that whole span, so -# agent.get can read idle/blocked (bin/backends/herdr.sh maps both to `idle`) -# while the pane's own rendered text still shows that recorded harness's busy -# signature for the entire tool call, exactly like tmux's regex-only reader -# would correctly report. Trusting herdr's `idle` -# outright (skipping that corroboration) is what let a still-working crew read -# as not-busy here, and - combined with a no-mistakes run-step lookup that also -# missed attribution (see nm_runs_status_for_branch) - as not provably working in -# fm-classify-lib.sh, triggering an immediate (non-wedge) stale wake instead of -# the absorb-then-escalate path. A genuinely human-blocked agent (a permission -# dialog, not mid-tool-call) does not render the busy banner, so this -# corroboration does not mask that case: it stays correctly not-busy. -crew_pane_is_busy() { # - case "$TASK_BACKEND" in - tmux) fm_pane_is_busy "$1" "$HARNESS" ;; - *) - local bs tail40 - bs=$(fm_backend_busy_state "$TASK_BACKEND" "$1" 2>/dev/null) - case "$bs" in - busy) return 0 ;; - *) - tail40=$(fm_backend_capture "$TASK_BACKEND" "$1" 40 "$EXPECTED_LABEL" 2>/dev/null) || return 1 - printf '%s' "$tail40" | grep -v '^[[:space:]]*$' | tail -12 \ - | fm_busy_lines_match "$HARNESS" - ;; - esac - ;; +# crew_busy_verdict: the crew's semantic busy state from the one contract +# owner (bin/fm-busy-lib.sh), as " ". A converted +# adapter answers from its own lifecycle record; Grok answers from its +# isolated rendered-tail fallback; a herdr crew's native `busy` is accepted +# when no record exists, but its native `idle` is NOT, because agent.get +# reports generation state (idle while a crew blocks on its own long-running +# foreground tool call) rather than turn state. +crew_busy_verdict() { # + local tail40='' + case "$HARNESS" in + grok*) tail40=$(fm_backend_capture "$TASK_BACKEND" "$1" 40 "$EXPECTED_LABEL" 2>/dev/null) || tail40='' ;; esac + fm_busy_classify "$TASK_BACKEND" "$1" "$HARNESS" "$ID" "$STATE" "$tail40" } # --- no-mistakes run lookup (authoritative when a run matches this branch) -- @@ -605,9 +580,17 @@ fi pane_readable "$BACKEND_TARGET" || emit unknown none "backend target gone: $BACKEND_TARGET" # Secondmates idle on their own watcher (idle pane = healthy), so the busy -# signature is not meaningful for them; read their state from the status log only. -if [ "$KIND" != secondmate ] && crew_pane_is_busy "$BACKEND_TARGET"; then - emit working pane "harness busy" +# state is not meaningful for them; read their state from the status log only. +# Only an exact busy verdict reports working here, and only an exact idle +# verdict permits the status-log fallback below. Missing, malformed, stale, or +# unverified semantic state remains unknown. +if [ "$KIND" != secondmate ]; then + BUSY_VERDICT=$(crew_busy_verdict "$BACKEND_TARGET") + case "${BUSY_VERDICT%% *}" in + busy) emit working pane "harness busy (${BUSY_VERDICT#* })" ;; + idle) ;; + *) emit unknown pane "harness state unavailable ($BUSY_VERDICT)" ;; + esac fi # Fall back to the status log's last line, but ONLY when its verb maps to a real diff --git a/bin/fm-ff-lib.sh b/bin/fm-ff-lib.sh index e6d6801a79f..bce9993ae78 100644 --- a/bin/fm-ff-lib.sh +++ b/bin/fm-ff-lib.sh @@ -25,6 +25,8 @@ # shared default branch or any other worktree's checkout. SUB_HOME_MARKER="${SUB_HOME_MARKER:-.fm-secondmate-home}" +# shellcheck source=bin/fm-secondmate-registry-lib.sh +. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/fm-secondmate-registry-lib.sh" # --- helpers --------------------------------------------------------------- @@ -231,20 +233,6 @@ dirty_status() { fi } -secondmate_registry_field() { - local reg=$1 id=$2 key=$3 line value - [ -f "$reg" ] || return 1 - line=$(grep -E "^- $id( |$)" "$reg" | tail -1 || true) - [ -n "$line" ] || return 1 - case "$key" in - home) value=$(printf '%s\n' "$line" | sed -n 's/.*(home:[[:space:]]*\([^;)]*\);.*/\1/p' | sed 's/[[:space:]]*$//') ;; - projects) value=$(printf '%s\n' "$line" | sed -n 's/.*; projects:[[:space:]]*\([^;)]*\); added .*/\1/p' | sed 's/[[:space:]]*$//') ;; - *) return 1 ;; - esac - [ -n "$value" ] || return 1 - printf '%s\n' "$value" -} - # List this home's LIVE secondmate direct reports from state/.meta records. # The meta file is the liveness signal; data/secondmates.md is only the fallback # for durable fields such as home= when an older/incomplete meta lacks them. diff --git a/bin/fm-fleet-snapshot.sh b/bin/fm-fleet-snapshot.sh index 1dee81bb84a..f8598d9ea19 100755 --- a/bin/fm-fleet-snapshot.sh +++ b/bin/fm-fleet-snapshot.sh @@ -839,7 +839,7 @@ BASH | select(startswith("- ")) | (capture("^- (?[^[:space:]]+)")?) as $id | select($id != null) - | (capture("\\(home:[[:space:]]*(?[^;)]*);")?) as $home + | (capture("^.*\\(home:[[:space:]]*(?[^;)]*);[[:space:]]*scope:[[:space:]]*.*;[[:space:]]*projects:[[:space:]]*[^;)]*;[[:space:]]*added[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2}\\)[[:space:]]*$")?) as $home | {id:$id.id,home:($home.home // null),registered:true, registry_error:(if $home == null or ($home.home | length) == 0 then "registry entry has no home" else null end)} ] | group_by(.id) diff --git a/bin/fm-herdr-session-cleanup.sh b/bin/fm-herdr-session-cleanup.sh index 05b6db9f947..2dc4c227941 100755 --- a/bin/fm-herdr-session-cleanup.sh +++ b/bin/fm-herdr-session-cleanup.sh @@ -62,14 +62,6 @@ fm_herdr_cleanup_home_identity() { (cd "$FM_HOME" 2>/dev/null && pwd -P) } -fm_herdr_cleanup_process_argv0() { # - printf '%s' "$1" | jq -er ' - .result.process_info.foreground_processes[0] as $process - | ($process.argv0 // $process.argv[0]) - | select(type == "string" and length > 0) - ' 2>/dev/null -} - fm_herdr_cleanup_journal_matches() { # <session> <home-real> local title=$1 session=$2 home_real=$3 journal id expected journal_home [ -d "$STATE" ] && [ ! -L "$STATE" ] || return 1 @@ -122,46 +114,6 @@ fm_herdr_cleanup_unique_match() { # <title> <session> <home-real> fi } -fm_herdr_cleanup_process_is_idle_shell() { # <session> <pane-id> - local session=$1 pane=$2 info shell_pid foreground_pgid count - local process_pid name argv0 shell_name rows stat ps_bin - info=$(fm_backend_herdr_cli "$session" pane process-info --pane "$pane" 2>/dev/null) || return 1 - printf '%s' "$info" | jq -e --arg pane "$pane" ' - .result.type == "pane_process_info" - and .result.process_info.pane_id == $pane - ' >/dev/null 2>&1 || return 1 - shell_pid=$(printf '%s' "$info" | jq -er \ - '.result.process_info.shell_pid | select(type == "number" and . > 1) | floor' 2>/dev/null) || return 1 - foreground_pgid=$(printf '%s' "$info" | jq -er \ - '.result.process_info.foreground_process_group_id | select(type == "number" and . > 1) | floor' 2>/dev/null) || return 1 - [ "$foreground_pgid" = "$shell_pid" ] || return 1 - count=$(printf '%s' "$info" | jq -er \ - '.result.process_info.foreground_processes | select(type == "array") | length' 2>/dev/null) || return 1 - [ "$count" -eq 1 ] || return 1 - process_pid=$(printf '%s' "$info" | jq -er \ - '.result.process_info.foreground_processes[0].pid | select(type == "number") | floor' 2>/dev/null) || return 1 - [ "$process_pid" = "$shell_pid" ] || return 1 - name=$(printf '%s' "$info" | jq -er \ - '.result.process_info.foreground_processes[0].name | select(type == "string" and length > 0)' 2>/dev/null) || return 1 - argv0=$(fm_herdr_cleanup_process_argv0 "$info") || return 1 - shell_name=${name##*/} - argv0=${argv0#-} - argv0=${argv0##*/} - [ "$argv0" = "$shell_name" ] || return 1 - case "$shell_name" in sh|bash|zsh|dash|ksh|fish) ;; *) return 1 ;; esac - - ps_bin=${FM_HERDR_PS_BIN:-ps} - command -v "$ps_bin" >/dev/null 2>&1 || return 1 - rows=$("$ps_bin" -axo pid=,ppid= 2>/dev/null) || return 1 - printf '%s\n' "$rows" | awk -v shell="$shell_pid" ' - $1 == shell { found++ } - $2 == shell { child++ } - END { exit(found == 1 && child == 0 ? 0 : 1) } - ' || return 1 - stat=$("$ps_bin" -p "$shell_pid" -o stat= 2>/dev/null | tr -d '[:space:]') || return 1 - case "$stat" in S*|I*) ;; *) return 1 ;; esac -} - fm_herdr_cleanup_snapshot_candidate() { # <snapshot> <workspace> <title> <token> <bound-workspace> <bound-tab> <bound-pane> local snapshot=$1 workspace=$2 title=$3 token=$4 local bound_workspace=$5 bound_tab=$6 bound_pane=$7 record @@ -242,7 +194,7 @@ fm_herdr_cleanup_revalidate() { # <session> <workspace> <tab> <pane> <title> <to and .result.panes[0].pane_id == $pane ' >/dev/null 2>&1 || return 1 [ "$(fm_backend_herdr_pane_agent_state "$session" "$pane")" = no-agent ] || return 1 - fm_herdr_cleanup_process_is_idle_shell "$session" "$pane" || return 1 + fm_backend_herdr_pane_idle_shell_pid "$session" "$pane" >/dev/null || return 1 focus=$(fm_backend_herdr_projection_focus_snapshot "$session") || return 1 [ "${focus#*$'\t'}" != "$tab" ] } @@ -296,7 +248,7 @@ fm_herdr_cleanup_one() { # <session> <workspace> <title> <home-real> tab=$FM_HERDR_CLEANUP_TAB pane=$FM_HERDR_CLEANUP_PANE if [ "$(fm_backend_herdr_pane_agent_state "$session" "$pane")" != no-agent ] \ - || ! fm_herdr_cleanup_process_is_idle_shell "$session" "$pane"; then + || ! fm_backend_herdr_pane_idle_shell_pid "$session" "$pane" >/dev/null; then fm_herdr_cleanup_warn "$id preserved because its pane is not a provably idle childless shell" fm_lock_release "$presentation_lock" || true fm_lock_release "$task_lock" || true diff --git a/bin/fm-home-seed.sh b/bin/fm-home-seed.sh index d506b95e4f8..4b5b9815bcc 100755 --- a/bin/fm-home-seed.sh +++ b/bin/fm-home-seed.sh @@ -27,8 +27,9 @@ # to override the registry routing scope. Otherwise the registry summary # and scope are derived from the filled charter brief. # fm-home-seed.sh validate -# Refuse duplicate ids, duplicate homes, and nested or overlapping homes in -# data/secondmates.md. +# Refuse records that operational consumers cannot parse, unavailable or +# unsafe registry files when present, non-absolute or unresolvable homes, +# duplicate ids or homes, and nested or overlapping homes. set -eu SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -38,16 +39,14 @@ DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}" PROJECTS="${FM_PROJECTS_OVERRIDE:-$FM_HOME/projects}" REG="$DATA/secondmates.md" SUB_HOME_MARKER=".fm-secondmate-home" +# shellcheck source=bin/fm-secondmate-registry-lib.sh +. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh" usage() { echo "usage: fm-home-seed.sh <id> <home|-> {<project>...|--no-projects}" >&2 echo " fm-home-seed.sh validate" >&2 } -registry_home_for_line() { - sed -n 's/^[^(]*(home: \([^;)]*\);.*/\1/p' -} - normalize_registry_text() { awk ' { @@ -179,13 +178,15 @@ registry_home_conflict_for_assignment() { local id=$1 home=$2 target line registered_id registered_home registered_key [ -f "$REG" ] || return 1 target=$(resolved_path "$home") - while IFS= read -r line; do + while IFS= read -r line || [ -n "$line" ]; do case "$line" in "- "*) - registered_id=${line#- } - registered_id=${registered_id%% *} - registered_home=$(printf '%s\n' "$line" | registry_home_for_line) - [ -n "$registered_home" ] || continue + if ! secondmate_registry_parse_line "$line"; then + echo "error: malformed secondmate registry entry: $line" >&2 + return 1 + fi + registered_id=$SECONDMATE_REGISTRY_ID + registered_home=$SECONDMATE_REGISTRY_HOME registered_key=$(resolved_path "$registered_home") if [ "$registered_key" = "$target" ]; then [ "$registered_id" = "$id" ] && continue @@ -206,14 +207,16 @@ registry_id_conflict_for_assignment() { local id=$1 home=$2 target line registered_id registered_home registered_key [ -f "$REG" ] || return 1 target=$(resolved_path "$home") - while IFS= read -r line; do + while IFS= read -r line || [ -n "$line" ]; do case "$line" in "- "*) - registered_id=${line#- } - registered_id=${registered_id%% *} + secondmate_registry_parse_line "$line" || { + echo "error: malformed secondmate registry entry: $line" >&2 + return 1 + } + registered_id=$SECONDMATE_REGISTRY_ID [ "$registered_id" = "$id" ] || continue - registered_home=$(printf '%s\n' "$line" | registry_home_for_line) - [ -n "$registered_home" ] || continue + registered_home=$SECONDMATE_REGISTRY_HOME registered_key=$(resolved_path "$registered_home") [ "$registered_key" = "$target" ] && continue printf '%s\n' "$registered_key" @@ -225,76 +228,11 @@ registry_id_conflict_for_assignment() { } validate_registry() { - local tmp line id registered_home home_key duplicate_homes duplicate_ids overlaps - tmp=$(mktemp "${TMPDIR:-/tmp}/fm-firstmates.XXXXXX") - if [ -f "$REG" ]; then - while IFS= read -r line; do - case "$line" in - "- "*) - id=${line#- } - id=${id%% *} - registered_home=$(printf '%s\n' "$line" | registry_home_for_line) - [ -n "$registered_home" ] || continue - home_key=$(resolved_path "$registered_home") - printf '%s\t%s\n' "$home_key" "$id" >> "$tmp" - ;; - esac - done < "$REG" - fi - duplicate_homes=$(awk -F '\t' ' - { - if (($1 in owner) && owner[$1] != $2) { - print $1 ": " owner[$1] ", " $2 - bad=1 - } else { - owner[$1]=$2 - } - } - END { exit bad ? 1 : 0 } - ' "$tmp" 2>/dev/null) || { - rm -f "$tmp" - printf 'error: duplicate secondmate home assignment:\n%s\n' "$duplicate_homes" >&2 - return 1 - } - duplicate_ids=$(awk -F '\t' ' - { - if ($2 in home) { - print $2 ": " home[$2] ", " $1 - bad=1 - } else { - home[$2]=$1 - } - } - END { exit bad ? 1 : 0 } - ' "$tmp" 2>/dev/null) || { - rm -f "$tmp" - printf 'error: duplicate secondmate id assignment:\n%s\n' "$duplicate_ids" >&2 - return 1 - } - overlaps=$(awk -F '\t' ' - function ancestor(a, b) { return a != b && index(b, a "/") == 1 } - { - for (i = 1; i <= count; i++) { - if (ancestor($1, path[i])) { - print $1 " (" $2 ") contains " path[i] " (" id[i] ")" - bad=1 - } else if (ancestor(path[i], $1)) { - print path[i] " (" id[i] ") contains " $1 " (" $2 ")" - bad=1 - } - } - count++ - path[count]=$1 - id[count]=$2 - } - END { exit bad ? 1 : 0 } - ' "$tmp" 2>/dev/null) || { - rm -f "$tmp" - printf 'error: overlapping secondmate home assignment:\n%s\n' "$overlaps" >&2 + [ -e "$REG" ] || [ -L "$REG" ] || return 0 + secondmate_registry_validate_bindings "$REG" resolved_path || { + printf 'error: %s\n' "$SECONDMATE_REGISTRY_ERROR" >&2 return 1 } - rm -f "$tmp" - return 0 } join_projects() { diff --git a/bin/fm-pending-reply-lib.sh b/bin/fm-pending-reply-lib.sh index 70ad5245c24..cdca29e67b3 100755 --- a/bin/fm-pending-reply-lib.sh +++ b/bin/fm-pending-reply-lib.sh @@ -573,6 +573,22 @@ fm_pending_reply_fallback_idle_eligible() { # <record-path> [ "$age" -ge "$grace" ] } +# fm_pending_reply_backend_observation: one busy/idle observation of a +# SECONDMATE endpoint, without ever reading its conversation. +# +# Deliberately NOT the semantic busy-state contract (bin/fm-busy-lib.sh). +# That contract covers ordinary task workers, whose turn lifecycle firstmate +# wires at spawn; a secondmate has no such wiring because an idle secondmate +# pane is healthy and it runs no supervised turn sequence of its own. This +# observation exists only to notice a busy-then-idle transition around one +# delivered request, so it is a delivery-confirmation signal in the same +# category as the submit acknowledgement in bin/fm-tmux-lib.sh - never task +# state, and never a source consumers can confuse with semantic state. +# +# It stays harness-scoped (fm_busy_lines_match with the recorded harness, no +# global OR of every vendor signature), so one harness's output cannot make +# another read busy, and a weak rendered idle degrades to `fallback-idle`, +# which the caller accepts as idle only after its grace window. fm_pending_reply_backend_observation() { # <backend> <target> [expected-label] [harness] local backend=$1 target=$2 expected_label=${3-} harness=${4-} native tail40 native=$(fm_backend_busy_state "$backend" "$target" 2>/dev/null || printf 'unknown') diff --git a/bin/fm-public-followup-emit.sh b/bin/fm-public-followup-emit.sh new file mode 100755 index 00000000000..c7510e9b33c --- /dev/null +++ b/bin/fm-public-followup-emit.sh @@ -0,0 +1,260 @@ +#!/usr/bin/env bash +# fm-public-followup-emit.sh - emit ONE structured terminal work result for work +# bound to a public commitment, into the owning home's private event inbox. +# +# WHY THIS EXISTS: a public promise is kept by the home that owns the relay +# consent and the thread binding. The home doing the work only has to report a +# TYPED result. Firstmate must never recover the source home, work id, outcome, +# or deliverables by parsing a free-form "done: ..." status sentence, so this +# script is the structured channel that carries them. +# +# WHAT IT DOES NOT DO: it never posts anything, never reads relay credentials, +# and never resolves a public thread. Outward delivery stays with the owning +# home (bin/fm-public-followup.sh deliver). +# +# Usage: +# fm-public-followup-emit.sh --home <owning-home> \ +# --obligation <obligation-id> --relation <relation-id> \ +# --source-home <main|secondmate:<id>> --work-id <task-id> \ +# --generation <n> --outcome <outcome-type> \ +# [--deliverable <key>=<value>]... \ +# (--outcome-text <text> | --outcome-text-file <path> | --outcome-text -) +# +# Options: +# --home <path> The home that owns the public commitment (the primary +# that took the mention). Must already have a +# registration for --obligation; see +# `fm-public-followup.sh register`. +# --obligation <id> tasks-axi public-followup obligation id. +# --relation <id> The relation_id this work fulfills or contributes to. +# --source-home <id> This worker's stable home identity, exactly as bound: +# "main" or "secondmate:<stable-id>". +# --work-id <id> This worker's exact task id, exactly as bound. +# --generation <n> The bound relation generation (integer >= 1). +# --outcome <type> Typed outcome. tasks-axi owns the vocabulary and +# refuses anything it does not accept; this script only +# checks the token is a safe slug. +# --deliverable k=v Repeatable safe deliverable (for example +# pr_url=https://...). tasks-axi owns which keys a given +# expected-final type permits. +# --outcome-text ... Public-safe outcome sentence, from an argument, a +# file, or stdin ("-"). Collapsed to one line; the +# event builder bounds it by codepoint, so control +# characters cannot survive. +# +# Output: the event id on stdout. Exit 0 on a published or already-present event +# (both are successes: the id is derived, so re-emitting the same terminal result +# is a no-op), 2 on a usage or validation error, 1 on a publication failure. +# +# IDEMPOTENCY: the event id is a digest of the identity tuple (obligation, +# relation, source home, work id, generation, outcome type, deliverables), so a +# retry, a duplicate report, or a rerun after restart resolves to the same file +# and the first published copy wins. Nothing here needs coordination. +# +# SAFETY: the event is published through the shared private-artifact primitive - +# atomic rename into place, single link, mode 0600 (never executable), inside a +# 0700 directory this script refuses to create. The owning home must already have +# registered the obligation, so a home that never opted into the relay can never +# be given public-followup artifacts by a child. +set -u + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# shellcheck source=bin/fm-public-followup-lib.sh +. "$SCRIPT_DIR/fm-public-followup-lib.sh" + +usage() { + cat >&2 <<'EOF' +usage: fm-public-followup-emit.sh --home <owning-home> --obligation <id> --relation <id> + --source-home <main|secondmate:<id>> --work-id <id> --generation <n> + --outcome <type> [--deliverable <key>=<value>]... + (--outcome-text <text> | --outcome-text-file <path> | --outcome-text -) +EOF +} + +# The header comment IS the help text, so the two can never drift apart. +help() { + sed -n '2,/^set -u$/p' "$0" | sed '$d; s/^# \{0,1\}//' +} + +die() { printf 'fm-public-followup-emit: %s\n' "$1" >&2; exit "${2:-2}"; } + +HOME_DIR= +OBLIGATION= +RELATION= +SOURCE_HOME= +WORK_ID= +GENERATION= +OUTCOME= +TEXT_SOURCE= +TEXT_MODE= +DELIVERABLE_KEYS=() +DELIVERABLE_VALUES=() + +case "${1:-}" in + --help|-h) help; exit 0 ;; + '') usage; exit 2 ;; +esac + +while [ "$#" -gt 0 ]; do + case "$1" in + --home) shift; HOME_DIR=${1:-} ;; + --obligation) shift; OBLIGATION=${1:-} ;; + --relation) shift; RELATION=${1:-} ;; + --source-home) shift; SOURCE_HOME=${1:-} ;; + --work-id) shift; WORK_ID=${1:-} ;; + --generation) shift; GENERATION=${1:-} ;; + --outcome) shift; OUTCOME=${1:-} ;; + --outcome-text) shift; TEXT_MODE='inline'; TEXT_SOURCE=${1:-} ;; + --outcome-text-file) shift; TEXT_MODE='file'; TEXT_SOURCE=${1:-} ;; + --deliverable) + shift + case "${1:-}" in + *=*) ;; + *) die "--deliverable needs <key>=<value>, got '${1:-}'" ;; + esac + DELIVERABLE_KEYS+=("${1%%=*}") + DELIVERABLE_VALUES+=("${1#*=}") + ;; + --help|-h) help; exit 0 ;; + *) die "unknown argument '$1'" ;; + esac + shift || true +done + +[ -n "$HOME_DIR" ] || { usage; exit 2; } +[ -n "$OBLIGATION" ] || { usage; exit 2; } +[ -n "$RELATION" ] || { usage; exit 2; } +[ -n "$SOURCE_HOME" ] || { usage; exit 2; } +[ -n "$WORK_ID" ] || { usage; exit 2; } +[ -n "$GENERATION" ] || { usage; exit 2; } +[ -n "$OUTCOME" ] || { usage; exit 2; } +[ -n "$TEXT_MODE" ] || { usage; exit 2; } + +fm_pf_slug_valid "$OBLIGATION" || die "unsafe obligation id: $OBLIGATION" +fm_pf_slug_valid "$RELATION" || die "unsafe relation id: $RELATION" +fm_pf_slug_valid "$WORK_ID" || die "unsafe work id: $WORK_ID" +fm_pf_slug_valid "$OUTCOME" || die "unsafe outcome type: $OUTCOME" +fm_pf_home_id_valid "$SOURCE_HOME" \ + || die "source home must be 'main' or 'secondmate:<stable-id>', got '$SOURCE_HOME'" +case "$GENERATION" in + ''|*[!0-9]*) die "generation must be a positive integer, got '$GENERATION'" ;; +esac +[ "$GENERATION" -ge 1 ] || die "generation must be >= 1, got '$GENERATION'" + +i=0 +while [ "$i" -lt "${#DELIVERABLE_KEYS[@]}" ]; do + key=${DELIVERABLE_KEYS[$i]} + case "$key" in + ''|*[!a-z0-9_]*) die "deliverable key must be lowercase [a-z0-9_], got '$key'" ;; + esac + [ "${#DELIVERABLE_VALUES[$i]}" -le 512 ] \ + || die "deliverable '$key' exceeds 512 characters" + case "${DELIVERABLE_VALUES[$i]}" in + *[[:cntrl:]]*) die "deliverable '$key' must be single-line text with no control characters" ;; + esac + i=$((i + 1)) +done + +# Resolve the owning home to a real absolute directory before composing any path +# under it, so a relative or symlinked argument cannot make the destination +# ambiguous in a later message or write. +case "$HOME_DIR" in + /*) ;; + *) HOME_DIR=$(CDPATH='' cd -- "$HOME_DIR" 2>/dev/null && pwd -P) \ + || die "--home is not a reachable directory: $1" ;; +esac +[ -d "$HOME_DIR" ] && [ ! -L "$HOME_DIR" ] \ + || die "--home must name an existing directory, got '$HOME_DIR'" + +fm_pf_relay_active "$HOME_DIR" || exit 0 +command -v jq >/dev/null 2>&1 || die "jq is required to build a typed terminal event" 1 + +STATE="$HOME_DIR/state" +REGISTRY="$(fm_pf_registry_dir "$STATE")/$OBLIGATION" +if [ ! -f "$REGISTRY" ] || [ -L "$REGISTRY" ]; then + die "home '$HOME_DIR' has no public-followup registration for '$OBLIGATION'; the owning home registers a commitment before its work can report one" 1 +fi + +# The registration is the owning home's own record of what it bound, so checking +# the identity tuple against it catches a mis-briefed worker at the edge with a +# clear message. tasks-axi still re-validates everything at consume time and +# remains the authority; this is a cheap early refusal, not a second gatekeeper. +reg_mismatch() { + local field=$1 expected=$2 got=$3 + [ -z "$expected" ] || [ "$expected" = "$got" ] \ + || die "event $field '$got' does not match this home's registration ('$expected')" +} +reg_mismatch relation "$(fm_pf_registry_get "$STATE" "$OBLIGATION" relation_id)" "$RELATION" +reg_mismatch source-home "$(fm_pf_registry_get "$STATE" "$OBLIGATION" work_home)" "$SOURCE_HOME" +reg_mismatch work-id "$(fm_pf_registry_get "$STATE" "$OBLIGATION" work_id)" "$WORK_ID" +reg_mismatch generation "$(fm_pf_registry_get "$STATE" "$OBLIGATION" generation)" "$GENERATION" + +case "$TEXT_MODE" in + inline) OUTCOME_TEXT=$(printf '%s' "$TEXT_SOURCE" | fm_pf_clean_outcome_text) ;; + file) + if [ "$TEXT_SOURCE" = '-' ]; then + OUTCOME_TEXT=$(fm_pf_clean_outcome_text) + else + [ -f "$TEXT_SOURCE" ] || die "outcome text file not found: $TEXT_SOURCE" + OUTCOME_TEXT=$(fm_pf_clean_outcome_text < "$TEXT_SOURCE") + fi + ;; +esac +[ -n "$OUTCOME_TEXT" ] || die "outcome text is empty once whitespace and control characters are removed" + +# Canonical deliverables object: sorted keys, compact, so the same deliverables +# always hash to the same identity regardless of flag order. +DELIVERABLES_JSON=$( + { + i=0 + while [ "$i" -lt "${#DELIVERABLE_KEYS[@]}" ]; do + printf '%s\n%s\n' "${DELIVERABLE_KEYS[$i]}" "${DELIVERABLE_VALUES[$i]}" + i=$((i + 1)) + done + } | jq -Rsc 'split("\n") | .[:-1] | [range(0; length; 2) as $i | {key: .[$i], value: .[$i+1]}] | from_entries | to_entries | sort_by(.key) | from_entries' +) || die "could not encode deliverables" 1 + +EVENT_ID=$(fm_pf_event_id \ + "$OBLIGATION" "$RELATION" "$SOURCE_HOME" "$WORK_ID" "$GENERATION" "$OUTCOME" \ + "$DELIVERABLES_JSON") || die "sha256 (shasum or sha256sum) is required" 1 +# The derived id becomes a filename, so require the exact digest shape rather +# than trusting whatever the hashing tool printed. +case "$EVENT_ID" in + *[!0-9a-f]*|'') die "could not derive a usable event id" 1 ;; +esac +[ "${#EVENT_ID}" -eq 64 ] || die "could not derive a usable event id" 1 + +# jq bounds the outcome text by codepoint, so a long or non-ASCII sentence is +# capped without ever splitting a multi-byte character. +EVENT_JSON=$(jq -Sc -n \ + --argjson schema_version "$FM_PF_EVENT_SCHEMA_VERSION" \ + --arg event_id "$EVENT_ID" \ + --arg obligation_id "$OBLIGATION" \ + --arg relation_id "$RELATION" \ + --arg work_id "$WORK_ID" \ + --argjson generation "$GENERATION" \ + --arg source_home_id "$SOURCE_HOME" \ + --arg outcome_type "$OUTCOME" \ + --argjson deliverables "$DELIVERABLES_JSON" \ + --arg public_safe_outcome "$OUTCOME_TEXT" \ + --argjson outcome_max "$FM_PF_OUTCOME_TEXT_MAX" \ + --arg occurred_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + '{schema_version:$schema_version, event_id:$event_id, obligation_id:$obligation_id, + relation_id:$relation_id, work_id:$work_id, generation:$generation, + source_home_id:$source_home_id, outcome_type:$outcome_type, + deliverables:$deliverables, + public_safe_outcome:($public_safe_outcome[0:$outcome_max]), + occurred_at:$occurred_at, successor:null}') \ + || die "could not build the typed terminal event" 1 + +EVENT_BYTES=$(printf '%s\n' "$EVENT_JSON" | LC_ALL=C wc -c | tr -d ' ') \ + || die "could not measure the typed terminal event" 1 +[ "$EVENT_BYTES" -le "$FM_PF_EVENT_BYTES_MAX" ] \ + || die "typed terminal event exceeds $FM_PF_EVENT_BYTES_MAX bytes" 2 + +printf '%s\n' "$EVENT_JSON" \ + | fmx_private_artifact_publish_stdin_once "$(fm_pf_events_dir "$STATE")" "$EVENT_ID.json" 600 +case $? in + 0|1) printf '%s\n' "$EVENT_ID" ;; + *) die "could not publish the terminal event into $HOME_DIR" 1 ;; +esac diff --git a/bin/fm-public-followup-lib.sh b/bin/fm-public-followup-lib.sh new file mode 100644 index 00000000000..dc7153d53cf --- /dev/null +++ b/bin/fm-public-followup-lib.sh @@ -0,0 +1,247 @@ +# shellcheck shell=bash +# fm-public-followup-lib.sh - shared gating and private-transport helpers for the +# deterministic public-followup consumer. +# +# Firstmate promises a public final reply when a myfirstmate relay mention (X or +# Discord) asks for work. `tasks-axi public-followup` is the sole owner of that +# typed obligation and its state machine; state/x-context/ is the sole owner of +# the private full request context. This library owns only the small Firstmate +# side: the activation gate, the private per-home transport directories, and the +# deterministic terminal-event identity. +# +# Sourced, never executed. No side effects on source (it creates nothing), which +# is what keeps a relay-disabled home free of public-followup artifacts. +# set -u / set -e safe. +# +# GATE ORDER - the acceptance criterion for relay-disabled homes: +# 1. fm_pf_relay_active <home> the authoritative myfirstmate activation +# contract, a non-empty FMX_PAIRING_TOKEN in +# <home>/.env. There is no second flag. When +# <home>/.env is absent this is a single +# [ -f ] test and nothing else runs. +# 2. fm_pf_has_registrations O(1) presence check on the registry created +# / fm_pf_has_events only by the relay path (fm-public-followup.sh +# register). Relay-enabled homes with no +# public commitments stop here, so no +# tasks-axi call and no backlog scan happens. +# +# Private transport layout, all under <home>/state/public-followup (mode 0700, +# created only by `fm-public-followup.sh register`): +# registry/<obligation-id> registration record: the bounded public-safe +# binding (obligation, relation, work ref, +# generation, platform, request id). Presence hint +# and reverse work->obligation index only; the +# obligation itself always remains tasks-axi truth. +# events/<event-id>.json inbound typed terminal events awaiting +# reconciliation, one file per event id. +# consumed/<event-id> idempotency ledger: an accepted event id is never +# replayed, so duplicate emits and restart replay +# are no-ops. +# rejected/<event-id>.json events tasks-axi refused, kept with a +# rejected/<event-id>.reason one-line reason so a refusal is inspectable and +# never retried in a loop. +# surfaced last surfaced pending-event signature, so the +# existing relay poll wakes once per new event set +# instead of every cycle. +# +# Event identity is DERIVED, never random: fm_pf_event_id hashes the canonical +# identity tuple, so re-emitting the same terminal result produces the same +# event id and the same destination path. Idempotency therefore holds across +# retries, restarts, and duplicate child reports without any coordination. +# +# Depends on bin/fm-x-lib.sh for .env reading and the private-artifact +# publication primitives (atomic, single-link, mode-validated, non-executable); +# those remain that file's contract and are not restated here. + +_FM_PF_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd 2>/dev/null)" || _FM_PF_LIB_DIR="." +# shellcheck source=bin/fm-x-lib.sh +. "$_FM_PF_LIB_DIR/fm-x-lib.sh" + +FM_PF_DIRNAME='public-followup' +# Consumed by the sourcing scripts, not by this library. +# shellcheck disable=SC2034 +FM_PF_EVENT_SCHEMA_VERSION=1 +# Bounded so a public-safe outcome line can never carry a raw public message, +# and so one event file stays small enough to read and validate cheaply. +FM_PF_OUTCOME_TEXT_MAX=${FM_PF_OUTCOME_TEXT_MAX:-600} +FM_PF_EVENT_BYTES_MAX=${FM_PF_EVENT_BYTES_MAX:-8192} + +# --- gate 1: the authoritative relay activation contract -------------------- + +# fm_pf_relay_active <home>: 0 when this home has opted into the myfirstmate +# relay, 1 otherwise. Identical contract to bootstrap's X-mode activation - a +# non-empty FMX_PAIRING_TOKEN in <home>/.env - so no second activation flag +# exists to drift. FMX_PAIRING_TOKEN in the environment wins, matching +# fmx_load_config, so a direct client call and this gate agree. +fm_pf_relay_active() { + local home=$1 token + if [ -n "${FMX_PAIRING_TOKEN+x}" ]; then + [ -n "${FMX_PAIRING_TOKEN-}" ] + return $? + fi + [ -f "$home/.env" ] || return 1 + token=$(fmx_env_get FMX_PAIRING_TOKEN "$home/.env") + [ -n "$token" ] +} + +# --- gate 2: O(1) presence checks on relay-path-owned registrations --------- + +fm_pf_root() { printf '%s\n' "$1/$FM_PF_DIRNAME"; } +fm_pf_registry_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/registry"; } +fm_pf_events_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/events"; } +fm_pf_consumed_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/consumed"; } +fm_pf_rejected_dir() { printf '%s\n' "$1/$FM_PF_DIRNAME/rejected"; } + +# fm_pf_dir_has_entry <dir>: 0 when <dir> is a real directory holding at least +# one non-dot entry. Stops at the first hit, so cost does not grow with the +# directory's size. +fm_pf_dir_has_entry() { + local dir=$1 entry + [ -d "$dir" ] && [ ! -L "$dir" ] || return 1 + for entry in "$dir"/*; do + [ -e "$entry" ] || continue + return 0 + done + return 1 +} + +fm_pf_has_registrations() { fm_pf_dir_has_entry "$(fm_pf_registry_dir "$1")"; } +fm_pf_has_events() { fm_pf_dir_has_entry "$(fm_pf_events_dir "$1")"; } + +# fm_pf_active <home> <state>: both gates, in order. The single predicate every +# caller outside the relay path should use before doing any public-followup work. +fm_pf_active() { + fm_pf_relay_active "$1" || return 1 + fm_pf_has_registrations "$2" || fm_pf_has_events "$2" +} + +# --- identifiers ------------------------------------------------------------ + +# fm_pf_slug_valid <value>: obligation ids, relation ids, work ids, and request +# ids all compose filenames. They arrive from tasks-axi, the relay, and child +# homes, so every one is checked against a conservative slug before use. +fm_pf_slug_valid() { + local v=$1 + case "$v" in + ''|.*|*[!A-Za-z0-9._-]*) return 1 ;; + esac + [ "${#v}" -le 128 ] +} + +# fm_pf_home_id_valid <home_id>: tasks-axi accepts "main" or +# "secondmate:<stable-id>" as a work_ref home. Validate the same shape here so a +# malformed source home is refused before it reaches a filename or a CLI call. +fm_pf_home_id_valid() { + local v=$1 + case "$v" in + main) return 0 ;; + secondmate:*) fm_pf_slug_valid "${v#secondmate:}" ;; + *) return 1 ;; + esac +} + +fm_pf_sha256() { + if command -v shasum >/dev/null 2>&1; then + shasum -a 256 2>/dev/null | awk '{print $1}' + elif command -v sha256sum >/dev/null 2>&1; then + sha256sum 2>/dev/null | awk '{print $1}' + else + return 1 + fi +} + +# fm_pf_event_id <obligation> <relation> <source_home> <work_id> <generation> +# <outcome_type> <deliverables-canonical> +# The stable idempotency identity. Derived from the identity tuple only, so the +# same terminal result always yields the same id no matter who emits it or how +# often. Public-safe outcome text is deliberately excluded: rewording the same +# landed outcome must not create a second event. +fm_pf_event_id() { + printf '%s\037%s\037%s\037%s\037%s\037%s\037%s' "$1" "$2" "$3" "$4" "$5" "$6" "$7" \ + | fm_pf_sha256 +} + +# --- bounded public-safe text ---------------------------------------------- + +# fm_pf_clean_outcome_text: read stdin, drop control characters, collapse every +# whitespace run to a single space, and trim. An event line therefore stays +# single-line and a raw pasted public message cannot ride along inside it. +# Deliberately does NOT truncate: a byte-wise cut would split a multi-byte +# character, so length bounding happens where it can count codepoints - jq, at +# the point the typed event is built. +fm_pf_clean_outcome_text() { + LC_ALL=C tr -d '\000-\010\013\014\016-\037\177' \ + | LC_ALL=C tr '\011\012\015' ' ' \ + | LC_ALL=C tr -s ' ' \ + | sed 's/^ //; s/ $//' +} + +# fm_pf_bound_bytes <max>: hard byte cap for text that never becomes JSON, such +# as a quarantined event's one-line refusal reason. +fm_pf_bound_bytes() { + LC_ALL=C cut -b "1-$1" +} + +# --- registry records ------------------------------------------------------- + +# fm_pf_registry_get <state> <obligation-id> <key>: read one key=value line from +# a registration record. Prints nothing and succeeds when absent. +fm_pf_registry_get() { + local state=$1 id=$2 key=$3 file line + fm_pf_slug_valid "$id" || return 1 + file="$(fm_pf_registry_dir "$state")/$id" + [ -f "$file" ] && [ ! -L "$file" ] || return 0 + line=$(grep -E "^${key}=" "$file" 2>/dev/null | tail -n1) || return 0 + printf '%s' "${line#*=}" +} + +# fm_pf_registry_ids <state>: every registered obligation id, one per line. +# The registry only ever holds this home's live public commitments, so this stays +# a bounded listing rather than a backlog scan. +fm_pf_registry_ids() { + local dir entry + dir=$(fm_pf_registry_dir "$1") + [ -d "$dir" ] && [ ! -L "$dir" ] || return 0 + for entry in "$dir"/*; do + [ -f "$entry" ] && [ ! -L "$entry" ] || continue + basename "$entry" + done +} + +# fm_pf_registry_ids_for_work <state> <work_home_id> <work_id>: the obligations +# this home registered against one exact work relation. Used by the completion +# guard so cleanup cannot declare bound work finished while its public promise is +# still open. +fm_pf_registry_ids_for_work() { + local state=$1 home_id=$2 work_id=$3 id + while IFS= read -r id; do + [ -n "$id" ] || continue + [ "$(fm_pf_registry_get "$state" "$id" work_home)" = "$home_id" ] || continue + [ "$(fm_pf_registry_get "$state" "$id" work_id)" = "$work_id" ] || continue + printf '%s\n' "$id" + done <<EOF +$(fm_pf_registry_ids "$state") +EOF +} + +# --- pending-event signature ------------------------------------------------ + +# Consumed by the sourcing scripts, not by this library. +# shellcheck disable=SC2034 +FM_PF_SURFACED_BASENAME=surfaced + +# fm_pf_events_signature <state>: a stable digest of the pending event id set. +# The relay poll compares it against the surfaced record so an unconsumed event +# wakes firstmate once per new event, not once per poll cycle. +fm_pf_events_signature() { + local dir entry names= + dir=$(fm_pf_events_dir "$1") + [ -d "$dir" ] && [ ! -L "$dir" ] || return 1 + for entry in "$dir"/*.json; do + [ -f "$entry" ] && [ ! -L "$entry" ] || continue + names="$names$(basename "$entry") +" + done + [ -n "$names" ] || return 1 + printf '%s' "$names" | LC_ALL=C sort | fm_pf_sha256 +} diff --git a/bin/fm-public-followup.sh b/bin/fm-public-followup.sh new file mode 100755 index 00000000000..aa754d9e646 --- /dev/null +++ b/bin/fm-public-followup.sh @@ -0,0 +1,906 @@ +#!/usr/bin/env bash +# fm-public-followup.sh - the deterministic consumer and delivery owner for +# public commitments made through the myfirstmate relay (X and Discord). +# +# THE PROBLEM THIS SOLVES: firstmate promises a public final reply, routes the +# work out, and then the conversation compacts or the session restarts. Nothing +# in memory survives, so the promise is only kept if reconciling it is a disk +# operation. Every command here reads durable state and nothing else. +# +# OWNERSHIP BOUNDARIES (do not re-implement any of these here): +# tasks-axi public-followup the typed obligation and its state machine. +# state/x-context/ the private full request context (fm-x-lib.sh). +# bin/fm-x-reply.sh posting to the relay, thread splitting, dry run. +# bin/fm-public-followup-lib.sh the activation gate and private transport. +# This script composes them; it never restates their contracts or schemas. +# +# ZERO OVERHEAD FOR HOMES THAT DO NOT USE THE RELAY: every subcommand gates +# first on the authoritative activation contract (a non-empty FMX_PAIRING_TOKEN +# in $FM_HOME/.env). Read-side and cleanup paths then use an O(1) presence check +# for registrations this home actually created. A relay-disabled home therefore +# runs one [ -f ] test before any backlog work: no tasks-axi call, no backlog scan, +# and no file created. Silent read-side commands return without output; commands +# that require an active relay report their configuration error after the same +# gate. A relay-enabled home with no live commitments stops at the second gate +# for the same cost. +# +# Usage: +# fm-public-followup.sh active +# Silent gate probe. Exit 0 when this home has live public-followup work +# worth looking at, 1 otherwise. Safe to call unconditionally. +# +# fm-public-followup.sh register <obligation-id> --relation <relation-id> +# --work-home <main|secondmate:<id>> --work-id <task-id> --generation <n> +# [--platform <x|discord>] [--request <request-id>] +# Record the binding the relay path just created with `tasks-axi +# public-followup add` + `bind-work`. This is the event-driven +# registration: it creates this home's private public-followup directories +# (0700) and the bounded public-safe registration record, which is what +# later makes the presence checks O(1) and lets bound work report a typed +# terminal result. Refuses when the relay is not active for this home. +# +# fm-public-followup.sh brief <obligation-id> +# Print the exact fm-public-followup-emit.sh command line the bound worker +# must run when its work reaches the promised terminal outcome, so the +# binding is copied into a brief instead of hand-assembled. +# +# fm-public-followup.sh consume +# Drain every pending typed terminal event: validate its derived identity, +# skip anything already accepted, apply `tasks-axi public-followup +# work-event`, and quarantine what tasks-axi refuses. Prints one +# "ready <obligation-id> <request-id> <platform>" line per obligation that +# became delivery-ready, and one "rejected <event-id>: <reason>" line per +# refusal. Silent when there is nothing to do. Duplicate events and restart +# replay are no-ops. +# +# fm-public-followup.sh pending +# One bounded public-safe line per unresolved commitment, for the session +# start digest. Prunes registrations whose obligation is already closed. +# Silent when nothing is unresolved. +# +# fm-public-followup.sh deliver <obligation-id> [--text-file <path>] +# Post the final public reply into the ORIGINAL thread and close the +# obligation. Uses the stored platform and opaque context binding, so the +# destination is never guessed. Without --text-file the accepted terminal +# event's bounded public-safe outcome is reused exactly, which keeps the +# common path deterministic. The sequence is begin-delivery with the +# payload hash, post, then record the posted receipt or a typed error. +# A validated receipt also clears any bound legacy X link before the +# registration is removed. +# An already-posted obligation is an idempotent success without another +# post; an obligation left in delivery-posting by a crash is REFUSED +# rather than posted again. +# +# fm-public-followup.sh record-posted <obligation-id> --attempt <n> --chunks <n> +# Close an obligation whose post is known to have landed on exactly +# attempt <n> with exactly <n> messages, without posting anything. This is +# the late-receipt path: use it when a post succeeded but its receipt was +# lost, never to paper over an unknown outcome. +# +# fm-public-followup.sh guard-work <work-home-id> <work-id> +# Exit 3 when this home has an unresolved public commitment bound to that +# exact work, printing one line per blocking obligation. Exit 0 otherwise. +# Cleanup paths call this so bound work is never treated as finished while +# its public promise is still open. +# +# fm-public-followup.sh retire <obligation-id> [--force] +# Drop the registration once its obligation is closed. --force is the +# explicit discard-approved escape hatch for an unresolved or missing +# obligation. +# +# Requires jq and a compatible tasks-axi for registration, reconciliation, +# delivery, cleanup guards, and retirement; `active` and `brief` only inspect +# local state. +# FM_PF_RETRY_BACKOFF_SECS (default 900) sets the next-attempt time recorded with +# a retryable delivery error. +set -u + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}" +FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}" +STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}" +DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}" + +# shellcheck source=bin/fm-public-followup-lib.sh +. "$SCRIPT_DIR/fm-public-followup-lib.sh" +# shellcheck source=bin/fm-secondmate-registry-lib.sh +. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh" + +RETRY_BACKOFF=${FM_PF_RETRY_BACKOFF_SECS:-900} +case "$RETRY_BACKOFF" in ''|*[!0-9]*) RETRY_BACKOFF=900 ;; esac + +usage() { + echo "usage: fm-public-followup.sh <active|register|brief|consume|pending|deliver|record-posted|guard-work|retire> [args]" >&2 +} + +# The header comment IS the help text, so the two can never drift apart. +help() { sed -n '2,/^set -u$/p' "$0" | sed '$d; s/^# \{0,1\}//'; } + +die() { printf 'fm-public-followup: %s\n' "$1" >&2; exit "${2:-2}"; } + +PF_TEMP_FILES=() +pf_cleanup_temp_files() { + [ "${#PF_TEMP_FILES[@]}" -eq 0 ] || rm -f -- "${PF_TEMP_FILES[@]}" +} +trap pf_cleanup_temp_files EXIT + +now_rfc3339() { date -u +%Y-%m-%dT%H:%M:%SZ; } + +# next_attempt_rfc3339: the retry time recorded with a retryable delivery error. +# BSD and GNU date disagree on the flag, so try both and print nothing when +# neither works - the error is still recorded, just without a retry time. +next_attempt_rfc3339() { + local at + at=$(( $(date +%s) + RETRY_BACKOFF )) + date -u -r "$at" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \ + || date -u -d "@$at" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \ + || true +} + +require_tools() { + command -v jq >/dev/null 2>&1 || die "jq is required" 1 + command -v tasks-axi >/dev/null 2>&1 || die "tasks-axi is required" 1 +} + +# Every tasks-axi call runs from the home whose backlog owns the obligation, the +# same convention bin/fm-decision-hold.sh uses for typed backlog state. +tx() { (cd "$FM_HOME" && tasks-axi "$@"); } + +# obligation_json <id>: the complete typed obligation payload on stdout, empty +# when the backlog simply has no such public-followup item, and a non-zero exit +# ONLY when the backlog could not be read at all. Callers depend on that +# distinction to report the right thing, so jq runs without -e here. tasks-axi +# stays the single source of truth; the registration record is never consulted +# for state. +obligation_json() { + local id=$1 out + out=$(tx public-followup list --json 2>/dev/null) || return 1 + [ -n "$out" ] || return 1 + printf '%s' "$out" | jq -c --arg id "$id" \ + '(.public_followups // []) | map(select(.id == $id)) | .[0] // empty' 2>/dev/null \ + || return 1 +} + +pf_field() { printf '%s' "$1" | jq -r "$2 // empty" 2>/dev/null; } + +# --- gates ------------------------------------------------------------------ + +# gate_or_exit: the shared silent gate for every read-side subcommand. Exits 0 +# with no output when this home has no public-followup work, so callers can +# invoke unconditionally without a relay-disabled home paying anything. +gate_or_exit() { + fm_pf_relay_active "$FM_HOME" || exit 0 + fm_pf_has_registrations "$STATE" || fm_pf_has_events "$STATE" || exit 0 +} + +# --- subcommand: active ----------------------------------------------------- + +cmd_active() { + fm_pf_relay_active "$FM_HOME" || exit 1 + fm_pf_has_registrations "$STATE" || fm_pf_has_events "$STATE" || exit 1 + exit 0 +} + +# --- subcommand: register --------------------------------------------------- + +cmd_register() { + local id=${1:-} + local relation='' work_home='' work_id='' generation='' platform='' request='' + [ -n "$id" ] || { usage; exit 2; } + shift + while [ "$#" -gt 0 ]; do + case "$1" in + --relation) shift; relation=${1:-} ;; + --work-home) shift; work_home=${1:-} ;; + --work-id) shift; work_id=${1:-} ;; + --generation) shift; generation=${1:-} ;; + --platform) shift; platform=${1:-} ;; + --request) shift; request=${1:-} ;; + *) die "unknown argument '$1'" ;; + esac + shift || true + done + + fm_pf_relay_active "$FM_HOME" \ + || die "this home has not opted into the myfirstmate relay, so it cannot own a public commitment" 1 + require_tools + + fm_pf_slug_valid "$id" || die "unsafe obligation id: $id" + fm_pf_slug_valid "$relation" || die "unsafe relation id: $relation" + fm_pf_slug_valid "$work_id" || die "unsafe work id: $work_id" + fm_pf_home_id_valid "$work_home" \ + || die "work home must be 'main' or 'secondmate:<stable-id>', got '$work_home'" + case "$generation" in + ''|*[!0-9]*) die "generation must be a positive integer, got '$generation'" ;; + esac + [ "$generation" -ge 1 ] || die "generation must be >= 1" + + local payload + payload=$(obligation_json "$id") \ + || die "could not read the backlog through tasks-axi" 1 + [ -n "$payload" ] \ + || die "no public-followup obligation '$id' in this home's backlog; create it with tasks-axi public-followup add before registering" 1 + + # The relation must already be bound, so a registration can never describe a + # binding tasks-axi does not have. + printf '%s' "$payload" | jq -e --arg r "$relation" --arg h "$work_home" --arg w "$work_id" \ + '(.public_followup.work_relations // []) + | map(select(.relation_id == $r and .work_ref.home_id == $h and .work_ref.task_id == $w)) + | length > 0' >/dev/null 2>&1 \ + || die "obligation '$id' has no bound relation '$relation' for $work_home/$work_id; run tasks-axi public-followup bind-work first" 1 + + [ -n "$platform" ] || platform=$(pf_field "$payload" '.public_followup.request.platform') + [ -n "$request" ] || request=$(pf_field "$payload" '.public_followup.request.request_id') + [ -z "$request" ] || fm_pf_slug_valid "$request" || die "unsafe request id: $request" + + local mkdir_target + for mkdir_target in "$(fm_pf_registry_dir "$STATE")" "$(fm_pf_events_dir "$STATE")" \ + "$(fm_pf_consumed_dir "$STATE")" "$(fm_pf_rejected_dir "$STATE")"; do + fmx_private_artifact_dir_prepare "$mkdir_target" >/dev/null \ + || die "could not prepare $mkdir_target" 1 + done + + printf 'obligation_id=%s\nrelation_id=%s\nwork_home=%s\nwork_id=%s\ngeneration=%s\nplatform=%s\nrequest_id=%s\n' \ + "$id" "$relation" "$work_home" "$work_id" "$generation" "$platform" "$request" \ + | fmx_private_artifact_publish_stdin "$(fm_pf_registry_dir "$STATE")" "$id" 600 \ + || die "could not write the registration record" 1 + + printf 'registered %s %s/%s generation=%s platform=%s\n' \ + "$id" "$work_home" "$work_id" "$generation" "${platform:-unknown}" +} + +# --- subcommand: brief ------------------------------------------------------ + +cmd_brief() { + local id=${1:-} relation work_home work_id generation + [ -n "$id" ] || { usage; exit 2; } + fm_pf_slug_valid "$id" || die "unsafe obligation id: $id" + fm_pf_relay_active "$FM_HOME" || die "the relay is not active for this home" 1 + [ -f "$(fm_pf_registry_dir "$STATE")/$id" ] \ + || die "no registration for '$id' in this home" 1 + + relation=$(fm_pf_registry_get "$STATE" "$id" relation_id) + work_home=$(fm_pf_registry_get "$STATE" "$id" work_home) + work_id=$(fm_pf_registry_get "$STATE" "$id" work_id) + generation=$(fm_pf_registry_get "$STATE" "$id" generation) + + cat <<EOF +When this work reaches its promised terminal outcome, report it as typed data +(never as a sentence for someone to parse) by running exactly: + + $FM_ROOT/bin/fm-public-followup-emit.sh \\ + --home $FM_HOME \\ + --obligation $id \\ + --relation $relation \\ + --source-home $work_home \\ + --work-id $work_id \\ + --generation $generation \\ + --outcome <pr-merged|report-ready|local-main|failed> \\ + --deliverable <key>=<value> \\ + --outcome-text '<one bounded public-safe sentence>' + +Do not post anything publicly yourself and do not look for the public thread: +the home above owns the reply. +EOF +} + +# --- subcommand: consume ---------------------------------------------------- + +# reject_event <file> <event-id> <reason>: quarantine one refused event with an +# inspectable reason so it is never retried in a loop. +reject_event() { + local file=$1 event_id=$2 reason=$3 rejected event_payload + rejected=$(fm_pf_rejected_dir "$STATE") + fmx_private_artifact_dir_prepare "$rejected" >/dev/null \ + || { printf 'rejected %s: %s (quarantine failed; event retained)\n' "$event_id" "$reason"; return 1; } + if ! printf '%s\n' "$reason" \ + | fmx_private_artifact_publish_stdin "$rejected" "$event_id.reason" 600 2>/dev/null; then + printf 'rejected %s: %s (quarantine failed; event retained)\n' "$event_id" "$reason" + return 1 + fi + if ! event_payload=$(cat "$file" 2>/dev/null); then + printf 'rejected %s: %s (quarantine failed; event retained)\n' "$event_id" "$reason" + return 1 + fi + if ! printf '%s' "$event_payload" \ + | fmx_private_artifact_publish_stdin "$rejected" "$event_id.json" 600 2>/dev/null; then + printf 'rejected %s: %s (quarantine failed; event retained)\n' "$event_id" "$reason" + return 1 + fi + if ! rm -f -- "$file" 2>/dev/null; then + printf 'rejected %s: %s (quarantine cleanup failed; event retained)\n' "$event_id" "$reason" + return 1 + fi + printf 'rejected %s: %s\n' "$event_id" "$reason" +} + +cmd_consume() { + gate_or_exit + fm_pf_has_events "$STATE" || exit 0 + require_tools + + local events_dir consumed_dir stderr_file file event_id payload derived out rc reason consume_rc=0 + local obligation delivery request platform + events_dir=$(fm_pf_events_dir "$STATE") + consumed_dir=$(fm_pf_consumed_dir "$STATE") + fmx_private_artifact_dir_prepare "$consumed_dir" >/dev/null \ + || die "could not prepare the consumed-event ledger" 1 + stderr_file=$(mktemp "${TMPDIR:-/tmp}/fm-pf-consume.XXXXXX") \ + || die "could not stage the reconciliation log" 1 + PF_TEMP_FILES+=("$stderr_file") + + for file in "$events_dir"/*.json; do + [ -f "$file" ] && [ ! -L "$file" ] || continue + event_id=$(basename "$file" .json) + + if ! fm_pf_slug_valid "$event_id"; then + printf 'rejected %s: unsafe event filename (event retained)\n' "$event_id" + consume_rc=1 + continue + fi + + # Already accepted on an earlier pass (duplicate emit, or a replay after + # restart): drop the copy without touching the state machine. + if [ -f "$consumed_dir/$event_id" ]; then + rm -f -- "$file" 2>/dev/null || true + continue + fi + + if [ "$(wc -c < "$file" 2>/dev/null || echo 0)" -gt "$FM_PF_EVENT_BYTES_MAX" ]; then + reject_event "$file" "$event_id" "event exceeds $FM_PF_EVENT_BYTES_MAX bytes" || consume_rc=1 + continue + fi + + if ! payload=$(jq -ce . "$file" 2>/dev/null) || [ -z "$payload" ]; then + reject_event "$file" "$event_id" "event is not valid JSON" || consume_rc=1 + continue + fi + + # The filename, the declared event_id, and the identity tuple must all agree. + # A mismatch means the file was hand-edited or built by something other than + # fm-public-followup-emit.sh, so it is refused before tasks-axi sees it. + if [ "$(pf_field "$payload" '.event_id')" != "$event_id" ]; then + reject_event "$file" "$event_id" "declared event_id does not match the filename" || consume_rc=1 + continue + fi + derived=$(fm_pf_event_id \ + "$(pf_field "$payload" '.obligation_id')" \ + "$(pf_field "$payload" '.relation_id')" \ + "$(pf_field "$payload" '.source_home_id')" \ + "$(pf_field "$payload" '.work_id')" \ + "$(pf_field "$payload" '.generation')" \ + "$(pf_field "$payload" '.outcome_type')" \ + "$(printf '%s' "$payload" | jq -Sc '.deliverables // {}' 2>/dev/null)") + if [ -z "$derived" ] || [ "$derived" != "$event_id" ]; then + reject_event "$file" "$event_id" "event id does not match its own identity fields" || consume_rc=1 + continue + fi + + obligation=$(pf_field "$payload" '.obligation_id') + if ! fm_pf_slug_valid "$obligation"; then + reject_event "$file" "$event_id" "unsafe obligation id in event" || consume_rc=1 + continue + fi + + # tasks-axi is the authority on source home, work id, generation, schema, + # outcome, and deliverables. Anything it refuses is quarantined verbatim. + # stderr is captured separately so a warning can never corrupt the JSON that + # the accepted path parses. + if out=$(tx public-followup work-event "$obligation" --event-file "$file" --json 2>"$stderr_file"); then + rc=0 + else + rc=$? + fi + if [ "$rc" -ne 0 ]; then + reason=$( { cat "$stderr_file" 2>/dev/null; printf '%s\n' "$out"; } \ + | grep -v '^[[:space:]]*$' | head -1 | fm_pf_clean_outcome_text | fm_pf_bound_bytes 400) + reject_event "$file" "$event_id" "${reason:-tasks-axi refused the event}" || consume_rc=1 + continue + fi + + if ! printf 'accepted %s\n' "$(now_rfc3339)" \ + | fmx_private_artifact_publish_stdin "$consumed_dir" "$event_id" 600 2>/dev/null; then + printf 'accepted %s: consumed ledger could not be recorded; event retained for reconciliation\n' "$event_id" + consume_rc=1 + continue + fi + if ! rm -f -- "$file" 2>/dev/null; then + printf 'accepted %s: consumed ledger recorded but event could not be removed; event retained for reconciliation\n' "$event_id" + consume_rc=1 + continue + fi + + delivery=$(printf '%s' "$out" | jq -r '.task.public_followup.delivery.state // empty' 2>/dev/null) + if [ "$delivery" = ready ]; then + request=$(printf '%s' "$out" | jq -r '.task.public_followup.request.request_id // empty' 2>/dev/null) + platform=$(printf '%s' "$out" | jq -r '.task.public_followup.request.platform // empty' 2>/dev/null) + printf 'ready %s %s %s\n' "$obligation" "${request:-unknown}" "${platform:-unknown}" + fi + done + + # A fresh event must be able to wake firstmate again, so drop the surfaced + # signature once the inbox has been worked. + rm -f -- "$(fm_pf_root "$STATE")/$FM_PF_SURFACED_BASENAME" 2>/dev/null || true + return "$consume_rc" +} + +# --- subcommand: pending ---------------------------------------------------- + +cmd_pending() { + gate_or_exit + + local listing id payload delivery task_state summary platform request printed=0 + # An unreadable backlog with registrations present is exactly the silence this + # whole path exists to prevent, so say so rather than printing nothing. + if ! command -v jq >/dev/null 2>&1 || ! command -v tasks-axi >/dev/null 2>&1 \ + || ! listing=$(tx public-followup list --json 2>/dev/null) || [ -z "$listing" ] \ + || ! printf '%s' "$listing" | jq -e ' + type == "object" + and (.public_followups | type == "array") + and all(.public_followups[]; + type == "object" + and (.id | type == "string") + and (.public_followup | type == "object") + and (.state | type == "string")) + ' >/dev/null 2>&1; then + if fm_pf_has_registrations "$STATE"; then + printf 'cannot read this home'\''s public commitments through tasks-axi; %s registration(s) are still recorded under state/%s/registry\n' \ + "$(fm_pf_registry_ids "$STATE" | grep -c . || true)" "$FM_PF_DIRNAME" + printed=1 + fi + if fm_pf_has_events "$STATE"; then + printf 'unconsumed terminal results are waiting; run %s/bin/fm-public-followup.sh consume\n' "$FM_ROOT" + printed=1 + fi + [ "$printed" -eq 1 ] || exit 0 + return 0 + fi + + while IFS= read -r id; do + [ -n "$id" ] || continue + payload=$(printf '%s' "$listing" | jq -ce --arg id "$id" \ + '(.public_followups // []) | map(select(.id == $id)) | .[0] // empty' 2>/dev/null) + if [ -z "$payload" ]; then + # The obligation is gone from the backlog (pruned after Done): the + # registration is stale bookkeeping, not evidence, so drop it. + if ! clear_public_followup_link "$id"; then + printf 'cannot clear the legacy X link for closed public commitment %s; registration retained for reconciliation\n' "$id" + printed=1 + continue + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + continue + fi + delivery=$(pf_field "$payload" '.public_followup.delivery.state') + task_state=$(pf_field "$payload" '.state') + if [ "$task_state" = 'done' ] || [ "$delivery" = 'posted' ] || [ "$delivery" = 'waived' ]; then + if ! clear_public_followup_link "$id"; then + printf 'cannot clear the legacy X link for closed public commitment %s; registration retained for reconciliation\n' "$id" + printed=1 + continue + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + continue + fi + summary=$(pf_field "$payload" '.public_followup.request.public_safe_summary' | fm_pf_clean_outcome_text) + platform=$(pf_field "$payload" '.public_followup.request.platform') + request=$(pf_field "$payload" '.public_followup.request.request_id') + printf 'unresolved %s state=%s platform=%s request=%s summary=%s\n' \ + "$id" "${delivery:-unknown}" "${platform:-unknown}" "${request:-unknown}" "$summary" + printed=1 + done <<EOF +$(fm_pf_registry_ids "$STATE") +EOF + + # Events that arrived while no agent was present are actionable on their own, + # so surface them even when every registration currently looks settled. + if fm_pf_has_events "$STATE"; then + printf 'unconsumed terminal results are waiting; run %s/bin/fm-public-followup.sh consume\n' "$FM_ROOT" + printed=1 + fi + [ "$printed" -eq 1 ] || exit 0 +} + +# --- subcommand: deliver ---------------------------------------------------- + +public_followup_registration_valid() { + local id=$1 file relation work_home work_id generation + file="$(fm_pf_registry_dir "$STATE")/$id" + [ -f "$file" ] && [ ! -L "$file" ] || return 1 + relation=$(fm_pf_registry_get "$STATE" "$id" relation_id) + work_home=$(fm_pf_registry_get "$STATE" "$id" work_home) + work_id=$(fm_pf_registry_get "$STATE" "$id" work_id) + generation=$(fm_pf_registry_get "$STATE" "$id" generation) + [ -n "$relation" ] && [ -n "$work_id" ] || return 1 + fm_pf_home_id_valid "$work_home" || return 1 + fm_pf_slug_valid "$work_id" || return 1 + case "$generation" in ''|*[!0-9]*) return 1 ;; esac +} + +public_followup_secondmate_home() { + local id=$1 meta home marker + fm_pf_home_id_valid "secondmate:$id" || return 1 + meta="$STATE/$id.meta" + home=$(fmx_meta_get "$meta" home) + if [ -z "$home" ] && [ -f "$DATA/secondmates.md" ] && [ ! -L "$DATA/secondmates.md" ]; then + home=$(secondmate_registry_field "$DATA/secondmates.md" "$id" home || true) + fi + [ -n "$home" ] || return 1 + case "$home" in /*) ;; *) return 1 ;; esac + home=$(CDPATH='' cd -- "$home" 2>/dev/null && pwd -P) || return 1 + [ -f "$home/.fm-secondmate-home" ] && [ ! -L "$home/.fm-secondmate-home" ] || return 1 + marker=$(sed -n '1p' "$home/.fm-secondmate-home" 2>/dev/null) + [ "$marker" = "$id" ] || return 1 + printf '%s\n' "$home" +} + +clear_public_followup_link() { + local id=$1 work_home work_id home state + public_followup_registration_valid "$id" || return 1 + work_home=$(fm_pf_registry_get "$STATE" "$id" work_home) + work_id=$(fm_pf_registry_get "$STATE" "$id" work_id) + [ -n "$work_home" ] && [ -n "$work_id" ] || return 1 + case "$work_home" in + main) + home=$FM_HOME + state=$STATE + ;; + secondmate:*) + home=$(public_followup_secondmate_home "${work_home#secondmate:}") || return 1 + state="$home/state" + ;; + *) return 1 ;; + esac + FM_HOME="$home" FM_STATE_OVERRIDE="$state" FM_ROOT_OVERRIDE="$FM_ROOT" \ + "$FM_ROOT/bin/fm-x-followup.sh" --clear "$work_id" >/dev/null +} + +public_followup_legacy_link_status() { + local payload=$1 relations work_home work_id home meta + if ! printf '%s' "$payload" | jq -e ' + (.public_followup.work_relations | type == "array") + and all(.public_followup.work_relations[]; + (.work_ref.home_id | type == "string") + and (.work_ref.task_id | type == "string") + ) + ' >/dev/null 2>&1; then + return 2 + fi + relations=$(printf '%s' "$payload" | jq -r ' + .public_followup.work_relations[] + | [.work_ref.home_id, .work_ref.task_id] + | @tsv + ' 2>/dev/null) || return 2 + [ -n "$relations" ] || return 2 + while IFS=$'\t' read -r work_home work_id; do + [ -n "$work_home" ] && [ -n "$work_id" ] || return 2 + case "$work_home" in + main) home=$FM_HOME ;; + secondmate:*) home=$(public_followup_secondmate_home "${work_home#secondmate:}") || return 2 ;; + *) return 2 ;; + esac + meta="$home/state/$work_id.meta" + [ -e "$meta" ] || continue + [ -f "$meta" ] && [ ! -L "$meta" ] || return 2 + [ -n "$(fmx_meta_get "$meta" x_request)" ] && return 0 + done <<EOF +$relations +EOF + return 1 +} + +record_error() { + local id=$1 attempt=$2 state=$3 code=$4 next=$5 tmp rc + tmp=$(mktemp "${TMPDIR:-/tmp}/fm-pf-error.XXXXXX") || return 1 + if [ -n "$next" ]; then + jq -n --argjson a "$attempt" --arg s "$state" --arg c "$code" \ + --arg o "$(now_rfc3339)" --arg n "$next" \ + '{state:$s, attempt_count:$a, error_code:$c, occurred_at:$o, next_attempt_at:$n}' > "$tmp" + else + jq -n --argjson a "$attempt" --arg s "$state" --arg c "$code" --arg o "$(now_rfc3339)" \ + '{state:$s, attempt_count:$a, error_code:$c, occurred_at:$o}' > "$tmp" + fi + tx public-followup record-error "$id" --error-file "$tmp" >/dev/null 2>&1 + rc=$? + rm -f -- "$tmp" + return "$rc" +} + +record_posted() { + local id=$1 attempt=$2 request=$3 platform=$4 chunks=$5 tmp rc + tmp=$(mktemp "${TMPDIR:-/tmp}/fm-pf-receipt.XXXXXX") || return 1 + jq -n --argjson a "$attempt" --arg r "$request" --arg p "$platform" \ + --argjson c "$chunks" --arg t "$(now_rfc3339)" \ + '{state:"posted", request_id:$r, platform:$p, attempt_count:$a, + total_chunks:$c, posted_chunks:$c, posted_at:$t}' > "$tmp" + tx public-followup record-delivery "$id" --receipt-file "$tmp" >/dev/null 2>&1 + rc=$? + rm -f -- "$tmp" + return "$rc" +} + +cmd_deliver() { + local id=${1:-} text_file= + [ -n "$id" ] || { usage; exit 2; } + shift + while [ "$#" -gt 0 ]; do + case "$1" in + --text-file) shift; text_file=${1:-} ;; + *) die "unknown argument '$1'" ;; + esac + shift || true + done + + fm_pf_slug_valid "$id" || die "unsafe obligation id: $id" + fm_pf_relay_active "$FM_HOME" \ + || die "this home has not opted into the myfirstmate relay, so it cannot post a public reply" 1 + require_tools + + local payload delivery attempt request platform text tmp_text hash chunks rc receipt receipt_fields receipt_dry_run link_status + payload=$(obligation_json "$id") || die "could not read the backlog through tasks-axi" 1 + [ -n "$payload" ] || die "no public-followup obligation '$id' in this home's backlog" 1 + + delivery=$(pf_field "$payload" '.public_followup.delivery.state') + request=$(pf_field "$payload" '.public_followup.request.request_id') + platform=$(pf_field "$payload" '.public_followup.request.platform') + attempt=$(pf_field "$payload" '.public_followup.delivery.attempt_count') + case "$attempt" in ''|*[!0-9]*) attempt=0 ;; esac + + case "$delivery" in + posted|waived) + if public_followup_registration_valid "$id"; then + if ! clear_public_followup_link "$id"; then + die "obligation '$id' is already $delivery, but its legacy X link could not be cleared; the registration was retained for reconciliation" 1 + fi + else + link_status=1 + public_followup_legacy_link_status "$payload" || link_status=$? + case "$link_status" in + 0) die "obligation '$id' is already $delivery, but its legacy X link cannot be cleared without a valid registration; reconcile it before any later terminal follow-up" 1 ;; + 1) ;; + *) die "obligation '$id' is already $delivery, but its registration is missing or invalid and the legacy X link cannot be verified; reconcile it before any later terminal follow-up" 1 ;; + esac + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + printf 'already delivered %s state=%s\n' "$id" "$delivery" + return 0 + ;; + ready|retry-due|context-blocked|unknown|partial) + public_followup_registration_valid "$id" \ + || die "public-followup registration for '$id' is missing or invalid; reconcile it before delivery so any legacy X link can be cleared" 1 + ;; + delivery-posting) + die "obligation '$id' is mid-delivery on attempt $attempt: a previous post was started and its outcome was never recorded. Confirm whether that post landed, then close it with 'record-posted $id --attempt $attempt --chunks <exact-count>' or reopen it for retry. Posting again here could duplicate the public reply." 1 + ;; + pending-work) + die "obligation '$id' is still waiting on its bound work; nothing to deliver yet" 1 + ;; + *) + die "obligation '$id' is in delivery state '${delivery:-unknown}', which is not deliverable" 1 + ;; + esac + + [ -n "$request" ] || die "obligation '$id' has no relay request id; its thread binding is unusable" 1 + + if [ -n "$text_file" ]; then + [ -f "$text_file" ] || die "reply text file not found: $text_file" + text=$(cat "$text_file") + else + # Deterministic default: reuse the accepted terminal event's bounded + # public-safe outcome exactly rather than paraphrasing a landed result. + text=$(printf '%s' "$payload" | jq -r ' + [(.public_followup.work_relations // [])[] + | (.accepted_events // [])[] + | .public_safe_outcome // empty] | last // empty' 2>/dev/null) + [ -n "$text" ] \ + || die "obligation '$id' carries no accepted public-safe outcome to reuse; pass --text-file with the reply you composed" 1 + fi + [ -n "$text" ] || die "the reply text is empty" 2 + + tmp_text=$(mktemp "${TMPDIR:-/tmp}/fm-pf-text.XXXXXX") || die "could not stage the reply text" 1 + PF_TEMP_FILES+=("$tmp_text") + receipt=$(mktemp "${TMPDIR:-/tmp}/fm-pf-postreceipt.XXXXXX") || die "could not stage the post receipt" 1 + PF_TEMP_FILES+=("$receipt") + printf '%s' "$text" > "$tmp_text" + + hash=$(fm_pf_sha256 < "$tmp_text") || die "sha256 (shasum or sha256sum) is required" 1 + [ -n "$hash" ] || die "could not hash the reply payload" 1 + + # begin-delivery is what makes a retry safe: it pins the attempt and the exact + # payload before anything leaves the machine. The attempt is read back rather + # than assumed, because every later receipt or error must name it exactly. + local begun + begun=$(tx public-followup begin-delivery "$id" --payload-hash "$hash" --json 2>/dev/null) \ + || die "tasks-axi refused to begin delivery for '$id'" 1 + attempt=$(printf '%s' "$begun" | jq -r '.task.public_followup.delivery.attempt_count // empty' 2>/dev/null) + case "$attempt" in + ''|*[!0-9]*) die "could not read the delivery attempt for '$id' after beginning it; nothing was posted" 1 ;; + esac + + rc=0 + FMX_REPLY_PLATFORM="$platform" FM_HOME="$FM_HOME" \ + "$FM_ROOT/bin/fm-x-reply.sh" "$request" --followup --receipt-file "$receipt" \ + --text-file "$tmp_text" >/dev/null || rc=$? + + if [ "$rc" -eq 0 ]; then + receipt_fields=$(jq -er --arg request "$request" ' + if type != "object" or .request_id != $request or .endpoint != "followup" + or (.chunks | type) != "number" or (.chunks < 1) or (.chunks != (.chunks | floor)) + or (.dry_run | type) != "boolean" then error("invalid receipt") + else [(.chunks | tostring), (.dry_run | tostring)] | @tsv end + ' "$receipt" 2>/dev/null) \ + || die "the public reply for '$id' POSTED but its receipt is missing or invalid; inspect the relay and close it with 'record-posted $id --attempt $attempt --chunks <exact-count>' before any retry" 1 + IFS=$'\t' read -r chunks receipt_dry_run <<EOF +$receipt_fields +EOF + if [ "$receipt_dry_run" = true ]; then + if ! record_error "$id" "$attempt" retry-due dry_run_no_post "$(next_attempt_rfc3339)"; then + die "dry-run for '$id' did not post and its retryable state could not be recorded; the obligation remains mid-delivery and needs explicit reconciliation before retry" 1 + fi + die "dry-run for '$id' did not post; recorded as retryable and left the obligation open" 1 + fi + if record_posted "$id" "$attempt" "$request" "$platform" "$chunks"; then + if ! clear_public_followup_link "$id"; then + die "the public reply for '$id' POSTED and its receipt was recorded, but its legacy X link could not be cleared; the registration was retained for reconciliation" 1 + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + printf 'delivered %s request=%s platform=%s chunks=%s\n' "$id" "$request" "$platform" "$chunks" + return 0 + fi + die "the public reply for '$id' POSTED but its receipt could not be recorded; close it with 'record-posted $id --attempt $attempt --chunks <exact-count>' before any retry, or the thread will get a second reply" 1 + fi + + case "$rc" in + 8) if ! record_error "$id" "$attempt" context-blocked reply_context_unresolved ""; then + die "the public reply for '$id' was not posted, and its held state could not be recorded; the obligation remains mid-delivery and needs explicit reconciliation before retry" 1 + fi + die "held '$id': the original thread's platform or size budget could not be resolved, so nothing was posted. Retry once the request context is recoverable." 1 ;; + 9) if ! record_error "$id" "$attempt" expired-action-required followup_binding_exhausted ""; then + die "the relay rejected '$id', and its expired state could not be recorded; the obligation remains mid-delivery and needs explicit reconciliation before retry" 1 + fi + die "the relay no longer accepts a follow-up for '$id' (window or cap exhausted); nothing was posted and this needs a captain decision" 1 ;; + *) if ! record_error "$id" "$attempt" retry-due relay_post_failed "$(next_attempt_rfc3339)"; then + die "posting the public reply for '$id' failed, and its retryable state could not be recorded; the obligation remains mid-delivery and needs explicit reconciliation before retry" 1 + fi + die "posting the public reply for '$id' failed (exit $rc); recorded as retryable, nothing was delivered" 1 ;; + esac +} + +# --- subcommand: record-posted --------------------------------------------- + +cmd_record_posted() { + local id=${1:-} attempt='' chunks='' + [ -n "$id" ] || { usage; exit 2; } + shift + while [ "$#" -gt 0 ]; do + case "$1" in + --attempt) shift; attempt=${1:-} ;; + --chunks) shift; chunks=${1:-} ;; + *) die "unknown argument '$1'" ;; + esac + shift || true + done + fm_pf_slug_valid "$id" || die "unsafe obligation id: $id" + case "$attempt" in ''|*[!0-9]*) die "--attempt <n> is required and must be an integer" ;; esac + case "$chunks" in ''|*[!0-9]*) die "--chunks <n> is required and must be a positive integer" ;; esac + [ "$chunks" -ge 1 ] 2>/dev/null || die "--chunks <n> is required and must be a positive integer" + fm_pf_relay_active "$FM_HOME" || die "the relay is not active for this home" 1 + public_followup_registration_valid "$id" \ + || die "public-followup registration for '$id' is missing or invalid; reconcile it before recording a receipt so any legacy X link can be cleared" 1 + require_tools + + local payload request platform + payload=$(obligation_json "$id") || die "could not read the backlog through tasks-axi" 1 + [ -n "$payload" ] || die "no public-followup obligation '$id' in this home's backlog" 1 + request=$(pf_field "$payload" '.public_followup.request.request_id') + platform=$(pf_field "$payload" '.public_followup.request.platform') + + record_posted "$id" "$attempt" "$request" "$platform" "$chunks" \ + || die "tasks-axi refused the receipt for '$id' attempt $attempt; the recorded attempt must match exactly" 1 + if ! clear_public_followup_link "$id"; then + die "the receipt for '$id' was recorded, but its legacy X link could not be cleared; the registration was retained for reconciliation" 1 + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + printf 'recorded %s attempt=%s request=%s\n' "$id" "$attempt" "$request" +} + +# --- subcommand: guard-work ------------------------------------------------- + +cmd_guard_work() { + local work_home=${1:-} work_id=${2:-} bound id payload delivery task_state blocked=0 + [ -n "$work_home" ] && [ -n "$work_id" ] || { usage; exit 2; } + fm_pf_relay_active "$FM_HOME" || exit 0 + fm_pf_has_registrations "$STATE" || exit 0 + + # Reading the registration records needs no tools, so establish whether this + # work is bound to any commitment before deciding anything else. + bound=$(fm_pf_registry_ids_for_work "$STATE" "$work_home" "$work_id") + [ -n "$bound" ] || exit 0 + + # From here the work IS bound to a public promise, so an unreadable state is a + # blocking answer, not a pass: cleanup must never proceed on a guess. + if ! command -v jq >/dev/null 2>&1 || ! command -v tasks-axi >/dev/null 2>&1; then + printf 'cannot verify the public commitments bound to %s/%s: jq and tasks-axi are required\n' \ + "$work_home" "$work_id" + exit 3 + fi + + while IFS= read -r id; do + [ -n "$id" ] || continue + if ! payload=$(obligation_json "$id"); then + printf 'cannot read the state of public commitment %s for %s/%s\n' "$id" "$work_home" "$work_id" + blocked=1 + continue + fi + # Gone from the backlog entirely (pruned after Done): nothing left to owe. + [ -n "$payload" ] || continue + delivery=$(pf_field "$payload" '.public_followup.delivery.state') + task_state=$(pf_field "$payload" '.state') + case "$task_state:$delivery" in + done:*|*:posted|*:waived) continue ;; + esac + printf 'public commitment %s is still %s for %s/%s\n' "$id" "${delivery:-unknown}" "$work_home" "$work_id" + blocked=1 + done <<EOF +$bound +EOF + [ "$blocked" -eq 0 ] || exit 3 +} + +# --- subcommand: retire ----------------------------------------------------- + +cmd_retire() { + local id=${1:-} force=0 payload delivery task_state + [ -n "$id" ] || { usage; exit 2; } + shift + while [ "$#" -gt 0 ]; do + case "$1" in + --force) force=1 ;; + *) die "unknown argument '$1'" ;; + esac + shift || true + done + fm_pf_slug_valid "$id" || die "unsafe obligation id: $id" + fm_pf_relay_active "$FM_HOME" || exit 0 + require_tools + + payload=$(obligation_json "$id") || die "could not read the backlog through tasks-axi" 1 + if [ -n "$payload" ]; then + delivery=$(pf_field "$payload" '.public_followup.delivery.state') + task_state=$(pf_field "$payload" '.state') + case "$task_state:$delivery" in + done:*|*:posted|*:waived) ;; + *) + [ "$force" -eq 1 ] \ + || die "obligation '$id' is still ${delivery:-unresolved}; retiring its registration now would hide an open public promise. Deliver it, waive it, or pass --force." 1 + ;; + esac + fi + if ! clear_public_followup_link "$id"; then + die "could not clear the legacy X link for '$id'; its registration was retained for reconciliation" 1 + fi + rm -f -- "$(fm_pf_registry_dir "$STATE")/$id" 2>/dev/null || true + printf 'retired %s\n' "$id" +} + +# --- dispatch --------------------------------------------------------------- + +CMD=${1:-} +case "$CMD" in + --help|-h|help) help; exit 0 ;; + '') usage; exit 2 ;; +esac +shift + +case "$CMD" in + active) cmd_active "$@" ;; + register) cmd_register "$@" ;; + brief) cmd_brief "$@" ;; + consume) cmd_consume "$@" ;; + pending) cmd_pending "$@" ;; + deliver) cmd_deliver "$@" ;; + record-posted) cmd_record_posted "$@" ;; + guard-work) cmd_guard_work "$@" ;; + retire) cmd_retire "$@" ;; + *) usage; exit 2 ;; +esac diff --git a/bin/fm-quota-axi-lib.sh b/bin/fm-quota-axi-lib.sh new file mode 100644 index 00000000000..441c9ce2c92 --- /dev/null +++ b/bin/fm-quota-axi-lib.sh @@ -0,0 +1,52 @@ +# shellcheck shell=bash +# Shared quota-axi compatibility floor for the bootstrap diagnostic. +# Usage: . bin/fm-quota-axi-lib.sh +# +# 0.1.16 is the floor because it is the first build that reports each provider's +# credential sources independently and exposes Grok `state.authStatus`. Without +# those fields a dispatch candidate cannot be checked against the authentication +# surface it actually uses, which is how one harness's expired CLI token used to +# produce a captain-facing sign-out claim for a candidate that never read it. +# +# This file is the single owner of that version number. bin/fm-bootstrap.sh +# turns a failing check into the operator-facing MISSING diagnostic, which is +# what keeps an older build from reaching a dispatch intake at all. + +FM_QUOTA_AXI_MIN=0.1.16 + +fm_quota_axi_compatible() { + local timeout=${1:-} output parts major minor patch extra + local min_major min_minor min_patch min_extra + command -v quota-axi >/dev/null 2>&1 || return 1 + if [ -n "$timeout" ]; then + case "$timeout" in + ''|*[!0-9]*|0) return 1 ;; + esac + if command -v timeout >/dev/null 2>&1; then + output=$(timeout "$timeout" quota-axi --version 2>/dev/null </dev/null) || return 1 + elif command -v gtimeout >/dev/null 2>&1; then + output=$(gtimeout "$timeout" quota-axi --version 2>/dev/null </dev/null) || return 1 + elif command -v perl >/dev/null 2>&1; then + output=$(perl -e 'my $t = shift; my $pid = fork; die "fork failed" unless defined $pid; if (!$pid) { setpgrp(0, 0); exec @ARGV } local $SIG{ALRM} = sub { kill "TERM", -$pid; select undef, undef, undef, 0.2; kill "KILL", -$pid; exit 124 }; alarm $t; waitpid $pid, 0; exit($? >> 8)' "$timeout" quota-axi --version 2>/dev/null </dev/null) || return 1 + else + return 1 + fi + else + output=$(quota-axi --version 2>/dev/null </dev/null) || return 1 + fi + parts=$(printf '%s\n' "$output" | + sed -n 's/.*\([0-9][0-9]*\)\.\([0-9][0-9]*\)\.\([0-9][0-9]*\).*/\1 \2 \3/p' | + head -1) + IFS=' ' read -r major minor patch extra <<< "$parts" + # An unparseable version is incompatible, never assumed current, so a + # development or vendored build cannot pass a floor it was never checked against. + [ -n "$major" ] && [ -n "$minor" ] && [ -n "$patch" ] && [ -z "$extra" ] || return 1 + # The floor is compared from FM_QUOTA_AXI_MIN so bumping it needs one edit. + IFS='.' read -r min_major min_minor min_patch min_extra <<< "$FM_QUOTA_AXI_MIN" + [ -n "$min_major" ] && [ -n "$min_minor" ] && [ -n "$min_patch" ] && [ -z "$min_extra" ] || return 1 + [ "$major" -gt "$min_major" ] && return 0 + [ "$major" -eq "$min_major" ] || return 1 + [ "$minor" -gt "$min_minor" ] && return 0 + [ "$minor" -eq "$min_minor" ] || return 1 + [ "$patch" -ge "$min_patch" ] +} diff --git a/bin/fm-secondmate-registry-lib.sh b/bin/fm-secondmate-registry-lib.sh new file mode 100644 index 00000000000..674df77a6ab --- /dev/null +++ b/bin/fm-secondmate-registry-lib.sh @@ -0,0 +1,211 @@ +#!/usr/bin/env bash +# shellcheck disable=SC2034 # parsed fields are output globals for sourcing callers. +# Shared parser for data/secondmates.md records. +# +# A generated record ends with an explicit structured suffix: +# (home: ...; scope: ...; projects: ...; added YYYY-MM-DD) +# Summary text and scope text are natural language and may contain parentheses +# and semicolons, so field boundaries are anchored to the suffix markers rather +# than to the first incidental punctuation. + +SECONDMATE_REGISTRY_ID= +SECONDMATE_REGISTRY_SUMMARY= +SECONDMATE_REGISTRY_HOME= +SECONDMATE_REGISTRY_SCOPE= +SECONDMATE_REGISTRY_PROJECTS= +SECONDMATE_REGISTRY_ADDED= +SECONDMATE_REGISTRY_LINE= +SECONDMATE_REGISTRY_MATCH_HOME= +SECONDMATE_REGISTRY_MATCH_HOME_KEY= +SECONDMATE_REGISTRY_MATCH_PROJECTS= +SECONDMATE_REGISTRY_ERROR= + +secondmate_registry_parse_line() { + local line=$1 + local record_re='^- ([A-Za-z0-9._-]+) - (.+) \(home:[[:space:]]*([^;)]*);[[:space:]]*scope:[[:space:]]*(.*);[[:space:]]*projects:[[:space:]]*([^;)]*);[[:space:]]*added[[:space:]]+([0-9]{4}-[0-9]{2}-[0-9]{2})\)[[:space:]]*$' + SECONDMATE_REGISTRY_ID= + SECONDMATE_REGISTRY_SUMMARY= + SECONDMATE_REGISTRY_HOME= + SECONDMATE_REGISTRY_SCOPE= + SECONDMATE_REGISTRY_PROJECTS= + SECONDMATE_REGISTRY_ADDED= + if [[ "$line" =~ $record_re ]]; then + SECONDMATE_REGISTRY_ID=${BASH_REMATCH[1]} + SECONDMATE_REGISTRY_SUMMARY=${BASH_REMATCH[2]} + SECONDMATE_REGISTRY_HOME=${BASH_REMATCH[3]} + SECONDMATE_REGISTRY_SCOPE=${BASH_REMATCH[4]} + SECONDMATE_REGISTRY_PROJECTS=${BASH_REMATCH[5]} + SECONDMATE_REGISTRY_ADDED=${BASH_REMATCH[6]} + else + return 1 + fi + [ -n "$SECONDMATE_REGISTRY_HOME" ] || return 1 + [ -n "$SECONDMATE_REGISTRY_SCOPE" ] || return 1 + return 0 +} + +secondmate_registry_line_for_id() { + local reg=$1 id=$2 line count=0 + case "$id" in ''|*[!A-Za-z0-9._-]*) return 1 ;; esac + [ -f "$reg" ] && [ ! -L "$reg" ] || return 1 + while IFS= read -r line || [ -n "$line" ]; do + [ "$line" = "- $id" ] || case "$line" in "- $id "*) ;; *) continue ;; esac + count=$((count + 1)) + [ "$count" -eq 1 ] || return 1 + SECONDMATE_REGISTRY_LINE=$line + done < "$reg" + [ "$count" -eq 1 ] || return 1 + secondmate_registry_parse_line "$SECONDMATE_REGISTRY_LINE" +} + +secondmate_registry_field() { + local reg=$1 id=$2 key=$3 + secondmate_registry_line_for_id "$reg" "$id" || return 1 + case "$key" in + home) printf '%s\n' "$SECONDMATE_REGISTRY_HOME" ;; + projects) printf '%s\n' "$SECONDMATE_REGISTRY_PROJECTS" ;; + *) return 1 ;; + esac +} + +secondmate_registry_path_key() { + local path=$1 parent base + case "$path" in /*) ;; *) return 1 ;; esac + if [ -d "$path" ]; then + cd "$path" && pwd -P + else + parent=$(dirname "$path") + base=$(basename "$path") + cd "$parent" && printf '%s/%s\n' "$(pwd -P)" "$base" + fi +} + +secondmate_registry_validate_bindings() { + local reg=$1 resolver=$2 expected_id=${3:-} expected_home=${4:-} + local tmp snapshot bindings line id home home_key duplicate_homes duplicate_ids overlaps expected_home_key + SECONDMATE_REGISTRY_MATCH_HOME= + SECONDMATE_REGISTRY_MATCH_HOME_KEY= + SECONDMATE_REGISTRY_MATCH_PROJECTS= + SECONDMATE_REGISTRY_ERROR= + case "$expected_id" in *[!A-Za-z0-9._-]*) SECONDMATE_REGISTRY_ERROR="invalid secondmate id: $expected_id"; return 1 ;; esac + if [ ! -f "$reg" ] || [ -L "$reg" ]; then + SECONDMATE_REGISTRY_ERROR="secondmate registry is unavailable or unsafe: $reg" + return 1 + fi + tmp=$(mktemp -d "${TMPDIR:-/tmp}/fm-secondmate-registry.XXXXXX") || { + SECONDMATE_REGISTRY_ERROR="could not create secondmate registry validation state" + return 1 + } + snapshot="$tmp/registry" + bindings="$tmp/bindings" + if ! cat "$reg" > "$snapshot" 2>/dev/null || ! : > "$bindings"; then + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="secondmate registry is unavailable or unsafe: $reg" + return 1 + fi + while IFS= read -r line || [ -n "$line" ]; do + case "$line" in + "- "*) + if ! secondmate_registry_parse_line "$line"; then + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="malformed secondmate registry entry: $line" + return 1 + fi + id=$SECONDMATE_REGISTRY_ID + home=$SECONDMATE_REGISTRY_HOME + case "$home" in + /*) ;; + *) + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="unsafe non-absolute secondmate home for $id: $home" + return 1 + ;; + esac + case "$home" in + *$'\t'*) + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="unsafe secondmate home for $id" + return 1 + ;; + esac + home_key=$("$resolver" "$home" 2>/dev/null || true) + if [ -z "$home_key" ]; then + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="unresolvable secondmate home for $id: $home" + return 1 + fi + printf '%s\t%s\n' "$home_key" "$id" >> "$bindings" + if [ -n "$expected_id" ] && [ "$id" = "$expected_id" ]; then + SECONDMATE_REGISTRY_MATCH_HOME=$home + SECONDMATE_REGISTRY_MATCH_HOME_KEY=$home_key + SECONDMATE_REGISTRY_MATCH_PROJECTS=$SECONDMATE_REGISTRY_PROJECTS + fi + ;; + esac + done < "$snapshot" + duplicate_homes=$(awk -F '\t' ' + { + if ($1 in owner) { + print $1 ": " owner[$1] ", " $2 + bad=1 + } else { + owner[$1]=$2 + } + } + END { exit bad ? 1 : 0 } + ' "$bindings" 2>/dev/null) || { + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="duplicate secondmate home assignment: $duplicate_homes" + return 1 + } + duplicate_ids=$(awk -F '\t' ' + { + if ($2 in home) { + print $2 ": " home[$2] ", " $1 + bad=1 + } else { + home[$2]=$1 + } + } + END { exit bad ? 1 : 0 } + ' "$bindings" 2>/dev/null) || { + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="duplicate secondmate id assignment: $duplicate_ids" + return 1 + } + overlaps=$(awk -F '\t' ' + function ancestor(a, b) { return a != b && index(b, a "/") == 1 } + { + for (i = 1; i <= count; i++) { + if (ancestor($1, path[i])) { + print $1 " (" $2 ") contains " path[i] " (" id[i] ")" + bad=1 + } else if (ancestor(path[i], $1)) { + print path[i] " (" id[i] ") contains " $1 " (" $2 ")" + bad=1 + } + } + count++ + path[count]=$1 + id[count]=$2 + } + END { exit bad ? 1 : 0 } + ' "$bindings" 2>/dev/null) || { + rm -rf -- "$tmp" + SECONDMATE_REGISTRY_ERROR="overlapping secondmate home assignment: $overlaps" + return 1 + } + rm -rf -- "$tmp" + if [ -n "$expected_id" ] && [ -z "$SECONDMATE_REGISTRY_MATCH_HOME" ]; then + SECONDMATE_REGISTRY_ERROR="no registry binding for secondmate $expected_id" + return 1 + fi + if [ -n "$expected_home" ]; then + expected_home_key=$("$resolver" "$expected_home" 2>/dev/null || true) + if [ -z "$expected_home_key" ] || [ "$expected_home_key" != "$SECONDMATE_REGISTRY_MATCH_HOME_KEY" ]; then + SECONDMATE_REGISTRY_ERROR="secondmate $expected_id is registered at $SECONDMATE_REGISTRY_MATCH_HOME, not $expected_home" + return 1 + fi + fi + return 0 +} diff --git a/bin/fm-send.sh b/bin/fm-send.sh index dfae6f49e64..6755e56c7f3 100755 --- a/bin/fm-send.sh +++ b/bin/fm-send.sh @@ -84,6 +84,26 @@ fm_send_id_from_meta() { # <meta-file> printf '%s' "${base%.meta}" } +fm_send_record_interrupt() { # <key> + local key=$1 id gen + [ "$key" = Escape ] || return 0 + case "$TARGET_HARNESS" in claude*) : ;; *) return 0 ;; esac + [ -n "$TARGET_META" ] || return 0 + id=$(fm_send_id_from_meta "$TARGET_META") + [ -f "$STATE/$id.busy-gen" ] || return 0 + gen=$(fm_meta_get "$TARGET_META" busy_gen) + if [ -n "$gen" ]; then + "$FM_ROOT/bin/fm-busy-event.sh" apply "$STATE" "$id" idle \ + --gen "$gen" --source fm-interrupt --event interrupt + else + "$FM_ROOT/bin/fm-busy-event.sh" apply "$STATE" "$id" idle \ + --current-gen --source fm-interrupt --event interrupt + fi || { + echo "error: key '$key' reached $T, but the Claude interrupt state could not be recorded for $id" >&2 + return 1 + } +} + fm_send_meta_for_key_value() { # <state-dir> <key> <value> local state=$1 key=$2 value=$3 meta got for meta in "$state"/*.meta; do @@ -224,6 +244,7 @@ if [ "${1:-}" = "--key" ]; then echo "error: key '$2' not sent to $T ($TARGET_BACKEND send failed; tried $RESOLUTION_TRIED)" >&2 exit 1 fi + fm_send_record_interrupt "$2" || exit 1 else MESSAGE=$* if [ "$MARK_FROM_FIRSTMATE" = 1 ]; then diff --git a/bin/fm-session-start.sh b/bin/fm-session-start.sh index 6095f706992..848c62379f2 100755 --- a/bin/fm-session-start.sh +++ b/bin/fm-session-start.sh @@ -105,6 +105,8 @@ PRIMARY_HARNESS=$("$SCRIPT_DIR/fm-harness.sh" 2>/dev/null || printf unknown) . "$SCRIPT_DIR/fm-backend.sh" # shellcheck source=bin/fm-tasks-axi-lib.sh . "$SCRIPT_DIR/fm-tasks-axi-lib.sh" +# shellcheck source=bin/fm-public-followup-lib.sh +. "$SCRIPT_DIR/fm-public-followup-lib.sh" STATUS_TAIL=${FM_SESSION_START_STATUS_TAIL:-5} case "$STATUS_TAIL" in ''|*[!0-9]*) STATUS_TAIL=5 ;; esac @@ -396,6 +398,23 @@ else printf 'absent\n' fi +# Public commitments made through the myfirstmate relay. A promise to reply in a +# public thread must survive compaction and restart, so it is surfaced from disk +# here rather than from conversation memory. fm-public-followup-lib.sh owns both +# gates: a home that never opted into the relay runs one [ -f ] test, prints no +# subsection, and never reaches fm-public-followup.sh. +if fm_pf_relay_active "$FM_HOME" \ + && { fm_pf_has_registrations "$STATE" || fm_pf_has_events "$STATE"; }; then + PUBLIC_FOLLOWUP=$("$SCRIPT_DIR/fm-public-followup.sh" pending 2>/dev/null) || PUBLIC_FOLLOWUP= + if [ -n "$PUBLIC_FOLLOWUP" ]; then + subsection "Public commitments awaiting delivery" + printf '%s\n' "$PUBLIC_FOLLOWUP" + printf '\nEach line is a public reply this home still owes. Reconcile terminal results with\n' + printf '%s/bin/fm-public-followup.sh consume, then deliver a ready one with\n' "$FM_ROOT" + printf '%s/bin/fm-public-followup.sh deliver <id>. Load fmx-respond for the procedure.\n' "$FM_ROOT" + fi +fi + # --- 6. closing reminder ----------------------------------------------- section "NEXT STEP" if [ "$READ_ONLY" -eq 1 ]; then diff --git a/bin/fm-spawn.sh b/bin/fm-spawn.sh index 43b3cb49aac..8c703713cd7 100755 --- a/bin/fm-spawn.sh +++ b/bin/fm-spawn.sh @@ -22,10 +22,12 @@ # installed CLIs were verified to support that axis; unsupported axes are omitted # from that harness's launch rather than guessed. # --backend <name> is the explicit runtime session-provider backend for this -# spawn. Without it, the script resolves FM_BACKEND, then config/backend, then -# runtime auto-detection (the runtime firstmate itself is executing inside - -# $TMUX, HERDR_ENV=1, or cmux runtime signals; bin/fm-backend.sh's -# fm_backend_detect, with cmux fallback details in docs/cmux-backend.md), +# exact task only (docs/configuration.md "Runtime backend" owns when that flag +# is authorized). Without it, the script resolves FM_BACKEND, then +# config/backend, then runtime auto-detection from the runtime firstmate's +# environment: $TMUX, HERDR_ENV=1, or cmux runtime signals (via +# bin/fm-backend.sh's fm_backend_detect, with cmux fallback details in +# docs/cmux-backend.md), # then tmux. # Spawn-capable backends are the reference tmux adapter and experimental # herdr, zellij, orca, and cmux. Orca owns both the task worktree and @@ -39,6 +41,15 @@ # A backend spawn refusal (missing dependency, version gate, unauthenticated # socket, or unsupported secondmate mode) is terminal for that selected backend; # callers must surface it instead of silently retrying another backend. +# A herdr crewmate or scout is placed in the exact workspace of the firstmate +# or secondmate process launching it, resolved from that process's own herdr +# pane rather than from a workspace label (herdr enforces no label uniqueness, +# so a label cannot tell two "firstmate" workspaces apart). A claimed parent +# identity that is unreadable, contradictory, stale, or from another herdr +# session stops the spawn before any worker endpoint exists. A launcher +# outside herdr has no workspace to inherit and uses this home's own labeled +# workspace, which must then match exactly one. --secondmate is the deliberate +# exception: it stands up that secondmate home's own workspace. # Herdr additionally supports a default-off presentation-only layout when the # local config/herdr-presentation-spaces flag exists. A clean fresh task first # writes state/<id>.herdr-presentation atomically, then creates a disposable @@ -185,6 +196,8 @@ SUB_HOME_MARKER=".fm-secondmate-home" . "$SCRIPT_DIR/fm-backend-hometag-lib.sh" # shellcheck source=bin/fm-gate-refuse-lib.sh . "$SCRIPT_DIR/fm-gate-refuse-lib.sh" +# shellcheck source=bin/fm-busy-lib.sh +. "$SCRIPT_DIR/fm-busy-lib.sh" # shellcheck source=bin/fm-pr-lib.sh . "$SCRIPT_DIR/fm-pr-lib.sh" # shellcheck source=bin/fm-delivery-lib.sh @@ -487,7 +500,7 @@ fi [ -z "$HARNESS_ARG" ] || ARG3=$HARNESS_ARG # The verified launch command per adapter. The knowledge half of each adapter -# (busy signature, exit command, dialogs, quirks) lives in the harness-adapters skill. +# (busy-state source, exit command, dialogs, quirks) lives in the harness-adapters skill. launch_template() { local harness=$1 kind=${2:-ship} # shellcheck disable=SC2016 # single quotes are deliberate: $(cat ...) expands in the crewmate pane, not here @@ -610,18 +623,7 @@ if [ "$KIND" = secondmate ] && [ -z "$ARG3" ]; then fi secondmate_registry_value() { - local id=$1 key=$2 reg line value - reg="$DATA/secondmates.md" - [ -f "$reg" ] || return 1 - line=$(grep -E "^- $id( |$)" "$reg" | tail -1 || true) - [ -n "$line" ] || return 1 - case "$key" in - home) value=$(printf '%s\n' "$line" | sed -n 's/^[^(]*(home: \([^;)]*\);.*/\1/p') ;; - projects) value=$(printf '%s\n' "$line" | sed -n 's/^[^(]*(home: [^;)]*; scope: [^;)]*; projects: \([^;)]*\); added .*/\1/p') ;; - *) return 1 ;; - esac - [ -n "$value" ] || return 1 - printf '%s\n' "$value" + secondmate_registry_field "$DATA/secondmates.md" "$1" "$2" } shell_quote() { @@ -844,6 +846,13 @@ fi if [ "$KIND" = secondmate ]; then [ -n "$FIRSTMATE_HOME" ] || { echo "error: no firstmate home supplied or registered for $ID" >&2; exit 1; } PROJ_ABS=$(validate_firstmate_home_for_spawn "$ID" "$FIRSTMATE_HOME") + if [ -e "$DATA/secondmates.md" ] || [ -L "$DATA/secondmates.md" ]; then + if ! secondmate_registry_validate_bindings "$DATA/secondmates.md" resolve_path "$ID" "$FIRSTMATE_HOME"; then + echo "error: $SECONDMATE_REGISTRY_ERROR" >&2 + exit 1 + fi + SECONDMATE_PROJECTS=$SECONDMATE_REGISTRY_MATCH_PROJECTS + fi WT="$PROJ_ABS" # Local-HEAD sync: before launch, fast-forward this secondmate's worktree to the # PRIMARY checkout's current default-branch commit, so a freshly spawned or @@ -1045,9 +1054,18 @@ case "$BACKEND" in # to PROJ_ABS for just these two calls (bash restores it automatically # after each prefixed simple-command call) so the secondmate's tab lands # in the secondmate's own workspace, not the primary's "firstmate" one. + # + # Placement, separately from labeling: a crewmate/scout belongs in the + # EXACT herdr workspace this launching process is itself running in, which + # only its own herdr pane identity can name (a same-labeled sibling + # workspace must never be adopted). A --secondmate launch is the exception - + # it stands up a DIFFERENT home's own workspace by design - so it asks for + # the per-home container instead of inheriting this launcher's. HERDR_LABEL_HOME=$FM_HOME + HERDR_LAUNCHER_RELATIONSHIP=launcher-home if [ "$KIND" = secondmate ]; then HERDR_LABEL_HOME=$PROJ_ABS + HERDR_LAUNCHER_RELATIONSHIP=other-home fi HERDR_PRESENTATION_JOURNAL=$(fm_backend_herdr_projection_journal_path "$STATE" "$ID") HERDR_PROJECTED=0 @@ -1102,8 +1120,21 @@ case "$BACKEND" in if ! fm_backend_herdr_server_ensure "$HERDR_SES"; then echo "warning: herdr presentation could not ensure its session server; using the ordinary flat layout without projection" >&2 elif spawn_herdr_presentation_order_lock_acquire "$HERDR_SES"; then - HERDR_PARENT_WORKSPACE_ID=$(fm_backend_herdr_projection_parent_workspace_exact \ - "$HERDR_SES" "$HERDR_PARENT_LABEL" 2>/dev/null || true) + # The projected child is placed and bound UNDER this launcher's exact + # parent workspace. Its own herdr pane identity names that workspace + # directly; the label lookup is only the fallback for a launcher with + # no herdr ancestry at all. A claimed-but-broken identity refuses here + # rather than projecting under a guessed parent. + set +e + fm_backend_herdr_launcher_identity "$HERDR_SES" + HERDR_LAUNCHER_STATUS=$? + set -e + case "$HERDR_LAUNCHER_STATUS" in + 0) HERDR_PARENT_WORKSPACE_ID=$FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID ;; + 2) HERDR_PARENT_WORKSPACE_ID=$(fm_backend_herdr_projection_parent_workspace_exact \ + "$HERDR_SES" "$HERDR_PARENT_LABEL" 2>/dev/null || true) ;; + *) spawn_herdr_presentation_order_lock_release; exit 1 ;; + esac if [ -z "$HERDR_PARENT_WORKSPACE_ID" ]; then echo "warning: herdr presentation parent is absent or ambiguous; using the ordinary flat layout without projection" >&2 spawn_herdr_presentation_order_lock_release @@ -1131,7 +1162,7 @@ case "$BACKEND" in HERDR_PROJECTION_ABORT_TASK_PANE=$HERDR_PANE_ID HERDR_PROJECTION_ABORT_SEEDED_PANE=$FM_BACKEND_HERDR_PROJECTION_SEEDED_PANE_ID fm_backend_herdr_projection_order_best_effort \ - "$HERDR_SES" "$HERDR_WORKSPACE_ID" "$HERDR_PARENT_LABEL" + "$HERDR_SES" "$HERDR_WORKSPACE_ID" "$HERDR_PARENT_LABEL" "$HERDR_PARENT_WORKSPACE_ID" HERDR_HOME_ID=$(fm_backend_herdr_projection_home_identity "$HERDR_LABEL_HOME" 2>/dev/null || true) if [ -n "$HERDR_HOME_ID" ] \ && fm_backend_herdr_projection_live_binding_matches \ @@ -1153,7 +1184,7 @@ case "$BACKEND" in fi fi if [ "$HERDR_PROJECTED" -ne 1 ]; then - HERDR_CONTAINER_RAW=$(FM_HOME="$HERDR_LABEL_HOME" fm_backend_herdr_container_ensure "$PROJ_ABS") || exit 1 + HERDR_CONTAINER_RAW=$(FM_HOME="$HERDR_LABEL_HOME" fm_backend_herdr_container_ensure "$PROJ_ABS" "$HERDR_LAUNCHER_RELATIONSHIP") || exit 1 # fm_backend_herdr_container_ensure echoes "<session>:<workspace_id>\t<seeded_default_tab_id>" # (the second field empty when this call ADOPTED a pre-existing workspace # rather than creating a fresh one). Split on the guaranteed single tab @@ -1393,42 +1424,158 @@ exclude_path() { grep -qxF "$rel" "$EXCL" 2>/dev/null || echo "$rel" >> "$EXCL" } if [ "$KIND" != secondmate ]; then + # Arm the semantic busy-state contract (bin/fm-busy-lib.sh) for every + # adapter with a verified semantic source. The launch brief sent below IS a + # submitted turn, so the seed record is busy/fm-spawn. The minted gen is + # embedded into each adapter's wiring so an event from a superseded + # incarnation is rejected as stale. Grok stays on its isolated rendered-tail + # fallback and standalone Kimi stays unknown until fm_busy_kimi_verified + # opens, so neither is armed here. + BUSY_GEN= + case "$HARNESS" in + codex*) + if fm_busy_codex_semantic_source; then + echo "error: codex semantic busy-state wiring is not implemented; extend the probe only together with verified wiring" >&2 + exit 1 + fi + ;; + esac + case "$HARNESS" in + claude*|opencode*|pi|pi-signed) + BUSY_GEN=$("$FM_ROOT/bin/fm-busy-event.sh" arm "$STATE_REAL" "$ID") || { + echo "error: failed to arm the busy-state contract for $ID" >&2 + exit 1 + } + ;; + kimi*) + # Standalone Kimi stays unknown until fm_busy_kimi_verified opens on a + # live-verified installed version (bin/fm-busy-lib.sh owns the gate and + # the required evidence). Arming without wiring would seed a busy record + # nothing can ever clear, so the arm waits for the wiring. + if fm_busy_kimi_verified; then + echo "error: kimi semantic busy-state wiring is not implemented; open the gate only together with verified wiring" >&2 + exit 1 + fi + ;; + esac case "$HARNESS" in claude*) + # Semantic busy-state hooks (bin/fm-busy-lib.sh): UserPromptSubmit opens + # a turn; Stop (normal completion), StopFailure (API-error turn end), + # and SessionEnd (process shutdown) all close it, so an abnormal end can + # never leave a stale busy record. Claude fires no hook for a manual + # interrupt, so the firstmate-controlled interruption procedure + # (harness-adapters) records idle/fm-interrupt itself. Stop keeps the + # turn-ended NOTIFICATION touch for the watcher. Every hook command + # tolerates a refused event (|| true) so a stale-gen writer can never + # break Claude's own lifecycle. mkdir -p "$WT/.claude" + busy_cmd_prefix="$(shell_quote "$FM_ROOT/bin/fm-busy-event.sh") apply $(shell_quote "$STATE_REAL") $(shell_quote "$ID")" + busy_suffix="--gen $(shell_quote "$BUSY_GEN") --source claude-hook" + j_submit=$(json_escape "$busy_cmd_prefix busy $busy_suffix --event user-prompt-submit 2>/dev/null || true") + j_stop=$(json_escape "touch $(shell_quote "$TURNEND"); $busy_cmd_prefix idle $busy_suffix --event stop 2>/dev/null || true") + j_stopfail=$(json_escape "$busy_cmd_prefix idle $busy_suffix --event stop-failure 2>/dev/null || true") + j_sessionend=$(json_escape "$busy_cmd_prefix idle $busy_suffix --event session-end 2>/dev/null || true") cat > "$WT/.claude/settings.local.json" <<EOF -{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"touch '$TURNEND'"}]}]}} +{"hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"$j_submit"}]}],"Stop":[{"hooks":[{"type":"command","command":"$j_stop"}]}],"StopFailure":[{"hooks":[{"type":"command","command":"$j_stopfail"}]}],"SessionEnd":[{"hooks":[{"type":"command","command":"$j_sessionend"}]}]}} EOF exclude_path '.claude/settings.local.json' ;; opencode*) mkdir -p "$WT/.opencode/plugins" - cat > "$WT/.opencode/plugins/fm-turn-end.js" <<EOF -export const FmTurnEnd = async ({ \$ }) => ({ - event: async ({ event }) => { - if (event.type === "session.idle") await \$\`touch $TURNEND\` - }, -}) + cat > "$WT/.opencode/plugins/fm-busy-state.js" <<EOF +// Firstmate semantic busy-state events + turn-end notification; written by +// fm-spawn under the contract owned by bin/fm-busy-lib.sh. +// Semantic state comes from OpenCode's session.status events: busy and retry +// are active, idle is inactive. Scoping latches the first session that +// reports activity (the worker's main session - a subagent child session can +// only start while the main session is already busy) and ignores other +// sessions' status until the latched session settles, so a child's idle can +// never clear the worker's busy state. The session.idle touch stays the +// watcher's wake NOTIFICATION, never current-state truth. +import { execFile } from "node:child_process"; +const busyEvent = (state, event) => + new Promise((resolve) => { + execFile("$FM_ROOT/bin/fm-busy-event.sh", [ + "apply", "$STATE_REAL", "$ID", state, + "--gen", "$BUSY_GEN", "--source", "opencode-plugin", "--event", event, + ], () => resolve()); + }); +export const FmBusyState = async () => { + let activeSession = null; + return { + event: async ({ event }) => { + if (event.type === "session.status") { + const sessionID = event.properties.sessionID; + const statusType = event.properties.status && event.properties.status.type; + if (statusType === "busy" || statusType === "retry") { + if (activeSession === null) activeSession = sessionID; + if (sessionID === activeSession) await busyEvent("busy", "session-" + statusType); + return; + } + if (statusType === "idle" && sessionID === activeSession) { + activeSession = null; + await busyEvent("idle", "session-status-idle"); + } + return; + } + if (event.type === "session.idle") { + if (event.properties.sessionID === activeSession) { + activeSession = null; + await busyEvent("idle", "session-idle"); + } + await new Promise((resolve) => { + execFile("touch", ["$TURNEND"], () => resolve()); + }); + } + }, + }; +}; EOF - exclude_path '.opencode/plugins/fm-turn-end.js' + exclude_path '.opencode/plugins/fm-busy-state.js' ;; pi|pi-signed) # Written OUTSIDE the worktree: pi's project-trust gate fires on any extension # loaded from inside the project (verified live), but an explicit -e path # elsewhere loads without a dialog. Lives in state/, cleaned by teardown. cat > "$STATE/$ID.pi-ext.ts" <<EOF -// Firstmate turn-end signal; written by fm-spawn. -// Use "turn_end" (fires after each turn the agent finishes), not "agent_end" -// (fires once, only when the whole run exits): the watcher needs a signal at -// every turn boundary so an idle crewmate is surfaced, not just at shutdown. +// Firstmate semantic busy-state events + turn-end notification; written by +// fm-spawn under the contract owned by bin/fm-busy-lib.sh. +// Semantic state: "agent_start" -> busy when a low-level agent run begins; +// "agent_settled" -> idle only when ctx.isIdle() confirms Pi will not +// continue automatically - auto-retries, auto-compaction retries, tool +// loops, and queued continuations all keep the run un-settled, and a settle +// that raced another extension's fresh run keeps state busy via isIdle(). +// "turn_end" fires at every inner turn boundary (one LLM response plus its +// tool calls) and stays a wake NOTIFICATION touch for the watcher, never +// current-state truth. import { execFile } from "node:child_process"; +const busyEvent = (state: string, event: string) => + new Promise<void>((resolve) => { + execFile("$FM_ROOT/bin/fm-busy-event.sh", [ + "apply", "$STATE_REAL", "$ID", state, + "--gen", "$BUSY_GEN", "--source", "pi-ext", "--event", event, + ], () => resolve()); + }); export default function (pi: any) { + pi.on("agent_start", () => busyEvent("busy", "agent-start")); + pi.on("agent_settled", (_event: any, ctx: any) => { + if (ctx && typeof ctx.isIdle === "function" && !ctx.isIdle()) return; + return busyEvent("idle", "agent-settled"); + }); pi.on("turn_end", () => execFile("touch", ["$TURNEND"])); } EOF ;; codex*) - # codex: turn-end rides the launch command via -c notify=[...] and __TURNEND__. + # Semantic busy-state source negotiation (bin/fm-busy-lib.sh owns the + # probes and the evidence). Neither Codex path is usable on the + # installed binary: a pane worker's turns are not observable through + # the app-server protocol, and its lifecycle hooks did not fire for a + # firstmate-launched worker. Codex therefore classifies unknown with + # an explicit reason rather than falling back to idle, and no busy + # wiring is installed. The turn-end NOTIFICATION marker still rides + # the launch command via -c notify=[...] and __TURNEND__. ;; grok*) # grok fires a Stop hook at every turn boundary (verified, grok 0.2.73), the @@ -1501,11 +1648,10 @@ fi # Recorded in meta so fm-teardown's safety check and the validate/merge stages can # branch on them. Mode governs ship tasks; a scout's deliverable is a report, not a # merge, so scout teardown ignores mode. -SECONDMATE_PROJECTS= if [ "$KIND" = secondmate ]; then MODE=secondmate YOLO=off - SECONDMATE_PROJECTS=$(secondmate_registry_value "$ID" projects || true) + : "${SECONDMATE_PROJECTS:=}" else PROJ_NAME=$(basename "$PROJ_ABS") read -r MODE YOLO <<EOF @@ -1533,6 +1679,7 @@ fi echo "browsertmp=$BROWSER_TMP" echo "model=${MODEL:-default}" echo "effort=${EFFORT:-default}" + [ -z "${BUSY_GEN:-}" ] || echo "busy_gen=$BUSY_GEN" # backend= is written only for a non-default (non-tmux) backend, so the # default path's meta stays byte-identical (absent backend= means tmux; # data/fm-backend-design-d7's P1 compatibility contract). @@ -1609,7 +1756,8 @@ if [ "$HARNESS" = claude ] && [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then fi if [ "$KIND" = secondmate ]; then sq_home=$(shell_quote "$PROJ_ABS") - LAUNCH="FM_ROOT_OVERRIDE= FM_STATE_OVERRIDE= FM_DATA_OVERRIDE= FM_PROJECTS_OVERRIDE= FM_CONFIG_OVERRIDE= FM_HOME=$sq_home $LAUNCH" + sq_primary_home=$(shell_quote "$FM_HOME") + LAUNCH="FM_ROOT_OVERRIDE= FM_STATE_OVERRIDE= FM_DATA_OVERRIDE= FM_PROJECTS_OVERRIDE= FM_CONFIG_OVERRIDE= FM_PUBLIC_FOLLOWUP_PRIMARY_HOME=$sq_primary_home FM_HOME=$sq_home $LAUNCH" fi # Export the task temp roots into the crewmate's pane shell so the agent and # every child inherit them. TMPDIR gives Puppeteer a task-attributable profile diff --git a/bin/fm-startup-memory-budget-lib.sh b/bin/fm-startup-memory-budget-lib.sh new file mode 100644 index 00000000000..f2c06014b8e --- /dev/null +++ b/bin/fm-startup-memory-budget-lib.sh @@ -0,0 +1,224 @@ +# shellcheck shell=bash +# Startup-memory budget primitives. +# Usage: . bin/fm-startup-memory-budget-lib.sh +# +# The local, primary-authoritative config/startup-memory-budget setting is one +# strictly formatted positive decimal value followed by one newline. The +# locked primary bootstrap owns first materialization. This library owns safe +# parsing, default publication, and the portable prompt-memory estimate used by +# bin/fm-startup-memory-budget.sh and the internal /stow skill. + +FM_STARTUP_MEMORY_BUDGET_FILE="startup-memory-budget" +FM_STARTUP_MEMORY_BUDGET_DEFAULT="7500" +FM_STARTUP_MEMORY_BUDGET_ERROR="" +FM_STARTUP_MEMORY_BUDGET_VALUE="" +FM_STARTUP_MEMORY_MEASURE_BYTES="" +FM_STARTUP_MEMORY_MEASURE_TOKENS="" +FM_STARTUP_MEMORY_MEASURE_PRESENCE="" + +fm_startup_memory_budget_fail() { + FM_STARTUP_MEMORY_BUDGET_ERROR=$1 + return 1 +} + +fm_startup_memory_budget_link_count() { + if [ "$(uname)" = Darwin ]; then + stat -f %l "$1" 2>/dev/null + else + stat -c %h "$1" 2>/dev/null + fi +} + +fm_startup_memory_budget_config_dir_safe() { + local dir=$1 + if [ -L "$dir" ]; then + fm_startup_memory_budget_fail "config directory is symlinked" + return 1 + fi + if [ ! -d "$dir" ]; then + fm_startup_memory_budget_fail "config directory is not a directory" + return 1 + fi + return 0 +} + +# fm_startup_memory_budget_file_valid <path> +# Sets FM_STARTUP_MEMORY_BUDGET_VALUE only for a regular, single-linked file +# containing exactly one positive decimal value and one terminating newline. +fm_startup_memory_budget_file_valid() { + local path=$1 links value + FM_STARTUP_MEMORY_BUDGET_VALUE="" + if [ -L "$path" ]; then + fm_startup_memory_budget_fail "file is symlinked" + return 1 + fi + if [ ! -e "$path" ]; then + fm_startup_memory_budget_fail "file is absent" + return 1 + fi + if [ ! -f "$path" ]; then + fm_startup_memory_budget_fail "file is not a regular file" + return 1 + fi + links=$(fm_startup_memory_budget_link_count "$path") || { + fm_startup_memory_budget_fail "could not inspect file link count" + return 1 + } + if [ "$links" != 1 ]; then + fm_startup_memory_budget_fail "file is hardlinked" + return 1 + fi + value=$(<"$path") || { + fm_startup_memory_budget_fail "could not read file" + return 1 + } + case "$value" in + ''|0|*[!0-9]*|0*) + fm_startup_memory_budget_fail "value must be one positive decimal integer" + return 1 + ;; + esac + if ! printf '%s\n' "$value" | cmp -s "$path" -; then + fm_startup_memory_budget_fail "file must contain exactly one value followed by one newline" + return 1 + fi + FM_STARTUP_MEMORY_BUDGET_VALUE=$value + return 0 +} + +# fm_startup_memory_budget_read <config-dir> +# Prints the validated decimal value. It never treats an absent or unsafe file +# as an implicit default because callers need a visible, auditable setting. +fm_startup_memory_budget_read() { + local config_dir=$1 path + fm_startup_memory_budget_config_dir_safe "$config_dir" || return 1 + path="$config_dir/$FM_STARTUP_MEMORY_BUDGET_FILE" + fm_startup_memory_budget_file_valid "$path" || return 1 + printf '%s\n' "$FM_STARTUP_MEMORY_BUDGET_VALUE" +} + +# fm_startup_memory_budget_materialize <config-dir> +# Atomically publishes the visible default only when the file is absent. A +# concurrent valid creator is accepted; every unsafe or malformed existing +# artifact is rejected without replacement. +fm_startup_memory_budget_materialize() { + local config_dir=$1 path tmp + if [ -e "$config_dir" ] || [ -L "$config_dir" ]; then + fm_startup_memory_budget_config_dir_safe "$config_dir" || return 1 + else + mkdir -p "$config_dir" 2>/dev/null || { + fm_startup_memory_budget_fail "could not create config directory" + return 1 + } + fm_startup_memory_budget_config_dir_safe "$config_dir" || return 1 + fi + + path="$config_dir/$FM_STARTUP_MEMORY_BUDGET_FILE" + if [ -e "$path" ] || [ -L "$path" ]; then + fm_startup_memory_budget_read "$config_dir" >/dev/null || return 1 + return 0 + fi + + tmp=$(umask 077; mktemp "$config_dir/.startup-memory-budget.XXXXXX" 2>/dev/null) || { + fm_startup_memory_budget_fail "could not create default temporary file" + return 1 + } + if ! printf '%s\n' "$FM_STARTUP_MEMORY_BUDGET_DEFAULT" > "$tmp" \ + || ! fm_startup_memory_budget_file_valid "$tmp"; then + rm -f "$tmp" + [ -n "$FM_STARTUP_MEMORY_BUDGET_ERROR" ] \ + || fm_startup_memory_budget_fail "could not write default value" + return 1 + fi + + # link(2) gives no-clobber publication in this directory. Removing the + # temporary name leaves the published file with exactly one link. + if ln "$tmp" "$path" 2>/dev/null; then + rm -f "$tmp" + fm_startup_memory_budget_read "$config_dir" >/dev/null || return 1 + return 0 + fi + rm -f "$tmp" + # Another actor may have created the file. Accept it only if it now meets + # the same safe, exact format - never replace or guess at it. + fm_startup_memory_budget_read "$config_dir" >/dev/null +} + +# fm_startup_memory_estimated_tokens_for_bytes <non-negative bytes> +# The estimate is ceil(UTF-8 bytes / 3): stable, dependency-free, and +# deliberately conservative for ordinary prompt text without claiming provider +# exactness. +fm_startup_memory_estimated_tokens_for_bytes() { + local bytes=$1 tokens + case "$bytes" in + ''|*[!0-9]*) return 1 ;; + esac + tokens=$((bytes / 3)) + if [ $((bytes % 3)) -ne 0 ]; then + tokens=$((tokens + 1)) + fi + printf '%s\n' "$tokens" +} + +# fm_startup_memory_measure_file <path> +# Prints "<bytes> <estimated-tokens> <present|absent>". Memory files must be +# ordinary files when present so a measurement never follows a symlink or reads +# a special file. +fm_startup_memory_measure_file() { + local path=$1 bytes tokens + FM_STARTUP_MEMORY_MEASURE_BYTES="" + FM_STARTUP_MEMORY_MEASURE_TOKENS="" + FM_STARTUP_MEMORY_MEASURE_PRESENCE="" + if [ ! -e "$path" ] && [ ! -L "$path" ]; then + FM_STARTUP_MEMORY_MEASURE_BYTES=0 + FM_STARTUP_MEMORY_MEASURE_TOKENS=0 + FM_STARTUP_MEMORY_MEASURE_PRESENCE=absent + printf '0 0 absent\n' + return 0 + fi + if [ -L "$path" ] || [ ! -f "$path" ]; then + fm_startup_memory_budget_fail "memory file is not an ordinary regular file: $path" + return 1 + fi + bytes=$(LC_ALL=C wc -c < "$path" 2>/dev/null | tr -d '[:space:]') || { + fm_startup_memory_budget_fail "could not measure memory file: $path" + return 1 + } + case "$bytes" in + ''|*[!0-9]*) + fm_startup_memory_budget_fail "invalid byte count for memory file: $path" + return 1 + ;; + esac + tokens=$(fm_startup_memory_estimated_tokens_for_bytes "$bytes") || { + fm_startup_memory_budget_fail "could not estimate memory tokens for: $path" + return 1 + } + # shellcheck disable=SC2034 # Public measurement result consumed by the caller after sourcing. + FM_STARTUP_MEMORY_MEASURE_BYTES=$bytes + # shellcheck disable=SC2034 # Public measurement result consumed by the caller after sourcing. + FM_STARTUP_MEMORY_MEASURE_TOKENS=$tokens + # shellcheck disable=SC2034 # Public measurement result consumed by the caller after sourcing. + FM_STARTUP_MEMORY_MEASURE_PRESENCE=present + printf '%s %s present\n' "$bytes" "$tokens" +} + +# fm_startup_memory_decimal_le <left> <right> +# Decimal comparison without shell arithmetic overflow. Inputs are normalized +# non-negative decimal strings. +fm_startup_memory_decimal_le() { + local left=$1 right=$2 left_len right_len + case "$left:$right" in + *[!0-9:]*|:*|*:) return 1 ;; + esac + left_len=${#left} + right_len=${#right} + if [ "$left_len" -lt "$right_len" ]; then + return 0 + fi + if [ "$left_len" -gt "$right_len" ]; then + return 1 + fi + [ "$left" = "$right" ] && return 0 + [[ "$left" < "$right" ]] +} diff --git a/bin/fm-startup-memory-budget.sh b/bin/fm-startup-memory-budget.sh new file mode 100755 index 00000000000..715da549482 --- /dev/null +++ b/bin/fm-startup-memory-budget.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +# Read and account for the local startup-memory budget. +# Usage: +# fm-startup-memory-budget.sh read +# fm-startup-memory-budget.sh report +# +# `read` prints the one validated effective budget from +# config/startup-memory-budget. `report` prints the stable local estimate for +# data/captain.md, data/captain-shared.md, and data/learnings.md together. +# Bootstrap owns default materialization; this command never creates or repairs +# configuration, so an absent, malformed, symlinked, hardlinked, or otherwise +# unsafe value is a concrete error rather than an inferred default. +set -eu + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}" +FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}" +CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}" +DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}" + +# shellcheck source=bin/fm-startup-memory-budget-lib.sh +. "$SCRIPT_DIR/fm-startup-memory-budget-lib.sh" + +usage() { + sed -n '2,11{s/^# \{0,1\}//;p;}' "$0" +} + +print_error() { + printf 'startup-memory-budget: %s\n' "$1" >&2 +} + +read_budget() { + if ! fm_startup_memory_budget_read "$CONFIG" >/dev/null; then + print_error "invalid config/$FM_STARTUP_MEMORY_BUDGET_FILE - $FM_STARTUP_MEMORY_BUDGET_ERROR" + return 1 + fi + printf '%s\n' "$FM_STARTUP_MEMORY_BUDGET_VALUE" +} + +report() { + local budget bytes tokens presence total=0 shared_tokens=0 role=primary + if ! budget=$(read_budget); then + return 2 + fi + + if [ -e "$FM_HOME/.fm-secondmate-home" ] || [ -L "$FM_HOME/.fm-secondmate-home" ]; then + role=secondmate + fi + + printf 'estimator=ceil(UTF-8 bytes / 3) conservative-local-estimate\n' + printf 'role=%s\n' "$role" + printf 'effective_budget_tokens=%s\n' "$budget" + for file in captain.md captain-shared.md learnings.md; do + if ! fm_startup_memory_measure_file "$DATA/$file" >/dev/null; then + print_error "$FM_STARTUP_MEMORY_BUDGET_ERROR" + return 2 + fi + bytes=$FM_STARTUP_MEMORY_MEASURE_BYTES + tokens=$FM_STARTUP_MEMORY_MEASURE_TOKENS + presence=$FM_STARTUP_MEMORY_MEASURE_PRESENCE + total=$((total + tokens)) + [ "$file" != captain-shared.md ] || shared_tokens=$tokens + printf 'file=data/%s bytes=%s estimated_tokens=%s status=%s\n' \ + "$file" "$bytes" "$tokens" "$presence" + done + printf 'total_estimated_tokens=%s\n' "$total" + if fm_startup_memory_decimal_le "$total" "$budget"; then + printf 'budget_status=within-budget\n' + else + printf 'budget_status=over-budget\n' + fi + if [ "$role" = secondmate ] \ + && ! fm_startup_memory_decimal_le "$shared_tokens" "$budget"; then + printf 'exception=primary-owned-shared-file-alone-exceeds-budget\n' + fi +} + +case "${1:-}" in + read) + [ "$#" -eq 1 ] || { usage >&2; exit 2; } + read_budget + ;; + report) + [ "$#" -eq 1 ] || { usage >&2; exit 2; } + report + ;; + -h|--help) + usage + ;; + *) + usage >&2 + exit 2 + ;; +esac diff --git a/bin/fm-supervise-daemon.sh b/bin/fm-supervise-daemon.sh index 30554edbbd4..400a8bf5357 100755 --- a/bin/fm-supervise-daemon.sh +++ b/bin/fm-supervise-daemon.sh @@ -96,7 +96,8 @@ # (default 300) # FM_HOUSEKEEPING_TICK seconds between housekeeping passes while # the watcher is mid-cycle (default 15) -# FM_BUSY_REGEX optional global busy-signature override +# FM_BUSY_REGEX optional rendered busy-signature override +# for delivery guards and Grok's fallback # FM_COMPOSER_IDLE_RE empty-composer regex applied after dim-ghost # and structural border stripping (default: # bare prompt glyphs plus busy footers) @@ -174,6 +175,11 @@ FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}" # shellcheck source=bin/fm-supervisor-target-lib.sh . "$FM_DAEMON_DIR/fm-supervisor-target-lib.sh" +# The single owner of semantic busy state for recorded tasks +# (fm_busy_classify). +# shellcheck source=bin/fm-busy-lib.sh +. "$FM_DAEMON_DIR/fm-busy-lib.sh" + # --- tunables --------------------------------------------------------------- # Supervisor backends this daemon knows how to inject into today. zellij, orca, # and cmux are real backends elsewhere in firstmate (bin/fm-backend.sh) but this @@ -198,8 +204,9 @@ WEDGE_ALARM_NOTIFIER_PID= # The captain-relevant verb set and the status classifiers (last_status_line, # status_is_captain_relevant, window_to_task, scan_captain_relevant_statuses) now # live in bin/fm-classify-lib.sh, shared with the always-on watcher. -# Composer-empty detection and harness-scoped busy-footer matching live in -# bin/fm-tmux-lib.sh; FM_BUSY_REGEX still overrides every fallback here. +# Composer-empty detection, submit acknowledgement, and the harness-scoped +# supervisor-pane busy guard live in bin/fm-tmux-lib.sh. +# FM_BUSY_REGEX also overrides Grok's isolated task-state fallback. INJECT_FAIL_SLEEP_DEFAULT=30 INJECT_CONFIRM_RETRIES_DEFAULT=3 INJECT_CONFIRM_SLEEP_DEFAULT=0.5 @@ -544,34 +551,45 @@ mark_escalated_seen() { # <kind> <arg> <state> esac } -# Busy + composer-empty detection are the shared primitives in fm-tmux-lib.sh -# (one source of truth with fm-send.sh). These thin wrappers keep the daemon's -# call sites and the unit tests stable. +# Busy and composer-empty detection form the injection boundary. +# These thin wrappers keep the daemon's call sites and unit tests stable. # # pane_input_pending returns 0 unless the composer is positively proven empty. # This includes real unsubmitted text, ambiguous structure, unreadable state, # and future verdicts. The detector drops dim/faint ghost text and strips the # harness's composer box borders, so an aligned ghost-only or idle bordered # claude composer ("│ > … │") is correctly proven empty. -# pane_is_busy / pane_input_pending: BACKEND-AWARE now (previously tmux-only -# direct calls). <backend> defaults to tmux when omitted, so every existing -# caller/test that passes only <target> is unaffected. Dispatch goes through -# bin/fm-backend.sh's generic per-backend primitives (fm_backend_busy_state, -# fm_backend_capture, fm_backend_composer_state) rather than hand-rolling a -# case statement here, mirroring the fallback order stale_window_is_busy uses -# for per-task panes: try the backend's native busy state first, then match -# captured output. The supervisor pane has no recorded task harness and uses -# the historical combined fallback; stale task panes select the recorded -# harness's verified signature. +# pane_is_busy / pane_input_pending: BACKEND-AWARE (dispatch goes through +# bin/fm-backend.sh's generic per-backend primitives rather than a hand-rolled +# case statement here). <backend> defaults to tmux when omitted, so every +# existing caller/test that passes only <target> is unaffected. +# +# This rendered reader applies only to the supervisor pane during away-mode +# injection. It never classifies a recorded worker task. The detected primary +# harness selects exactly one signature, so output from another harness cannot +# make the primary read busy. +# +# Resolved lazily and memoized: harness detection walks process ancestry, which +# is too heavy to pay on every source of this library (the unit tests and the +# launcher source it purely for its pure functions). +fm_daemon_primary_harness() { + if [ -z "${FM_DAEMON_PRIMARY_HARNESS:-}" ]; then + FM_DAEMON_PRIMARY_HARNESS=$("$FM_DAEMON_DIR/fm-harness.sh" 2>/dev/null || printf 'unknown') + [ -n "$FM_DAEMON_PRIMARY_HARNESS" ] || FM_DAEMON_PRIMARY_HARNESS=unknown + fi + printf '%s' "$FM_DAEMON_PRIMARY_HARNESS" +} + pane_is_busy() { # <target> [backend] - local target=$1 backend=${2:-tmux} bs tail40 - bs=$(fm_backend_busy_state "$backend" "$target" 2>/dev/null) - case "$bs" in + local target=$1 backend=${2:-tmux} native tail40 harness + harness=$(fm_daemon_primary_harness) + native=$(fm_backend_busy_state "$backend" "$target" 2>/dev/null) + case "$native" in busy) return 0 ;; esac tail40=$(fm_backend_capture "$backend" "$target" 40 2>/dev/null) || return 1 printf '%s' "$tail40" | grep -v '^[[:space:]]*$' | tail -12 \ - | fm_busy_lines_match + | fm_busy_lines_match "$harness" } # pane_input_pending dispatches through fm_backend_composer_state and treats @@ -593,21 +611,23 @@ task_window_harness() { # <window> <state> local win=$1 state=$2 task meta task=$(window_to_task "$win" "$state") meta="$state/$task.meta" - grep '^harness=' "$meta" | cut -d= -f2- || true + grep '^harness=' "$meta" 2>/dev/null | cut -d= -f2- || true } +# stale_window_is_busy: 0 when the task is PROVABLY working through the +# semantic busy-state contract (bin/fm-busy-lib.sh), 1 when it is not, and 2 +# when the endpoint could not be read at all. Only an exact busy verdict is +# working: unknown semantic state never becomes busy and never becomes a +# silent idle, so a stale pane whose state cannot be proven surfaces. stale_window_is_busy() { # <window> <state> - local win=$1 state=$2 backend harness label tail40 bs + local win=$1 state=$2 backend harness label task tail40 verdict backend=$(task_window_backend "$win" "$state") harness=$(task_window_harness "$win" "$state") - label="fm-$(window_to_task "$win" "$state")" + task=$(window_to_task "$win" "$state") + label="fm-$task" tail40=$(fm_backend_capture "$backend" "$win" 40 "$label" 2>/dev/null) || return 2 - bs=$(fm_backend_busy_state "$backend" "$win" 2>/dev/null) - case "$bs" in - busy) return 0 ;; - esac - printf '%s' "$tail40" | grep -v '^[[:space:]]*$' | tail -12 \ - | fm_busy_lines_match "$harness" + verdict=$(fm_busy_classify "$backend" "$win" "$harness" "$task" "$state" "$tail40") + [ "${verdict%% *}" = busy ] } escalate_add() { # <state> <distilled-item> @@ -1113,8 +1133,7 @@ inject_msg() { # <message> [state] # discovery), matching this function's pre-existing default assumption. backend="${FM_SUPERVISOR_BACKEND:-tmux}" fm_backend_target_exists "$backend" "$target" || return 1 - # (3) Busy-guard: never inject into an in-use pane. - # a) pane_is_busy: the harness shows a busy footer (agent mid-turn). + # (3) Busy-guard: never inject into an in-use supervisor pane. if pane_is_busy "$target" "$backend"; then log "inject deferred: supervisor pane busy (agent mid-turn)" return 1 diff --git a/bin/fm-teardown.sh b/bin/fm-teardown.sh index 289d0781554..ba42dab3493 100755 --- a/bin/fm-teardown.sh +++ b/bin/fm-teardown.sh @@ -122,6 +122,10 @@ SUB_HOME_MARKER=".fm-secondmate-home" . "$SCRIPT_DIR/fm-pr-lib.sh" # shellcheck source=bin/fm-delivery-lib.sh . "$SCRIPT_DIR/fm-delivery-lib.sh" +# shellcheck source=bin/fm-public-followup-lib.sh +. "$SCRIPT_DIR/fm-public-followup-lib.sh" +# shellcheck source=bin/fm-secondmate-registry-lib.sh +. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh" if [ "$#" -lt 1 ] || ! fm_task_id_path_safe "$1"; then echo "error: invalid teardown request" >&2 exit 2 @@ -175,6 +179,10 @@ TASK_TMP=$(grep '^tasktmp=' "$META" | cut -d= -f2- || true) # New tasks also record the home-scoped TMPDIR used by Puppeteer. Older metadata # lacks this field; the reaper falls back to tasktmp, worktree, and process cwd. BROWSER_TMP=$(grep '^browsertmp=' "$META" | cut -d= -f2- || true) +BUSY_GEN=$(fm_meta_get "$META" busy_gen) +if [ -z "$BUSY_GEN" ]; then + BUSY_GEN=$(cat "$STATE/$ID.busy-gen" 2>/dev/null || true) +fi ORCA_WORKTREE_ID=$(fm_meta_get "$META" orca_worktree_id) ORCA_PATH_MATCH_VERIFIED=0 @@ -182,6 +190,70 @@ KIND=$(grep '^kind=' "$META" | cut -d= -f2- || true) [ -n "$KIND" ] || KIND=ship MODE=$(grep '^mode=' "$META" | cut -d= -f2- || true) [ -n "$MODE" ] || MODE=no-mistakes +PUBLIC_FOLLOWUP_HOME=$FM_HOME +PUBLIC_FOLLOWUP_STATE=$STATE +PUBLIC_FOLLOWUP_WORK_HOME=main +PUBLIC_FOLLOWUP_PARENT_UNRESOLVED=0 +PUBLIC_FOLLOWUP_PARENT_RELAY_ACTIVE=0 +PUBLIC_FOLLOWUP_RELAY_ACTIVE=0 +public_followup_resolve_primary_home() { + local parent=$1 child=$2 id=$3 parent_meta registry meta_home + fm_pf_home_id_valid "secondmate:$id" || return 1 + case "$parent" in /*) ;; *) return 1 ;; esac + parent=$(CDPATH='' cd -- "$parent" 2>/dev/null && pwd -P) || return 1 + child=$(CDPATH='' cd -- "$child" 2>/dev/null && pwd -P) || return 1 + [ "$parent" != "$child" ] || return 1 + parent_meta="$parent/state/$id.meta" + [ -f "$parent_meta" ] && [ ! -L "$parent_meta" ] || return 1 + [ "$(fm_meta_get "$parent_meta" kind)" = secondmate ] || return 1 + meta_home=$(fm_meta_get "$parent_meta" home) + meta_home=$(CDPATH='' cd -- "$meta_home" 2>/dev/null && pwd -P) || return 1 + [ "$meta_home" = "$child" ] || return 1 + registry="$parent/data/secondmates.md" + secondmate_registry_validate_bindings "$registry" secondmate_registry_path_key "$id" "$child" || return 1 + printf '%s\n' "$parent" +} +if [ -f "$FM_HOME/$SUB_HOME_MARKER" ]; then + SECOND_MATE_ID=$(sed -n '1p' "$FM_HOME/$SUB_HOME_MARKER") + # A marked child only enters the primary-binding path when the authoritative + # parent relay is active. A child that has not opted into the relay must + # retain the old teardown path, even without a durable parent registry. + if [ -n "${FM_PUBLIC_FOLLOWUP_PRIMARY_HOME:-}" ]; then + if fm_pf_relay_active "$FM_PUBLIC_FOLLOWUP_PRIMARY_HOME"; then + PUBLIC_FOLLOWUP_PARENT_RELAY_ACTIVE=1 + fi + elif fm_pf_relay_active "$FM_HOME"; then + PUBLIC_FOLLOWUP_PARENT_RELAY_ACTIVE=1 + fi + if [ "$PUBLIC_FOLLOWUP_PARENT_RELAY_ACTIVE" = 1 ]; then + PUBLIC_FOLLOWUP_PARENT_UNRESOLVED=1 + if fm_pf_home_id_valid "secondmate:$SECOND_MATE_ID"; then + PUBLIC_FOLLOWUP_WORK_HOME="secondmate:$SECOND_MATE_ID" + if PUBLIC_FOLLOWUP_HOME=$(public_followup_resolve_primary_home \ + "${FM_PUBLIC_FOLLOWUP_PRIMARY_HOME:-}" "$FM_HOME" "$SECOND_MATE_ID"); then + PUBLIC_FOLLOWUP_STATE="$PUBLIC_FOLLOWUP_HOME/state" + PUBLIC_FOLLOWUP_PARENT_UNRESOLVED=0 + if [ "$FORCE" != "--force" ] \ + && fm_pf_relay_active "$PUBLIC_FOLLOWUP_HOME"; then + PUBLIC_FOLLOWUP_RELAY_ACTIVE=1 + fi + else + PUBLIC_FOLLOWUP_HOME= + PUBLIC_FOLLOWUP_STATE= + fi + fi + else + PUBLIC_FOLLOWUP_HOME= + PUBLIC_FOLLOWUP_STATE= + fi +elif [ "$KIND" = secondmate ]; then + PUBLIC_FOLLOWUP_WORK_HOME="secondmate:$ID" + if [ "$FORCE" != "--force" ] && fm_pf_relay_active "$FM_HOME"; then + PUBLIC_FOLLOWUP_RELAY_ACTIVE=1 + fi +elif [ "$FORCE" != "--force" ] && fm_pf_relay_active "$FM_HOME"; then + PUBLIC_FOLLOWUP_RELAY_ACTIVE=1 +fi default_branch() { local ref branch @@ -295,6 +367,15 @@ remove_kimi_turnend_auth() { rm -f "$hooks_dir/$token" } +retire_busy_state() { + local state_dir=$1 id=$2 gen=${3:-} + if [ -n "$gen" ]; then + "$SCRIPT_DIR/fm-busy-event.sh" retire "$state_dir" "$id" --gen "$gen" + elif [ -f "$state_dir/$id.busy-gen" ]; then + "$SCRIPT_DIR/fm-busy-event.sh" retire "$state_dir" "$id" --current-gen + fi +} + validate_pr_poll_cleanup() { local state_dir=$1 id=$2 quarantine state_device artifact has_artifact=0 fm_task_id_path_safe "$id" || return 0 @@ -538,10 +619,6 @@ backlog_refresh_reminder() { fi } -registry_home_for_line() { - sed -n 's/^[^(]*(home: \([^;)]*\);.*/\1/p' -} - path_is_ancestor_of() { local ancestor=$1 path=$2 [ -n "$ancestor" ] || return 1 @@ -897,13 +974,19 @@ validate_removal_target() { registered_descendant_home_for_removal() { local reg=$1 target=$2 line id registered_home registered_abs [ -f "$reg" ] || return 1 - while IFS= read -r line; do + if ! secondmate_registry_validate_bindings "$reg" secondmate_registry_path_key; then + echo "REFUSED: $SECONDMATE_REGISTRY_ERROR" >&2 + return 2 + fi + while IFS= read -r line || [ -n "$line" ]; do case "$line" in "- "*) - id=${line#- } - id=${id%% *} - registered_home=$(printf '%s\n' "$line" | registry_home_for_line) - [ -n "$registered_home" ] || continue + secondmate_registry_parse_line "$line" || { + echo "REFUSED: malformed secondmate registry entry: $line" >&2 + return 2 + } + id=$SECONDMATE_REGISTRY_ID + registered_home=$SECONDMATE_REGISTRY_HOME registered_abs=$(removal_target_abs_path "$registered_home" 2>/dev/null || true) [ -n "$registered_abs" ] || continue [ "$registered_abs" = "$target" ] && continue @@ -992,11 +1075,33 @@ validate_firstmate_home_for_removal() { echo "REFUSED: unsafe $label removal target $home is marked for secondmate ${marker_id:-unknown}, expected $expected_id" >&2 return 1 fi + if [ -e "$SECONDMATE_REG" ] || [ -L "$SECONDMATE_REG" ]; then + if ! secondmate_registry_validate_bindings "$SECONDMATE_REG" secondmate_registry_path_key "$expected_id" "$abs_home_path"; then + case "$SECONDMATE_REGISTRY_ERROR" in + overlapping\ secondmate\ home\ assignment:*) + echo "REFUSED: unsafe $label removal target $home contains registered secondmate home; $SECONDMATE_REGISTRY_ERROR" >&2 + ;; + *) echo "REFUSED: $SECONDMATE_REGISTRY_ERROR" >&2 ;; + esac + return 1 + fi + fi fi validate_firstmate_operational_dirs_for_removal "$abs_home_path" "$label" || return 1 - conflict=$(registered_descendant_home_for_removal "$SECONDMATE_REG" "$abs_home_path" || true) + conflict= + if conflict=$(registered_descendant_home_for_removal "$SECONDMATE_REG" "$abs_home_path"); then + : + else + conflict_rc=$? + [ "$conflict_rc" -eq 1 ] || return 1 + fi if [ -z "$conflict" ]; then - conflict=$(registered_descendant_home_for_removal "$abs_home_path/data/secondmates.md" "$abs_home_path" || true) + if conflict=$(registered_descendant_home_for_removal "$abs_home_path/data/secondmates.md" "$abs_home_path"); then + : + else + conflict_rc=$? + [ "$conflict_rc" -eq 1 ] || return 1 + fi fi if [ -n "$conflict" ]; then IFS=$'\t' read -r child_id child_home <<EOF @@ -1060,8 +1165,144 @@ validate_firstmate_home_children_removal() { done } +TEARDOWN_HERDR_LOCK_RECORDS= +teardown_release_herdr_locks() { + local lock_session lock_path + [ -n "$TEARDOWN_HERDR_LOCK_RECORDS" ] || return 0 + while IFS=$'\t' read -r lock_session lock_path; do + [ -n "$lock_path" ] || continue + fm_lock_release "$lock_path" || true + done <<FMEOF +$TEARDOWN_HERDR_LOCK_RECORDS +FMEOF + TEARDOWN_HERDR_LOCK_RECORDS= +} + +teardown_herdr_session_lock_held() { # <session> + local session=$1 lock_session lock_path + [ -n "$TEARDOWN_HERDR_LOCK_RECORDS" ] || return 1 + while IFS=$'\t' read -r lock_session lock_path; do + [ "$lock_session" != "$session" ] || return 0 + done <<FMEOF +$TEARDOWN_HERDR_LOCK_RECORDS +FMEOF + return 1 +} + +teardown_herdr_require_prerequisites() { # <task-id> + local task_id=$1 prerequisite + if ! fm_backend_source herdr; then + echo "error: herdr teardown prerequisites are unavailable for $task_id; nothing was changed - restore the adapter and rerun teardown" >&2 + return 1 + fi + for prerequisite in \ + fm_backend_herdr_parse_target \ + fm_backend_herdr_pane_presence_state \ + fm_backend_herdr_workspace_presence_state \ + fm_backend_herdr_endpoint_confirmed_gone \ + fm_backend_herdr_explicit_close_pane_confirmed \ + fm_backend_herdr_presentation_session_lock_path; do + if ! declare -F "$prerequisite" >/dev/null 2>&1; then + echo "error: herdr teardown prerequisites are unavailable for $task_id; nothing was changed - restore the adapter and rerun teardown" >&2 + return 1 + fi + done + if ! declare -F fm_lock_try_acquire >/dev/null 2>&1; then + # shellcheck source=bin/fm-wake-lib.sh + . "$SCRIPT_DIR/fm-wake-lib.sh" + fi + if ! declare -F fm_lock_try_acquire >/dev/null 2>&1 \ + || ! declare -F fm_lock_release >/dev/null 2>&1; then + echo "error: herdr teardown lock machinery is unavailable for $task_id; nothing was changed - restore the lock support and rerun teardown" >&2 + return 1 + fi +} + +teardown_herdr_preflight_target() { # <target> <task-id> + local target=$1 task_id=$2 session pane presence lock_path verified_lock_path lock_session held_path attempt + teardown_herdr_require_prerequisites "$task_id" || return 1 + if ! fm_backend_herdr_parse_target "$target"; then + echo "error: herdr endpoint $target for $task_id could not be parsed exactly; nothing was changed - repair the endpoint metadata and rerun teardown" >&2 + return 1 + fi + session=$FM_BACKEND_HERDR_SESSION + pane=$FM_BACKEND_HERDR_PANE + presence=$(fm_backend_herdr_pane_presence_state "$session" "$pane") + case "$presence" in + dead|present) ;; + *) + echo "error: herdr endpoint $target for $task_id has ambiguous structured presence; nothing was changed - restore reliable endpoint inspection and rerun teardown" >&2 + return 1 + ;; + esac + if ! lock_path=$(fm_backend_herdr_presentation_session_lock_path "$session"); then + echo "error: herdr session presentation lock could not be resolved for $task_id; nothing was changed - rerun teardown once the session is reachable and unambiguous" >&2 + return 1 + fi + if [ -n "$TEARDOWN_HERDR_LOCK_RECORDS" ]; then + while IFS=$'\t' read -r lock_session held_path; do + if [ "$lock_session" = "$session" ]; then + if [ "$held_path" != "$lock_path" ]; then + echo "error: herdr session presentation lock changed during preflight for $task_id; nothing was changed - rerun teardown once session identity is stable" >&2 + return 1 + fi + return 0 + fi + done <<FMEOF +$TEARDOWN_HERDR_LOCK_RECORDS +FMEOF + fi + attempt=0 + while [ "$attempt" -lt 50 ]; do + if fm_lock_try_acquire "$lock_path"; then + if ! verified_lock_path=$(fm_backend_herdr_presentation_session_lock_path "$session") \ + || [ "$verified_lock_path" != "$lock_path" ]; then + fm_lock_release "$lock_path" || true + echo "error: herdr session presentation lock changed during preflight for $task_id; nothing was changed - rerun teardown once session identity is stable" >&2 + return 1 + fi + if [ -n "$TEARDOWN_HERDR_LOCK_RECORDS" ]; then + TEARDOWN_HERDR_LOCK_RECORDS="$TEARDOWN_HERDR_LOCK_RECORDS +$session $lock_path" + else + TEARDOWN_HERDR_LOCK_RECORDS="$session $lock_path" + fi + trap teardown_release_herdr_locks EXIT + return 0 + fi + sleep 0.1 + attempt=$((attempt + 1)) + done + echo "error: herdr session presentation lock is contended for $task_id; nothing was changed - rerun teardown once the contention clears" >&2 + return 1 +} + +preflight_firstmate_home_herdr_children() { # <home> + local home=$1 sub_state child_meta child_id child_backend child_target child_kind child_home child_wt + sub_state="$home/state" + [ -d "$sub_state" ] || return 0 + for child_meta in "$sub_state"/*.meta; do + [ -e "$child_meta" ] || continue + child_id=$(basename "$child_meta" .meta) + fm_backend_validate_task_endpoint "$child_meta" "$child_id" || return 1 + child_backend=$FM_BACKEND_VALIDATED_BACKEND + child_target=$FM_BACKEND_VALIDATED_TARGET + if [ "$child_backend" = herdr ]; then + teardown_herdr_preflight_target "$child_target" "$child_id" || return 1 + fi + child_kind=$(meta_value "$child_meta" kind) + [ -n "$child_kind" ] || child_kind=ship + if [ "$child_kind" = secondmate ]; then + child_wt=$(meta_value "$child_meta" worktree) + child_home=$(meta_value "$child_meta" home) + [ -n "$child_home" ] || child_home=$child_wt + preflight_firstmate_home_herdr_children "$child_home" || return 1 + fi + done +} + cleanup_firstmate_home_children() { - local home=$1 sub_state child_meta child_id child_t child_tab child_wt child_proj child_kind child_home child_backend child_orca_worktree_id child_return_rc + local home=$1 sub_state child_meta child_id child_t child_tab child_wt child_proj child_kind child_home child_backend child_orca_worktree_id child_return_rc child_busy_gen local child_endpoint_home child_endpoint_root sub_state="$home/state" [ -d "$sub_state" ] || return 0 @@ -1094,7 +1335,20 @@ cleanup_firstmate_home_children() { fm_backend_task_endpoint_ownership "$child_meta" "$child_id" "$home" "$home" || return 1 child_endpoint_home=$FM_BACKEND_ENDPOINT_OWNING_HOME child_endpoint_root=$FM_BACKEND_ENDPOINT_OWNING_ROOT - if [ "$child_backend" = zellij ]; then + if [ "$child_backend" = herdr ]; then + fm_backend_herdr_parse_target "$child_t" || return 1 + if ! teardown_herdr_session_lock_held "$FM_BACKEND_HERDR_SESSION"; then + echo "error: herdr session presentation lock is not held for child $child_id; retaining that child's durable identity records and stopping forced cleanup" >&2 + return 1 + fi + fm_backend_herdr_kill_serialized "$FM_BACKEND_HERDR_SESSION" "$FM_BACKEND_HERDR_PANE" 2>/dev/null || true + if ! fm_backend_herdr_endpoint_confirmed_gone "$child_t"; then + echo "error: herdr pane $child_t for child $child_id is not confirmed gone; retaining that child's durable identity records and stopping forced cleanup" >&2 + return 1 + fi + elif [ "$child_backend" = zellij ]; then + # Zellij titles are scoped by the owning home tag, so forced secondmate + # cleanup must verify child tabs as that child home, not the parent. ( unset FM_ROOT_OVERRIDE; FM_HOME=$child_endpoint_home FM_ROOT=$child_endpoint_root fm_backend_kill "$child_backend" "$child_t" "$(meta_value "$child_meta" zellij_tab_id)" "fm-$child_id" "$(meta_value "$child_meta" herdr_workspace_id)" ) 2>/dev/null || true else child_tab=$(meta_value "$child_meta" zellij_tab_id) @@ -1107,7 +1361,7 @@ cleanup_firstmate_home_children() { child_home=$(meta_value "$child_meta" home) [ -n "$child_home" ] || child_home=$child_wt if [ -n "$child_home" ] && [ -d "$child_home" ]; then - cleanup_firstmate_home_children "$child_home" + cleanup_firstmate_home_children "$child_home" || return 1 remove_firstmate_home "$child_home" "child firstmate home" "$child_id" fi elif [ "$child_backend" = orca ]; then @@ -1120,6 +1374,7 @@ cleanup_firstmate_home_children() { elif [ -n "$child_wt" ] && [ -d "$child_wt" ]; then validate_child_worktree_for_removal "$child_wt" "$child_proj" >/dev/null || return 1 rm -f "$child_wt/.claude/settings.local.json" "$child_wt/.opencode/plugins/fm-turn-end.js" \ + "$child_wt/.opencode/plugins/fm-busy-state.js" \ "$child_wt/.fm-grok-turnend" "$child_wt/.fm-kimi-turnend" if [ -n "$child_proj" ] && [ -d "$child_proj" ] && command -v treehouse >/dev/null 2>&1; then if teardown_treehouse_return "$child_wt" "$child_proj" "child worktree"; then @@ -1139,6 +1394,11 @@ cleanup_firstmate_home_children() { remove_grok_turnend_auth "$sub_state" "$child_id" remove_kimi_turnend_auth "$sub_state" "$child_id" remove_pr_poll_artifacts "$sub_state" "$child_id" || return 1 + child_busy_gen=$(meta_value "$child_meta" busy_gen) + if [ -z "$child_busy_gen" ]; then + child_busy_gen=$(cat "$sub_state/$child_id.busy-gen" 2>/dev/null || true) + fi + retire_busy_state "$sub_state" "$child_id" "$child_busy_gen" || return 1 rm -f "$sub_state/$child_id.status" "$sub_state/$child_id.turn-ended" \ "$sub_state/$child_id.meta" "$sub_state/$child_id.pi-ext.ts" \ "$sub_state/$child_id.grok-turnend-token" "$sub_state/$child_id.kimi-turnend-token" @@ -1160,6 +1420,10 @@ if [ "$KIND" = secondmate ]; then validate_firstmate_home_for_removal "$HOME_PATH" "secondmate home" "$ID" >/dev/null || exit 1 if [ "$FORCE" = "--force" ]; then validate_firstmate_home_children_removal "$HOME_PATH" || exit 1 + if [ "$BACKEND" = herdr ]; then + teardown_herdr_preflight_target "$T" "$ID" || exit 1 + fi + preflight_firstmate_home_herdr_children "$HOME_PATH" || exit 1 fi fi @@ -1202,6 +1466,28 @@ if [ "$KIND" = scout ] && [ "$FORCE" != "--force" ]; then } fi +# A public commitment is not kept until its final reply lands in the ORIGINAL +# thread, and this cleanup removes the task records that make the promise +# reconcilable. Refuse while this home still owes a public reply for exactly this +# work. Both gates live in bin/fm-public-followup-lib.sh, so a home that never +# opted into the myfirstmate relay runs one [ -f ] test and nothing else here. +if [ "$FORCE" != "--force" ] && [ "$PUBLIC_FOLLOWUP_PARENT_UNRESOLVED" = 1 ]; then + echo "REFUSED: cannot resolve the primary home for marked secondmate $SECOND_MATE_ID; refusing cleanup without its durable parent binding." >&2 + exit 1 +fi +if [ "$FORCE" != "--force" ] \ + && [ -n "$PUBLIC_FOLLOWUP_STATE" ] \ + && [ "$PUBLIC_FOLLOWUP_RELAY_ACTIVE" = 1 ] \ + && fm_pf_has_registrations "$PUBLIC_FOLLOWUP_STATE"; then + if ! PUBLIC_FOLLOWUP_BLOCKING=$(FM_HOME="$PUBLIC_FOLLOWUP_HOME" FM_STATE_OVERRIDE="$PUBLIC_FOLLOWUP_STATE" \ + "$SCRIPT_DIR/fm-public-followup.sh" guard-work "$PUBLIC_FOLLOWUP_WORK_HOME" "$ID" 2>/dev/null); then + echo "REFUSED: task $ID still owes a public reply through the myfirstmate relay." >&2 + printf '%s\n' "$PUBLIC_FOLLOWUP_BLOCKING" >&2 + echo "Deliver it with bin/fm-public-followup.sh deliver <obligation-id>, waive it with tasks-axi public-followup waive, or use --force after explicit discard approval." >&2 + exit 1 + fi +fi + if [ "$BACKEND" = orca ] && [ "$KIND" != scout ] && [ "$KIND" != secondmate ] && [ "$FORCE" != "--force" ]; then if ! inspectable_git_worktree "$WT"; then echo "REFUSED: Orca ship task $ID has no inspectable git worktree at ${WT:-<missing>}." >&2 @@ -1266,6 +1552,22 @@ reap_task_browsers "$FM_HOME" "$STATE" "$ID" "$FM_ROOT" || { exit 1 } +# A Herdr close may reposition shared workspace order, so the whole +# destructive sequence below (worktree return, pane close, record removal) +# runs under the named-session presentation lock, acquired BEFORE anything is +# returned or erased: a contended lock refuses here while the isolated copy, +# every durable record, and the endpoint are all still intact for a plain +# rerun. An unresolvable lock path (for example an unreachable server) also +# refuses before any destructive step. +TEARDOWN_HERDR_SESSION= +TEARDOWN_HERDR_PANE= +if [ "$BACKEND" = herdr ]; then + teardown_herdr_preflight_target "$T" "$ID" || exit 1 + fm_backend_herdr_parse_target "$T" || exit 1 + TEARDOWN_HERDR_SESSION=$FM_BACKEND_HERDR_SESSION + TEARDOWN_HERDR_PANE=$FM_BACKEND_HERDR_PANE +fi + # Best-effort: drop the local task branch so the shared repo does not accumulate refs. if [ "$BACKEND" = orca ] && [ "$KIND" != secondmate ]; then if [ "$ORCA_PATH_MATCH_VERIFIED" != 1 ]; then @@ -1280,6 +1582,7 @@ if [ "$BACKEND" = orca ] && [ "$KIND" != secondmate ]; then fi fi rm -f "$WT/.claude/settings.local.json" "$WT/.opencode/plugins/fm-turn-end.js" \ + "$WT/.opencode/plugins/fm-busy-state.js" \ "$WT/.fm-grok-turnend" "$WT/.fm-kimi-turnend" fi [ -z "$T_ORCA" ] || kill_endpoint_verified "$BACKEND" "$T" "$(meta_value "$META" zellij_tab_id)" "fm-$ID" @@ -1333,29 +1636,20 @@ if [ "$BACKEND" = herdr ] \ fi if [ "$HERDR_PRESENTATION_RETIRE_CANDIDATE" = 1 ]; then - # shellcheck source=bin/fm-wake-lib.sh - . "$SCRIPT_DIR/fm-wake-lib.sh" - HERDR_PRESENTATION_FOCUS_LOCK= - HERDR_PRESENTATION_FOCUS_LOCK_HELD=0 - HERDR_PRESENTATION_FOCUS_LOCK_ATTEMPT=0 - if HERDR_PRESENTATION_FOCUS_LOCK=$(fm_backend_herdr_presentation_session_lock_path "$HERDR_PRESENTATION_SESSION"); then - while [ "$HERDR_PRESENTATION_FOCUS_LOCK_ATTEMPT" -lt 50 ]; do - if fm_lock_try_acquire "$HERDR_PRESENTATION_FOCUS_LOCK"; then - HERDR_PRESENTATION_FOCUS_LOCK_HELD=1 - break - fi - sleep 0.1 - HERDR_PRESENTATION_FOCUS_LOCK_ATTEMPT=$((HERDR_PRESENTATION_FOCUS_LOCK_ATTEMPT + 1)) - done - fi - if [ "$HERDR_PRESENTATION_FOCUS_LOCK_HELD" = 1 ]; then + # The presentation lock was acquired before the worktree return above; a + # contended lock already refused this teardown while everything was intact. + if teardown_herdr_session_lock_held "$HERDR_PRESENTATION_SESSION"; then fm_backend_herdr_projection_close_pane_focus_preserving \ "$HERDR_PRESENTATION_SESSION" "$HERDR_PRESENTATION_PANE" 2>/dev/null || true - HERDR_PRESENTATION_FOCUS_LOCK_HELD=0 - fm_lock_release "$HERDR_PRESENTATION_FOCUS_LOCK" || true else echo "warning: herdr presentation focus lock unavailable; refusing a concurrent focus-unsafe pane close" >&2 fi +elif [ "$BACKEND" = herdr ]; then + if teardown_herdr_session_lock_held "$TEARDOWN_HERDR_SESSION"; then + fm_backend_herdr_kill_serialized "$TEARDOWN_HERDR_SESSION" "$TEARDOWN_HERDR_PANE" 2>/dev/null || true + else + echo "warning: herdr session presentation lock path is unavailable; skipping the pane close rather than closing unlocked" >&2 + fi elif [ "$BACKEND" != orca ]; then endpoint_tab=$(meta_value "$META" zellij_tab_id) [ "$BACKEND" != herdr ] || endpoint_tab=$(meta_value "$META" herdr_tab_id) @@ -1372,6 +1666,23 @@ elif [ "$BACKEND" = herdr ] \ && { [ -e "$HERDR_PRESENTATION_JOURNAL" ] || [ -L "$HERDR_PRESENTATION_JOURNAL" ]; }; then echo "warning: herdr presentation journal for $ID remains quarantined; no workspace cleanup was attempted" >&2 fi +# A refused, skipped, or failed Herdr close must never erase a live task's +# durable endpoint identity: unless the exact pane is confirmed gone, retain +# every record and stop before any removal below so a later rerun can retry +# the locked close. Only a structured not-found proves the pane gone; unknown +# presence, missing or malformed endpoint identity, and missing confirmation +# machinery all refuse. +if [ "$BACKEND" = herdr ]; then + fm_backend_source herdr || true + if ! declare -F fm_backend_herdr_endpoint_confirmed_gone >/dev/null 2>&1; then + echo "error: herdr endpoint confirmation is unavailable for $ID; retaining every durable task record" >&2 + exit 1 + fi + if ! fm_backend_herdr_endpoint_confirmed_gone "$T"; then + echo "error: herdr pane $T for $ID is not confirmed gone after its close was refused, skipped, or failed; retaining every durable task record - rerun teardown once the close can run under the session lock" >&2 + exit 1 + fi +fi if [ "$KIND" = secondmate ]; then [ -n "$HOME_PATH" ] || HOME_PATH=$WT remove_firstmate_home "$HOME_PATH" "secondmate home" "$ID" @@ -1393,6 +1704,7 @@ reap_task_browsers "$FM_HOME" "$STATE" "$ID" "$FM_ROOT" || { [ -n "$BROWSER_TMP" ] && rm -rf "$BROWSER_TMP" [ -n "$TASK_TMP" ] && rm -rf "$TASK_TMP" remove_pr_poll_artifacts "$STATE" "$ID" || exit 1 +retire_busy_state "$STATE" "$ID" "$BUSY_GEN" || exit 1 rm -f "$STATE/$ID.status" "$STATE/$ID.turn-ended" "$STATE/$ID.meta" \ "$STATE/$ID.pi-ext.ts" "$STATE/$ID.grok-turnend-token" \ "$STATE/$ID.kimi-turnend-token" "$STATE/$ID.delivery-override" diff --git a/bin/fm-test-isolation-proof.sh b/bin/fm-test-isolation-proof.sh index f84f8ed09ef..7c0eb75d9d3 100755 --- a/bin/fm-test-isolation-proof.sh +++ b/bin/fm-test-isolation-proof.sh @@ -121,7 +121,7 @@ exclusion_reason() { fm-afk-pi-herdr-return-e2e.test.sh|\ fm-codex-continuity-live-e2e.test.sh|fm-grok-continuity-live-e2e.test.sh|\ fm-opencode-primary-live-e2e.test.sh|fm-pi-primary-live-e2e.test.sh|\ - fm-send-secondmate-marker-herdr-e2e.test.sh) + fm-quota-array-dispatch-live-e2e.test.sh|fm-send-secondmate-marker-herdr-e2e.test.sh) printf '%s\n' 'live harness opt-in; never default parallel CI' ;; fm-backend-autodetect-smoke.test.sh|fm-backend-herdr-eventwait-smoke.test.sh|\ @@ -198,6 +198,7 @@ fm-afk-inject-e2e.test.sh fm-backend-herdr-smoke.test.sh fm-backend-cmux-smoke.test.sh fm-pi-primary-live-e2e.test.sh +fm-quota-array-dispatch-live-e2e.test.sh EOF } diff --git a/bin/fm-test-run.sh b/bin/fm-test-run.sh index bf9955429c5..633663d82d1 100755 --- a/bin/fm-test-run.sh +++ b/bin/fm-test-run.sh @@ -117,7 +117,8 @@ now_ms() { # unclassified so new tests are still runnable and visible in summaries. family_for_basename() { case "$1" in - fm-arm-pretool-check.test.sh|fm-ask-user-authority.test.sh|fm-brief.test.sh|\ + fm-arm-pretool-check.test.sh|fm-ask-user-authority.test.sh|\ + fm-brief.test.sh|fm-vendor-auth-probe.test.sh|\ fm-calm-pi-extension.test.sh|fm-cd-pretool-check.test.sh|\ fm-codex-cage.test.sh|\ fm-composer-ghost.test.sh|fm-composer-lib.test.sh|\ @@ -139,6 +140,7 @@ family_for_basename() { ;; fm-afk-inject-herdr-e2e.test.sh|fm-afk-launch.test.sh|fm-backend-autodetect-smoke.test.sh|\ fm-backend-herdr-eventwait-smoke.test.sh|fm-backend-herdr-presentation-e2e.test.sh|\ + fm-backend-herdr-launcher-workspace-e2e.test.sh|\ fm-backend-herdr-prune-safety-e2e.test.sh|fm-backend-herdr-respawn-idem-e2e.test.sh|\ fm-herdr-session-cleanup-e2e.test.sh|\ fm-backend-herdr-smoke.test.sh|fm-backend-herdr-workspace-per-home-e2e.test.sh) @@ -146,6 +148,7 @@ family_for_basename() { ;; fm-backlog-handoff.test.sh|fm-secondmate-harness.test.sh|fm-secondmate-lifecycle-e2e.test.sh|\ fm-secondmate-liveness.test.sh|fm-secondmate-safety.test.sh|fm-secondmate-sync.test.sh|\ + fm-startup-memory-budget.test.sh|\ fm-send-secondmate-marker.test.sh|fm-shared-captain-inheritance.test.sh) printf '%s\n' secondmate ;; @@ -157,7 +160,7 @@ family_for_basename() { fm-afk-pi-herdr-return-e2e.test.sh|fm-codex-cage-live-e2e.test.sh|\ fm-codex-continuity-live-e2e.test.sh|fm-grok-continuity-live-e2e.test.sh|\ fm-grok-stop-live-e2e.test.sh|fm-opencode-primary-live-e2e.test.sh|fm-pi-primary-live-e2e.test.sh|\ - fm-send-secondmate-marker-herdr-e2e.test.sh) + fm-quota-array-dispatch-live-e2e.test.sh|fm-send-secondmate-marker-herdr-e2e.test.sh) printf '%s\n' live-harness-optin ;; fm-backend-herdr.test.sh|fm-backend-tmux-smoke.test.sh|fm-backend.test.sh|\ @@ -588,7 +591,7 @@ families_for_test_reference() { # Conservative path → family map. Over-selects rather than under-selects. # Never expands to the complete suite. families_for_changed_path() { - local path=$1 + local path=$1 fixture_ref case "$path" in tests/fm-test-run.test.sh) printf '%s\n' pure-contract-unit @@ -645,13 +648,17 @@ families_for_changed_path() { printf '%s\n' live-harness-optin printf '%s\n' afk ;; + bin/fm-startup-memory-budget.sh|bin/fm-startup-memory-budget-lib.sh) + printf '%s\n' secondmate + printf '%s\n' session-bootstrap + ;; bin/fm-secondmate*|bin/fm-home-seed.sh|bin/fm-backlog-handoff.sh|\ bin/fm-config-inherit-lib.sh|bin/fm-config-push.sh|bin/fm-shared*) printf '%s\n' secondmate ;; bin/fm-session-start.sh|bin/fm-bootstrap.sh|bin/fm-fleet-sync.sh|\ bin/fm-sessionstart-nudge.sh|bin/fm-tangle*|bin/fm-update.sh|\ - bin/fm-gate-refuse*|bin/fm-lock*) + bin/fm-gate-refuse*|bin/fm-lock*|bin/fm-quota-axi-lib.sh) printf '%s\n' session-bootstrap ;; bin/fm-pr-*|bin/fm-merge-local.sh|bin/fm-reap-browsers.sh|bin/fm-teardown.sh|\ @@ -680,10 +687,15 @@ families_for_changed_path() { bin/fm-brief.sh|bin/fm-ensure-agents-md.sh|bin/fm-crew-state.sh|\ bin/fm-decision-hold.sh|bin/fm-supervision*|bin/fm-transition-lib.sh|\ bin/fm-tmux-lib.sh|bin/fm-marker-lib.sh|bin/fm-operational-input.sh|bin/fm-tasks-axi-lib.sh|\ + bin/fm-vendor-auth-probe.sh|\ bin/fm-primary-scope-lib.sh|bin/fm-project-mode.sh|bin/fm-promote.sh|\ bin/fm-ff-lib.sh|bin/fm-gotmp*|bin/*pretool*) printf '%s\n' pure-contract-unit ;; + .agents/skills/quota-array-dispatch/SKILL.md) + printf '%s\n' pure-contract-unit + printf '%s\n' live-harness-optin + ;; .agents/skills/*/SKILL.md) printf '%s\n' pure-contract-unit ;; @@ -703,9 +715,26 @@ families_for_changed_path() { families_for_test_reference "$(basename "$path")" \ || printf '%s\n' "__unmapped__:$path" ;; + tests/fixtures/*/*) + # A fixture belongs to whichever suite reads its directory, found by the + # same reference scan used for shared helpers. Keyed on the directory + # rather than the file so adding a fixture selects the same suite. + # A removed fixture directory has no consuming suite left to select. + fixture_ref=${path#tests/fixtures/} + fixture_ref=${fixture_ref%%/*} + if [ -d "tests/fixtures/$fixture_ref" ]; then + families_for_test_reference "fixtures/$fixture_ref" \ + || printf '%s\n' "__unmapped__:$path" + fi + ;; bin/*) - families_for_test_reference "$(basename "$path")" \ - || printf '%s\n' "__unmapped__:$path" + # A deleted script has no consuming suite left to select, the same rule + # the fixture case above applies. Refusing on its absent mapping would + # make every retirement branch unable to select its changed tests. + if [ -e "$path" ]; then + families_for_test_reference "$(basename "$path")" \ + || printf '%s\n' "__unmapped__:$path" + fi ;; tests/*) printf '%s\n' "__unmapped__:$path" diff --git a/bin/fm-tmux-lib.sh b/bin/fm-tmux-lib.sh index cf8c3f7fa5e..e8284ba1e01 100755 --- a/bin/fm-tmux-lib.sh +++ b/bin/fm-tmux-lib.sh @@ -46,8 +46,14 @@ # tmux adapter does not paper over a herdr-specific shape. # # Overrides: FM_COMPOSER_IDLE_RE matches an empty composer after ghost and -# structural border stripping. FM_BUSY_REGEX globally overrides harness-scoped -# busy-footer matching (mirrors fm-watch.sh / the daemon). +# structural border stripping. FM_BUSY_REGEX overrides the rendered busy-footer +# matching used here. +# +# NOT a task-state source: task busy state is owned by bin/fm-busy-lib.sh's +# semantic contract. The matching below serves only delivery guards: the submit +# acknowledgement and the away-mode supervisor-pane busy guard. Both ask about +# the pane receiving input, not the state of a recorded worker task. Matching +# stays harness-scoped so one harness's output cannot make another read busy. # # All functions are `set -u` and `set -e` safe (guarded tmux calls, explicit # returns) so they can be sourced into either context. @@ -60,7 +66,7 @@ # shellcheck source=bin/fm-composer-lib.sh . "$(dirname -- "${BASH_SOURCE[0]}")/fm-composer-lib.sh" -# Busy footers per harness (mirror fm-watch.sh). claude/codex: "esc to +# Delivery-only rendered busy footers per harness. claude/codex: "esc to # interrupt"; opencode: "esc interrupt"; pi: "Working..."; grok: "Ctrl+c:cancel". # Claude's current spinner has a rotating glyph and word, but every active-turn # line has an ellipsis followed by a parenthesized elapsed duration. Keep this diff --git a/bin/fm-update.sh b/bin/fm-update.sh index c3b0e674f77..59717839bd6 100755 --- a/bin/fm-update.sh +++ b/bin/fm-update.sh @@ -70,13 +70,17 @@ sweep_live_secondmate_metas "$STATE" origin no # Registry backstop: a secondmate registered in data/secondmates.md but without # a live meta (e.g. between restarts) is still its persistent on-disk home. if [ -f "$SECONDMATES_MD" ]; then - while IFS= read -r line; do + while IFS= read -r line || [ -n "$line" ]; do case "$line" in "- "*) ;; *) continue ;; esac - id=$(printf '%s\n' "$line" | sed -n 's/^- \([^ ][^ ]*\) - .*/\1/p') - home=$(printf '%s\n' "$line" | sed -n 's/.*(home:[[:space:]]*\([^;]*\);.*/\1/p' | sed 's/[[:space:]]*$//') + if ! secondmate_registry_parse_line "$line"; then + echo "secondmate registry: skipped malformed entry: $line" >&2 + continue + fi + id=$SECONDMATE_REGISTRY_ID + home=$SECONDMATE_REGISTRY_HOME process_secondmate "$id" "$home" "" origin no done < "$SECONDMATES_MD" fi diff --git a/bin/fm-vendor-auth-probe.sh b/bin/fm-vendor-auth-probe.sh new file mode 100755 index 00000000000..1593fe7ae4b --- /dev/null +++ b/bin/fm-vendor-auth-probe.sh @@ -0,0 +1,200 @@ +#!/usr/bin/env bash +# fm-vendor-auth-probe.sh - one hard-bounded, non-destructive authentication +# probe of a named vendor CLI. +# +# This script collects a FACT and renders no verdict. It takes no harness, model, +# or provider, reads no quota, and never decides whether a dispatch candidate is +# eligible. The dispatching first mate owns that judgment from `quota-axi`'s data +# plus each harness's authoritative model catalog; the decision procedure is +# owned once by .agents/skills/quota-array-dispatch/SKILL.md. +# +# Why it exists rather than the agent running the vendor CLI itself: the +# captain's 2026-07-30 `firstmate-grok-auth-preflight` decision approved exactly +# one bounded, non-interactive probe, and that safety envelope must not depend on +# agent memory. It is enforced here deterministically: +# - the argv is fixed in this file and never composed from input, so no caller +# can turn the probe into a login, logout, or interactive TUI launch; +# - stdin is closed, so caller input can never reach the vendor CLI; +# - a hard positive timeout bounds every command, so a hung CLI cannot wedge an +# intake; +# - raw vendor output is classified here and never printed, logged, or passed +# in an argument. +# +# The probe registry is a fixed-argv safety allowlist, not a routing table. It +# carries no harness, model, provider, credential-store, or provider-family +# relationship, and asking for a probe is always the caller's own explicit +# decision. A probe is registered only after its non-destructive discovery +# command and its output discriminators are verified first-hand and recorded in +# docs/verification/dispatch-auth.md. +# +# Registered probes: +# grok `grok models` - the standalone Grok Build CLI. Verified on grok +# 0.2.117: the command exits 0 in BOTH the authenticated and the +# unauthenticated case, so only the literal first stdout line +# discriminates and the exit status is never a verdict. +# +# Output: exactly one sanitized `key=value` line on stdout. No token, refresh +# token, header, path, length, prefix, hash, or raw vendor output is ever +# printed, logged, or passed in an argument. +# +# probe= the requested probe name +# status= authenticated | unauthenticated | indeterminate | +# timeout | unavailable +# version= the probed CLI's version, or none +# versionVerified= yes | no | none - whether the running CLI matches the +# version whose discriminator strings were verified +# +# `status` is evidence, never eligibility. Only `authenticated` and +# `unauthenticated` are ground truth. `indeterminate`, `timeout`, and +# `unavailable` mean the probe established nothing and must never be read as +# either outcome; unrecognized output is `indeterminate`, never authenticated. +# +# Exit status: 0 whenever the line is printed, 2 on a usage error. The exit +# status deliberately does not encode the probe result, because this script +# renders no verdict for a caller to branch on. +# +# Usage: +# fm-vendor-auth-probe.sh <probe> +# +# Environment: +# FM_VENDOR_AUTH_PROBE_TIMEOUT hard per-command bound in seconds; must be a +# positive integer, otherwise the default 20 is +# used. Zero is rejected because `timeout 0` and +# `alarm 0` both mean "no deadline". +set -u + +VERIFIED_GROK_VERSION=0.2.117 + +usage() { + cat <<'EOF' +fm-vendor-auth-probe.sh - one hard-bounded, non-destructive authentication probe +of a named vendor CLI. It collects a fact and renders no verdict: it takes no +harness, model, or provider, reads no quota, and never decides dispatch +eligibility. The dispatching first mate owns that judgment. + +Usage: + fm-vendor-auth-probe.sh <probe> + +Registered probes: + grok `grok models` on the standalone Grok Build CLI + +Prints one sanitized key=value line: probe, status, version, versionVerified. + +status is evidence, never eligibility: + authenticated the vendor CLI reports an authenticated session + unauthenticated the vendor CLI reports no authenticated session + indeterminate output the verified discriminators do not cover + timeout the hard bound was hit + unavailable the vendor CLI is not on PATH +Only authenticated and unauthenticated are ground truth; the other three +establish nothing and must never be read as either outcome. + +The argv is fixed in the script, stdin is closed, and raw vendor output is never +printed. Login, logout, and the interactive TUI are never invoked. + +Exit status: 0 whenever the line is printed, 2 on a usage error. + +Environment: + FM_VENDOR_AUTH_PROBE_TIMEOUT hard per-command bound in seconds (default 20); + a non-positive or non-numeric value is rejected + in favor of the default +EOF +} + +die_usage() { + printf 'fm-vendor-auth-probe: %s\n' "$1" >&2 + printf 'usage: fm-vendor-auth-probe.sh <probe> (registered probes: grok)\n' >&2 + exit 2 +} + +PROBE= +while [ $# -gt 0 ]; do + case "$1" in + -h|--help) usage; exit 0 ;; + -*) die_usage "unknown option: $1" ;; + *) + [ -z "$PROBE" ] || die_usage "only one probe may be requested at a time" + PROBE=$1 + shift + ;; + esac +done + +[ -n "$PROBE" ] || die_usage "a probe name is required" + +# A non-positive bound is not a bound: `timeout 0` and the Perl fallback's +# `alarm 0` both disable the deadline, so a hung vendor CLI would run unbounded. +TIMEOUT=${FM_VENDOR_AUTH_PROBE_TIMEOUT:-20} +case "$TIMEOUT" in + ''|*[!0-9]*|0*) TIMEOUT=20 ;; +esac + +# Bounded execution, mirroring bin/fm-fleet-snapshot.sh's run_timed selection so +# a macOS host without coreutils still gets a hard bound instead of an unbounded +# vendor CLI call. Exit 124 means the bound was hit. +run_timed() { # <seconds> <command...> + local seconds=$1 + shift + if command -v timeout >/dev/null 2>&1; then + timeout "$seconds" "$@" + elif command -v gtimeout >/dev/null 2>&1; then + gtimeout "$seconds" "$@" + elif command -v perl >/dev/null 2>&1; then + perl -e 'my $t = shift; my $pid = fork; die "fork failed" unless defined $pid; if (!$pid) { setpgrp(0, 0); exec @ARGV } local $SIG{ALRM} = sub { kill "TERM", -$pid; select undef, undef, undef, 0.2; kill "KILL", -$pid; exit 124 }; alarm $t; waitpid $pid, 0; exit($? >> 8)' "$seconds" "$@" + else + return 124 + fi +} + +STATUS=unavailable +VERSION=none +VERSION_VERIFIED=none + +emit() { + printf 'probe=%s status=%s version=%s versionVerified=%s\n' \ + "$PROBE" "$STATUS" "$VERSION" "$VERSION_VERIFIED" + exit 0 +} + +# The two argv forms below are literals in this file. Nothing the caller supplies +# reaches the vendor CLI's argv or stdin. +grok_version() { + local output + output=$(run_timed "$TIMEOUT" grok --version 2>/dev/null </dev/null) || { printf 'none\n'; return 0; } + printf '%s\n' "$output" | sed -nE 's/.*[^0-9]([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' | head -n 1 | grep . || printf 'none\n' +} + +probe_grok() { + local output first rc=0 + output=$(run_timed "$TIMEOUT" grok models 2>/dev/null </dev/null) || rc=$? + if [ "$rc" -eq 124 ]; then + printf 'timeout\n' + return 0 + fi + # The exit status is deliberately ignored: grok 0.2.117 exits 0 in both the + # authenticated and unauthenticated cases, so only the first stdout line + # discriminates. Raw output is classified here and never printed. + first=$(printf '%s\n' "$output" | head -n 1) + case "$first" in + "You are logged in with "*) printf 'authenticated\n' ;; + "You are not authenticated."*) printf 'unauthenticated\n' ;; + *) printf 'indeterminate\n' ;; + esac +} + +case "$PROBE" in + grok) + command -v grok >/dev/null 2>&1 || emit + VERSION=$(grok_version) + if [ "$VERSION" = "$VERIFIED_GROK_VERSION" ]; then + VERSION_VERIFIED=yes + else + VERSION_VERIFIED=no + fi + STATUS=$(probe_grok) + emit + ;; + *) + die_usage "no probe is registered for '$PROBE'" + ;; +esac diff --git a/bin/fm-watch.sh b/bin/fm-watch.sh index b8f3c2e437a..b27b452bd6d 100755 --- a/bin/fm-watch.sh +++ b/bin/fm-watch.sh @@ -112,6 +112,8 @@ mkdir -p "$STATE" # cheap when no records exist and never scrapes secondmate conversation. # shellcheck source=bin/fm-pending-reply-lib.sh . "$SCRIPT_DIR/fm-pending-reply-lib.sh" +# shellcheck source=bin/fm-busy-lib.sh +. "$SCRIPT_DIR/fm-busy-lib.sh" WATCH_LOCK="$STATE/.watch.lock" WATCH_PATH="$SCRIPT_DIR/fm-watch.sh" @@ -146,14 +148,9 @@ CHECK_TIMEOUT=${FM_CHECK_TIMEOUT:-30} # seconds allowed per *.check.sh SIGNAL_GRACE=${FM_SIGNAL_GRACE:-30} # seconds to linger after a signal so trailing # signals (a status write, then the same turn's # turn-end hook) coalesce into one wake -# Busy signatures are selected by recorded harness unless FM_BUSY_REGEX globally -# overrides them. -# claude/codex: "esc to interrupt"; opencode: "esc interrupt"; pi: "Working..."; -# grok: "Ctrl+c:cancel". Claude's current spinner signature is matched only for -# a recorded Claude task because an ellipsis followed by elapsed time is not a -# safe shared signature for arbitrary harness output. Kimi's moon-plus-middot -# spinner signature is likewise matched only for a recorded Kimi task. -BUSY_REGEX=${FM_BUSY_REGEX:-'esc (to )?interrupt|Working\.\.\.|Ctrl\+c:cancel'} +# Busy state is decided by the semantic contract in bin/fm-busy-lib.sh, which +# is the single owner of per-harness sources, source attribution, and the one +# remaining rendered-text fallback (Grok only). # Always-on wake triage: most wakes during a long crew validation are benign (a # working: note or turn-end while a pipeline runs, a no-change heartbeat). Rather # than wake firstmate's LLM for each, this watcher classifies every wake in bash @@ -216,29 +213,24 @@ hash_pane() { if command -v md5 >/dev/null 2>&1; then md5 -q; else md5sum | cut -d' ' -f1; fi } -# window_is_busy: 0 (busy) iff the task's harness is actively working. Prefers -# a backend's native semantic busy state (fm_backend_busy_state - herdr's -# agent.get; herdr-addendum "busy state" row, "the first backend where -# fm_session_busy_state gets real semantics"); when the backend reports unknown, -# falls back to the recorded harness's verified pane-tail signature. <tail40> is -# the same bounded capture already read for hashing, so this adds no extra -# backend calls on the regex-fallback path. +# window_is_busy: 0 (busy) iff the task's harness is PROVABLY working, through +# the semantic busy-state contract (bin/fm-busy-lib.sh). Only an exact busy +# verdict returns 0: idle, unknown, and dead all return 1, so a converted +# adapter whose semantic state is missing, malformed, stale, or unverified is +# treated as not-provably-working and surfaces rather than being absorbed. +# <tail40> is the same bounded capture already read for hashing and is +# consumed only by the Grok-scoped fallback inside the contract. window_is_busy() { # <window> <tail40> - local w=$1 tail40=$2 bs harness lines - bs=$(fm_backend_busy_state "$(window_backend "$w")" "$w" 2>/dev/null) - case "$bs" in - busy) return 0 ;; - idle) return 1 ;; - *) - lines=$(printf '%s' "$tail40" | grep -v '^[[:space:]]*$' | tail -12) - harness=$(window_harness "$w") - if [ -n "${FM_BUSY_REGEX:-}" ]; then - printf '%s' "$lines" | grep -qiE "$BUSY_REGEX" - else - printf '%s' "$lines" | fm_busy_lines_match "$harness" - fi - ;; - esac + local w=$1 tail40=$2 task meta verdict + task=$(window_to_task "$w" "$STATE") + meta="$STATE/$task.meta" + if [ -n "$task" ] && [ -f "$meta" ]; then + verdict=$(fm_busy_classify_meta "$meta" "$task" "$STATE" "$tail40") + else + verdict=$(fm_busy_classify "$(window_backend "$w")" "$w" "$(window_harness "$w")" \ + "${task:-unknown}" "$STATE" "$tail40") + fi + [ "${verdict%% *}" = busy ] } window_kind() { @@ -1026,8 +1018,8 @@ EOF # - paused: the crew declared an external wait, or a declared pause or # captain hold is paired with a confidently dead agent, so absorb on # the long PAUSE_RESURFACE_SECS cadence instead of wedge-escalating; - # - none: no running pipeline, idle pane, no busy signature, no declared - # pause - the crew has STOPPED. Surface immediately so firstmate peeks + # - none: no running pipeline, no exact busy verdict, no declared pause. + # Surface immediately so firstmate inspects the inconclusive state # (it may be done via an interactive menu that wrote no done: status, # waiting on a decision, or wedged) instead of leaving the finish to # wait out the timer. diff --git a/bin/fm-x-followup.sh b/bin/fm-x-followup.sh index 603678cfca0..9a51c3883b6 100755 --- a/bin/fm-x-followup.sh +++ b/bin/fm-x-followup.sh @@ -17,6 +17,11 @@ # exit 1, silent -> not linked, or window/cap exhausted (link # pruned) # +# Clear a legacy link without posting: +# fm-x-followup.sh --clear <task-id> +# idempotently removes only the X follow-up metadata for a typed terminal +# outcome. +# # Post (after composing the reply to a file or stdin): # fm-x-followup.sh <task-id> [--image <path>] [--final] --text-file <path> # fm-x-followup.sh <task-id> [--image <path>] [--final] - @@ -65,12 +70,13 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}" . "$SCRIPT_DIR/fm-x-lib.sh" usage() { - echo "usage: fm-x-followup.sh --check <task-id> | <task-id> [--image <path>] [--final] --text-file <path> | <task-id> [--image <path>] [--final] -" >&2 + echo "usage: fm-x-followup.sh --check <task-id> | --clear <task-id> | <task-id> [--image <path>] [--final] --text-file <path> | <task-id> [--image <path>] [--final] -" >&2 } help() { cat <<'EOF' usage: fm-x-followup.sh --check <task-id> + fm-x-followup.sh --clear <task-id> fm-x-followup.sh <task-id> [--image <path>] [--final] --text-file <path> fm-x-followup.sh <task-id> [--image <path>] [--final] - @@ -79,6 +85,7 @@ X-mode-linked task and manage the link's follow-up counter. Options: --check Print the request_id when a follow-up is due. + --clear Clear only the X follow-up link; never post. --image <path> Attach one local image file; threaded replies attach it to the opener tweet or message. --final Clear the link after this post regardless of the remaining count. --text-file <path> @@ -108,7 +115,11 @@ case "${1:-}" in esac FINAL=0 -if [ "${1:-}" = --check ]; then +if [ "${1:-}" = --clear ]; then + MODE=clear + ID=${2:-} + if [ -z "$ID" ] || [ "$#" -gt 2 ]; then usage; exit 2; fi +elif [ "${1:-}" = --check ]; then MODE=check ID=${2:-} if [ -z "$ID" ] || [ "$#" -gt 2 ]; then usage; exit 2; fi @@ -144,6 +155,13 @@ case "$ID" in esac META="$STATE/$ID.meta" +if [ "$MODE" = clear ]; then + fmx_meta_link_clear "$META" \ + || { echo "fm-x-followup: could not clear the link in state/$ID.meta" >&2; exit 1; } + printf '%s\n' "$ID" + exit 0 +fi + RID=$(fmx_meta_get "$META" x_request) TS=$(fmx_meta_get "$META" x_request_ts) COUNT=$(fmx_meta_get "$META" x_followups) diff --git a/bin/fm-x-poll.sh b/bin/fm-x-poll.sh index cab733b8e5d..d4fc7bdf40b 100755 --- a/bin/fm-x-poll.sh +++ b/bin/fm-x-poll.sh @@ -17,6 +17,14 @@ # claim state/x-context/<request_id>.offered.json, and print one compact # line "x-mention <request_id>" (which becomes the watcher wake payload) # an already offered request_id -> print nothing, exit 0 +# a new set of unreconciled public-followup terminal results -> print one +# "public-followup ..." line BEFORE the relay call, so a promised final +# reply is surfaced through this same wake path +# +# The public-followup line rides here rather than on a new poll of its own: this +# check only exists in a home that opted into the relay, and it is an O(1) +# directory presence test plus a signature compare, with no tasks-axi call and no +# backlog scan. A home with no pending terminal results pays nothing for it. # The full object is stashed verbatim, so any conversation context the relay # includes (in_reply_to: {author_handle, text}, null for a fresh mention) is # preserved for fmx-respond to handle follow-ups with continuity. The durable @@ -66,13 +74,30 @@ case "$STATE" in FM_STATE_OVERRIDE=$STATE ;; esac -# shellcheck source=bin/fm-x-lib.sh -. "$SCRIPT_DIR/fm-x-lib.sh" +# shellcheck source=bin/fm-public-followup-lib.sh +# Also brings in bin/fm-x-lib.sh, which this script's relay client uses. +. "$SCRIPT_DIR/fm-public-followup-lib.sh" fmx_load_config # Hard no-op when X mode is off: this is what keeps the check shim inert. [ -n "$FMX_TOKEN" ] || exit 0 +# Unreconciled terminal results for a public commitment are actionable even when +# the relay has no new mention, and they outlive any session, so surface them +# first. The signature compare keeps this to one wake per new result set instead +# of one per cycle; bin/fm-public-followup.sh consume clears it. +if fm_pf_has_events "$STATE"; then + PF_ROOT=$(fm_pf_root "$STATE") + PF_SIG=$(fm_pf_events_signature "$STATE" 2>/dev/null) || PF_SIG= + if [ -n "$PF_SIG" ] \ + && [ "$(cat "$PF_ROOT/$FM_PF_SURFACED_BASENAME" 2>/dev/null || true)" != "$PF_SIG" ]; then + if printf '%s\n' "$PF_SIG" \ + | fmx_private_artifact_publish_stdin "$PF_ROOT" "$FM_PF_SURFACED_BASENAME" 600 2>/dev/null; then + printf 'public-followup terminal results are waiting to be reconciled\n' + fi + fi +fi + ERROR_FILE="$STATE/x-poll.error" CLAIM_ERROR_FILE="$STATE/x-poll.claim-error" diff --git a/bin/fm-x-reply.sh b/bin/fm-x-reply.sh index 44e85cb469e..d8d654b545e 100755 --- a/bin/fm-x-reply.sh +++ b/bin/fm-x-reply.sh @@ -5,6 +5,13 @@ # fm-x-reply.sh <request_id> [--image <path>] --text-file <path> # fm-x-reply.sh <request_id> [--image <path>] - # fm-x-reply.sh <request_id> --followup [--image <path>] ... +# fm-x-reply.sh <request_id> ... --receipt-file <path> +# +# --receipt-file <path> writes {request_id, endpoint, chunks, dry_run} to <path> +# after the reply lands, so a caller that must record HOW MANY messages were +# posted (bin/fm-public-followup.sh, building a typed delivery receipt) does not +# have to re-derive the split. Omitted by default and never written on failure, +# so stdout, exit codes, and every existing caller stay unchanged. # # The --text-file / stdin forms exist so a caller never has to inline reply text # (which may be influenced by a public mention) into a shell command, where shell @@ -102,21 +109,35 @@ reply_make_tmp_file() { printf -v "$var_name" '%s' "$file" } +# write_reply_receipt <chunks> <dry-run-0|1>: record what this reply actually +# sent, for a caller that has to build a typed delivery receipt. Only ever called +# on success. A write failure is reported but never changes the exit status: the +# reply already landed, and claiming otherwise would invite a duplicate post. +write_reply_receipt() { + [ -n "$RECEIPT_FILE" ] || return 0 + if ! (umask 077; jq -n --arg r "$REQ" --arg e "$ENDPOINT" --argjson c "$1" --argjson d "$2" \ + '{request_id:$r, endpoint:$e, chunks:$c, dry_run:($d == 1)}' > "$RECEIPT_FILE"); then + echo "fm-x-reply: warning: posted but could not write the receipt to $RECEIPT_FILE" >&2 + fi +} + usage() { - echo "usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] <text> | [--followup] [--image <path>] --text-file <path> | [--followup] [--image <path>] -" >&2 + echo "usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] [--receipt-file <path>] <text> | ... --text-file <path> | ... -" >&2 } help() { cat <<'EOF' -usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] <text> - fm-x-reply.sh <request_id> [--followup] [--image <path>] --text-file <path> - fm-x-reply.sh <request_id> [--followup] [--image <path>] - +usage: fm-x-reply.sh <request_id> [--followup] [--image <path>] [--receipt-file <path>] <text> + fm-x-reply.sh <request_id> [--followup] [--image <path>] [--receipt-file <path>] --text-file <path> + fm-x-reply.sh <request_id> [--followup] [--image <path>] [--receipt-file <path>] - Post a public-safe X-mode answer to the relay, or a completion follow-up with --followup. Options: --followup POST to /connector/followup instead of /connector/answer. --image <path> Attach one local image file; threaded replies attach it to the opener tweet or message. + --receipt-file <path> + After a successful reply, write {request_id, endpoint, chunks, dry_run} to <path>. --text-file <path> Read reply text from a file instead of the command line. - Read reply text from stdin. @@ -141,6 +162,7 @@ shift # the answer path always has. FOLLOWUP=0 IMAGE_PATH= +RECEIPT_FILE= ARGS=() while [ "$#" -gt 0 ]; do case "$1" in @@ -154,6 +176,15 @@ while [ "$#" -gt 0 ]; do fi IMAGE_PATH=$1 ;; + --receipt-file) + shift + if [ "$#" -lt 1 ] || [ -z "$1" ]; then + echo "fm-x-reply: missing --receipt-file path" >&2 + usage + exit 2 + fi + RECEIPT_FILE=$1 + ;; *) ARGS+=("$1") ;; esac shift @@ -306,6 +337,7 @@ if [ -n "$FMX_DRY" ]; then "$N" "$FMX_RELAY" "$ENDPOINT" "$REQ" >&2 printf '%s' "$CHUNKS" | jq -r '.[]' | while IFS= read -r __chunk; do printf ' %s\n' "$__chunk" >&2; done fi + write_reply_receipt "$N" 1 printf '%s\n' "$REQ" exit 0 fi @@ -331,6 +363,7 @@ case "$code" in fmx_context_registry_set "$STATE" "$REQ" "$REQ_PLATFORM" "$REQ_EXPLICIT_MAX" 1 2>/dev/null \ || echo "fm-x-reply: warning: could not retain reply context for $REQ" >&2 fi + write_reply_receipt "$N" 0 printf '%s\n' "$REQ" ;; 409) diff --git a/docs/architecture.md b/docs/architecture.md index 0e1a7089392..e2e3df07393 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -17,12 +17,12 @@ When a canonical validated PR poll returns exactly `merged`, the watcher appends The receipt makes retirement safely retryable across restarts: fixed-path recovery revalidates the same evidence, removes the runnable check first, removes its registration and data sidecars, removes the receipt last, and preserves task metadata including `pr=` and `pr_head=`. A concurrent replacement remains armed, every non-merged or invalid observation remains unchanged, and retirement never performs task or persistent-secondmate cleanup. `bin/fm-pr-lib.sh` owns the receipt format and strict identity mechanics, while `bin/fm-watch.sh` owns queue-before-retirement ordering. -No-verb wakes, such as `working:` notes and bare turn-ended signals, are benign only when `bin/fm-crew-state.sh` reports positive evidence that the crew is still working: an actively running no-mistakes step attributed to that crew's current code or a backend busy signature. +No-verb wakes, such as `working:` notes and bare turn-ended signals, are benign only when `bin/fm-crew-state.sh` reports positive evidence that the crew is still working: an actively running no-mistakes step attributed to that crew's current code, or an exact busy verdict from the semantic busy-state contract. A crew that declares `paused:` for a known external wait is separately absorbed while idle and re-surfaced only on the longer pause cadence, rather than being treated as a possible wedge. For an ordinary crew that has stopped, the normal-mode watcher first surfaces one stale wake, then applies that same cadence to an unchanged `paused:` or durable `captain-held` endpoint only when the backend confidently reports its agent dead. Live or inconclusive liveness remains fail-open at that initial surface, and the secondmate idle-endpoint exemption is unchanged. Its initial normal-mode status signal still surfaces through the no-verb path, while away mode self-handles that routine signal and owns the later recheck. -Fresh stale panes use the same current-state read before trusting the status log, so an active run or busy pane outranks an old captain-relevant status-log line left behind before validation. +Fresh stale panes use the same current-state read before trusting the status log, so an active run or a proven busy worker outranks an old captain-relevant status-log line left behind before validation. No-change heartbeats are also benign. Absorbed wakes advance their suppression markers, log to `state/.watch-triage.log`, and keep the watcher blocking without a queue record or LLM turn. After each drain, `fm-wake-drain.sh` runs the same liveness guard as the supervision scripts, so a lapsed watcher chain surfaces even on a turn that only drains and handles queued wakes. @@ -33,10 +33,10 @@ Crew status files are append-only wake-event logs, not current-state fields. The script header owns the exact run-head ancestry rules. During no-mistakes' `ci` monitor phase, it also reads the ci step log tail because `axi status` reports both "still waiting on checks" and "checks green, waiting on merge" as `ci,running`. The most recent recognized ci log marker wins, so checks-green monitoring reports done while a later re-arm, failed-check, or issue marker returns the crew to working. -Only when no matching run exists does it fall back to the pane busy-signature and then a status-log event whose verb maps to a recognized run-state; a dead pane without a run reports unknown instead of trusting a stale log. +Only when no matching run exists does it consult semantic busy state; exact busy reports working, exact idle permits fallback to a status-log event whose verb maps to a recognized run-state, and unknown or a dead pane stays unknown instead of trusting a stale log. Decision-only events such as `resolved` never become current state or leak their prose into the current-state detail. In that status-log fallback, a declared external wait reports the distinct `paused` state with its reason. -For herdr, that pane fallback trusts a native `busy` verdict outright, but corroborates native `idle` or unknown verdicts against the recorded harness's rendered busy signature before deciding the crew is not working. +The semantic branch reports working only on an exact busy verdict and names the source that produced it; an unknown verdict never becomes working, never permits the status-log fallback, and never becomes a silent idle. For whole-fleet read-only review, `bin/fm-fleet-snapshot.sh --json` emits schema `fm-fleet-snapshot.v1` from the backlog, task metadata, current crew state, endpoint probes, PR/report pointers, scout reports, bounded current summaries from registered secondmate homes, and secondmate return-channel guidance. `bin/fm-fleet-view.sh` renders that snapshot as Markdown for humans, while `bin/fm-bearings-snapshot.sh` provides the bounded bearings projection, so both views consume one structured contract instead of reparsing raw fleet files. The script header owns the exact JSON schema. @@ -87,23 +87,41 @@ Stalled escalation delivery writes `state/.subsuper-inject-wedged` and attempts On an unmarked return, `bin/fm-afk-return.sh` owns ordered shutdown, durable catch-up evidence, and the fail-closed gate that keeps ordinary work behind every live firstmate-actionable blocker. `fm-send.sh` selects a pre-Enter popup-settle for slash commands and for codex `$...` skill invocations using metadata-routed target `harness=` values, then adds its own `FM_SEND_SETTLE` pause after successful text sends so immediate peeks catch the receiving turn starting; the sub-supervisor uses only the shared submit core and does not pay that post-submit pause. +## Busy state is semantic, per adapter + +`bin/fm-busy-lib.sh` is the single owner of what "this worker is busy" means, and `bin/fm-busy-event.sh` is the only writer of the per-task records it reads. +Every classification returns a verdict of busy, idle, unknown, or dead together with the source that produced it, so a consumer or a diagnostic can never confuse semantic state with a fallback. + +Each converted adapter reports its own turn lifecycle through a machine-readable contract the vendor already exposes, rather than through rendered footer text: Pi and pi-signed through the Firstmate-owned extension's `agent_start` and `agent_settled` confirmed by `ctx.isIdle()`, OpenCode through its plugin's semantic `session.status`, and Claude through owned `UserPromptSubmit`, `Stop`, `StopFailure`, and `SessionEnd` hooks. +Kimi behind Pi inherits Pi's lifecycle. +Codex and standalone Kimi classify unknown behind explicit probes until a semantic source is live-verified for them, and Grok keeps one clearly isolated rendered-tail fallback that can only ever classify a Grok task. + +Missing, malformed, stale, untrusted, or unverified semantic state is unknown, never idle, and unknown is never promoted to busy either. +Ordinary task-state consumers act only on an exact busy verdict, so an unreadable worker surfaces for a closer look instead of being absorbed as still-working or written off as finished. +Endpoint death is the only process-level override and yields dead; child processes, CPU, process sleep state, and marker modification times are not state signals. +`state/<id>.turn-ended` files remain wake notifications, not current state. + +Each record is bound to an incarnation token minted when the task's wiring is armed, so an event from a superseded incarnation is rejected rather than applied, and a record left behind by one classifies unknown. +Three rendered-text readers deliberately remain outside this contract because they answer delivery questions: the submit acknowledgement and away-mode supervisor-pane busy guard in `bin/fm-tmux-lib.sh`, and the secondmate delivery-confirmation observation in `bin/fm-pending-reply-lib.sh`. +All are harness-scoped rather than a global pattern union, and none is a recorded worker state source. + ## Runtime session backends The runtime backend is the session-provider layer below firstmate's scripts. It owns task endpoint creation, bounded capture, text/key sends, current-path reads for spawn-time worktree discovery when the backend does not create the worktree itself, live-window fallback lookup, agent-process liveness probes where verified, and endpoint teardown. `bin/fm-backend.sh` centralizes backend selection, `state/<id>.meta` helpers, current-schema cleanup validation, authenticated legacy-record migration, selector resolution, and operation dispatch; `bin/backends/tmux.sh` is the verified reference adapter ([`docs/tmux-backend.md`](tmux-backend.md)), and `bin/backends/herdr.sh` (P2), `bin/backends/zellij.sh` (P3), `bin/backends/orca.sh` (P4), and `bin/backends/cmux.sh` (P5) are experimental task-spawn adapters. -New spawns select a backend from `--backend`, then `FM_BACKEND`, then local `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, or cmux runtime signals, then default `tmux`. +[`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns new-spawn backend selection precedence and authorization. Runtime auto-detection is innermost-first: `$TMUX` wins over `HERDR_ENV=1`, which wins over cmux's primary `CMUX_WORKSPACE_ID` marker and documented fallback signals; auto-detected herdr or cmux prints a one-time opt-out notice, auto-detected tmux stays silent, and zellij and orca are never auto-detected (only explicit selection). Unknown backend names fail loudly. For compatibility, default tmux tasks do not write `backend=tmux`; every reader treats a missing `backend=` field as `tmux`. -`fm-watch.sh` polls each window's backend for a busy state: tmux, zellij, orca, and cmux have no native primitive and always report unknown, so their pane-tail fallback matches only the recorded harness's verified signature; herdr's `agent.get` semantic state (working/idle/done/blocked) is consulted first for stale detection, with unknown native states using the same harness-scoped fallback. -This scope prevents cross-harness false positives such as Kimi's rotating idle tip `ctrl+c: cancel` borrowing Grok's busy token, and keeps Claude's broader elapsed-spinner shape from matching ordinary output in other panes. -Unknown supplied harnesses match no default signature, while callers that have no harness metadata retain the historical combined-pattern compatibility fallback. -That poll loop is the default event source for backends with no native push events, so this stays an extraction of the abstraction rather than a watcher rewrite. +`fm-watch.sh` decides each window's busy state through the semantic contract above rather than by polling the backend for rendered text. +Herdr's native `agent.get` verdict still participates, but only as evidence of activity: a native `busy` is accepted when the task has no record of its own, while a native `idle` is not, because `agent.get` reports generation state and reads idle while a worker blocks on its own long-running foreground tool call. +tmux, zellij, orca, and cmux expose no native busy primitive at all, so a task on those backends is classified purely from its adapter's own lifecycle record. +That poll loop is still the default event source for backends with no native push events, so this stays an extraction of the abstraction rather than a watcher rewrite. For capable Herdr sessions, the same watcher replaces its terminal sleep with a bounded native event wait that immediately surfaces `blocked`; [Push events and polling fallback](herdr-backend.md#push-events-and-polling-fallback) owns the current mechanism and capability gates, while [runtime backend verification](verification/runtime-backends.md#native-blocked-event) owns the active evidence. The deeper session-start agent-process liveness probe is separate from that busy-state poll: tmux and Herdr have verified classifiers for secondmate recovery, Zellij remains unverified, and Orca and cmux do not support secondmate spawns. Herdr is experimental and can be selected explicitly or by runtime auto-detection: Treehouse remains its worktree provider, [`herdr-backend.md`](herdr-backend.md) owns current setup and safety limits, and [`verification/runtime-backends.md`](verification/runtime-backends.md#herdr) owns active empirical evidence. -Herdr's durable default container shape is workspace-per-home plus tab-per-task: the primary home uses workspace label `firstmate`, secondmate homes use `2ndmate-<secondmate-id>`, and recovery/list-live scopes to the current `FM_HOME`'s workspace. +Herdr uses one tab per task; [Watching and task containers](herdr-backend.md#watching-and-task-containers) owns launcher-bound workspace placement, the label-only fallback, and recovery scope. Its optional default-off presentation projection may place one clean new task in a disposable workspace without changing endpoint authority or lifecycle ownership; [Optional presentation spaces](herdr-backend.md#optional-presentation-spaces) owns that conditional design and its narrow home-local restored-shell cleanup at locked session start. Zellij is experimental and selected only explicitly: Treehouse remains its worktree provider, [`zellij-backend.md`](zellij-backend.md) owns current setup and limits, and [`verification/runtime-backends.md`](verification/runtime-backends.md#zellij) owns active empirical evidence. Zellij's container shape is simpler than herdr's: one shared `firstmate` session, one tab per task, with no per-home workspace split; visible tab titles are scoped by the active home label plus a short hash of the resolved `FM_ROOT` path. @@ -158,7 +176,7 @@ That keeps spawn launch compatible across the [verified harness set](configurati `fm-home-seed.sh` provisions the isolated home, clones the listed PR-based projects into it, initializes newly cloned `no-mistakes` projects, copies the charter to `data/charter.md`, and `fm-spawn.sh --secondmate` launches it through the same session-provider and status-file path as any direct report. For a domain whose subject is the firstmate repo itself, a deliberate `--no-projects` seed creates a project-less home whose crews take pooled worktrees of that repo instead of separate clones. The signal cannot be mixed with project names or omitted accidentally, and a populated home cannot be converted in place; the full seed contract is in [configuration.md](configuration.md#secondmate-routes-datasecondmatesmd). -On the herdr backend, a secondmate launch lands in that secondmate home's labeled workspace, and crewmates spawned from that home land in the same workspace. +Herdr secondmate and child placement follows the launcher-binding contract in [Watching and task containers](herdr-backend.md#watching-and-task-containers). When seeded with `-`, the home is a durable treehouse lease under the secondmate id, so it survives with no live process and is not recycled by later `treehouse get` or pruning. Retirement or seed rollback returns the leased home; normal restart/recovery keeps it leased. If returning the lease fails during teardown, firstmate leaves the route and home intact instead of hiding a still-held lease. @@ -215,7 +233,7 @@ When a reply has a real visual artifact, `--image <path>` attaches one local PNG Actionable reversible requests run through firstmate's normal intake, backlog, dispatch, investigation, or ship lifecycle. Work that completes in the answering turn gets one outcome reply. Work that spawns a longer-running task gets an acknowledgement reply first; `bin/fm-x-link.sh` records `x_request=`, `x_request_ts=`, `x_followups=0`, and optional reply-platform context in that task's `state/<id>.meta`, while durable per-request context preserves the original platform and budget independently of task links and inbox cleanup. -Later milestone and completion wakes use `bin/fm-x-followup.sh` to post up to three public-safe follow-ups through the relay's `connector/followup` endpoint, ending with a `--final` one that always clears the link. +Later milestone wakes use `bin/fm-x-followup.sh` to post up to three public-safe follow-ups through the relay's `connector/followup` endpoint, ending with a `--final` one for ordinary X-linked work. A typed promised-final commitment owns its terminal reply through `bin/fm-public-followup.sh`; after its receipt is validated, `bin/fm-x-followup.sh --clear <task-id>` removes any legacy link without posting another reply. The [X mode configuration reference](configuration.md#x-mode-env) owns the exact context retention, platform-resolution, and fail-safe posting contract. If recovery relinks the same relay request onto a successor task, `fm-x-link.sh --carry-count <n> --carry-ts <epoch> --carry-platform <x|discord> --carry-max <n>` preserves the consumed follow-up count, original 7-day window, and reply split budget instead of granting a fresh local budget or falling back to the wrong platform. The follow-up helper forwards `--image <path>` to the same reply client when a follow-up needs an image. @@ -228,6 +246,18 @@ For preview testing, `FMX_DRY_RUN` makes `fm-x-reply.sh` and `fm-x-dismiss.sh` s Attached images are recorded as compact `{media_type, bytes, source_path}` metadata in dry-run instead of base64 bytes. X mode remains layered on top of the existing check mechanism without changing its request-handling behavior. +A promised *final* public reply is a stronger commitment than a milestone follow-up, because forgetting it is publicly visible. +It is therefore not carried in conversation memory at all: intake turns it into a typed `kind=public-followup` obligation owned by `tasks-axi public-followup`, and every later step reads that obligation from disk. +The mechanism boundary is deliberately narrow. +`tasks-axi` owns the obligation state machine and is the only thing that validates a terminal result's source home, work id, generation, schema, outcome, and deliverables. +`state/x-context/` remains the only owner of the private full request context. +`bin/fm-x-reply.sh` remains the only thing that posts. +`bin/fm-public-followup.sh` composes those three and adds nothing of its own beyond the activation gate, a private terminal-event inbox, and the idempotent delivery sequence. +Work routed to another home reports a *typed* terminal result through `bin/fm-public-followup-emit.sh`; firstmate never recovers the source home, work id, outcome, or deliverables by parsing a free-form `done:` sentence, and the child never learns the thread. +Because a terminal event's id is derived from its identity tuple rather than generated, duplicate reports and restart replay converge without coordination. +Reconciliation rides the existing relay poll and the session-start digest instead of a new watcher, daemon, or timer, and both are gated on the same `.env` activation contract so a home that never opted into the relay executes none of it. +The [X mode configuration reference](configuration.md#promised-public-replies-statepublic-followup) owns the operator-facing contract, and the `fmx-respond` skill owns the procedure. + ## Project memory belongs to projects Durable project-intrinsic agent knowledge lives in each project's committed `AGENTS.md`, with `CLAUDE.md` as a symlink. diff --git a/docs/calm-mode-feasibility.md b/docs/calm-mode-feasibility.md index 6ac60599ec8..8a40a2f9a43 100644 --- a/docs/calm-mode-feasibility.md +++ b/docs/calm-mode-feasibility.md @@ -5,8 +5,9 @@ This document owns the version-scoped feasibility evidence, Pi transcript taxono ## Required extension surface -A qualifying implementation must auto-load from the trusted project, persist the toggle choice for the effective Firstmate home across Pi session starts and resumes, keep Pi's built-in working activity visible, emit no Calm status row, redraw already-rendered controllable rows, remove supported hidden rows without gaps, restore ordinary rendering, and leave delivery, tool execution, model context, session storage, export and share operation, diagnostics, and expansion state unchanged. -The governing presentation policy allows genuine original user prompts, genuine user-facing assistant text, and Pi's native working activity. +A qualifying implementation must auto-load from the trusted project, persist the toggle choice for the effective Firstmate home across Pi session starts and resumes, keep working activity visible, emit no Calm status row, redraw already-rendered controllable rows, remove supported hidden rows without gaps, restore ordinary rendering, and leave delivery, tool execution, model context, session storage, export and share operation, diagnostics, and expansion state unchanged. +The governing presentation policy allows genuine original user prompts, genuine user-facing assistant text, and working activity. +Working activity may be presented through Pi's stock row or through a supported Calm-owned widget, but Calm must leave the stock row untouched whenever Calm is off. Changing persisted context to remove hidden content, filtering provider context, patching installed harness code, or claiming coverage outside a supported renderer does not satisfy that boundary. ## Compatibility evidence @@ -134,6 +135,35 @@ An adjacent two-notification run retained the same two-row neighboring-assistant Calm off, an absent Calm preference, and an absent Calm extension retained ordinary rows. The current exact marker and the narrow bare-U+2063 `Supervisor escalate (` compatibility shape hid under Calm, while quoted markers, ASCII `FIRSTMATE_OP:` without U+2063, ordinary text before the current marker, unrelated text after U+2063, and image-bearing input remained visible. +## Calm working presentation + +Calm replaces Pi's stock working row with a small animated boat while Calm is on and one logical agent run is active. +This path uses only public extension API and patches nothing: `ExtensionUIContext.setWorkingVisible(false)` hides the stock row, and `setWidget()` installs a temporary component factory above the editor. +Pi's documented custom working-indicator frames are static and width-blind, so they cannot own responsive geometry; a widget component receives `render(width)` and can. + +`.pi/extensions/fm-calm.ts` remains the sole owner of the presentation choice and the only caller of `setWorkingVisible()`, while `.pi/extensions/lib/fm-calm-working-ship.ts` owns the sprite geometry, the bounce track, and the widget. +Visibility follows `agent_start` through `agent_settled` rather than turns or tool calls. +Pi emits `agent_settled` from a `finally` block once a run will not continue automatically, so retries, automatic continuations, queued follow-ups, and compaction inside one run never remove the boat, while settle, abort, and failure all reach the same cleanup. +Repeated `agent_start` events inside one run are idempotent, and Pi disposes the previous component before installing a replacement under the same key and when it clears extension widgets, so the frame timer cannot duplicate or outlive the widget. +Pi's above-editor widget container reserves one spacer row whether or not a widget is present, so removing the boat leaves no residual blank row. + +The sprite is two rows when the usable width admits the complete hull: a two-cell mainsail centered over a symmetric `\__/` hull that replaces water on its row rather than adding a third row. +The sail is directional because a mainsail extends aft of the mast, so it renders `<|` while travelling right and `|>` while travelling left. +Direction reverses the moment the boat lands on an endpoint, so the endpoint frame itself already shows the new heading and no frame at or after a bounce shows the previous sail. +The water row fills the complete supplied width, the track is recomputed and clamped from that width on every frame so a resize cannot wrap or strand the boat offscreen, and widths too narrow for the hull fall back to a deterministic single row. + +One scheduler drives two logically independent clocks. +Every tick advances a bounded fixed-cell water phase, and only every fourth tick moves the boat, so at a 220ms tick the water ripples several times between boat steps and the boat travels one column every 880ms. +Ticks rather than wall-clock timestamps drive every state change, so tests seek animation time exactly, and disposing the widget stops both clocks together. +Water phases are single-column ASCII, so advancing them never changes visible width, adds a row, or moves the hull column. + +Colors are standard ANSI foreground codes rather than theme lookups: blue for every water cell and yellow for the complete boat, with no bright variant, 256-color, or RGB escape. +Each colored run is closed with a default-foreground reset so styling cannot bleed into the sail row's padding, neighbouring UI, or a later frame, and geometry is always computed from visible cells rather than escape bytes. + +The presentation is TUI-only and visual-only. +It adds no session entry, transcript row, model context, or export or share content, and its widget takes no keyboard input, so editor focus and Escape abort are unchanged. +Compaction and retry loaders remain stock because Pi exposes no supported replacement for them. + ## Central visibility and input policy `.pi/extensions/lib/fm-calm-visibility.ts` owns only the allowlist-style transcript presentation policy. @@ -173,7 +203,7 @@ The test fixture enumerates every class below through the centralized policy, an | `custom-entry` | `CustomEntryComponent` with a registered renderer | Legacy Calm presentation entries rebuild to zero children without a residual spacer and restore through ordinary expansion redraw when mounted; arbitrary extension entries remain an unsupported boundary. | | `compaction-summary` | `CompactionSummaryMessageComponent` | Unsupported boundary; remains visible. | | `branch-summary` | `BranchSummaryMessageComponent` | Unsupported boundary; remains visible. | -| `working-status` | `WorkingStatusIndicator` | Visible through Pi's unchanged built-in row while Calm is active. | +| `working-status` | `WorkingStatusIndicator`, or the Calm working-ship widget while Calm is active | Always visible. Calm off leaves Pi's stock row untouched; Calm on hides that row for the duration of one logical agent run and renders the working ship instead. | | `command-status` | Interactive command result and status rows | Calm emits no enable notice, but generic Pi command rows remain an unsupported boundary. | | `system-notice` | `showStatus`, `showError`, compaction, retry, and startup warning rows | Unsupported boundary; remains visible. | | `cache-notice` | Non-persisted cache-miss `Text` row | Unsupported boundary; remains visible. | @@ -220,12 +250,12 @@ Only Pi's Calm presentation implementation changed; every producer and non-Pi tr ## Regression coverage `tests/fm-calm-pi-extension.test.sh` compares wrapped and stock renderers, verifies all seven built-ins plus `fm_watch_arm_pi`, exercises redraw of already-rendered tool, thinking, current operational-user, and legacy synthetic rows, and covers every policy class. -It covers persisted preference restoration across every session-start reason and a real restart, proves Pi's native `Working...` row through a delayed deterministic provider, asserts no Calm status row, verifies operational messages remain exact ordinary user-role session entries and complete exports, and drives genuine 100 by 44, 160 by 36, and 180 by 44 terminal fixtures. +It covers persisted preference restoration across every session-start reason and a real restart, proves the working-ship presentation and Calm-off stock `Working...` row through a delayed deterministic provider, asserts no Calm status row, verifies operational messages remain exact ordinary user-role session entries and complete exports, and drives genuine 100 by 44, 160 by 36, and 180 by 44 terminal fixtures. A native deterministic `/skill:ahoy` turn produces thinking, tool-call, and tool-result blocks, asserts that the collapsed skill-to-final gap equals the two-row visible-only baseline, expands and re-collapses original thinking, restores Calm-off rendering, verifies persisted hidden history, and repeats the geometry assertion after restart with `terminal.clearOnShrink` explicitly off. The operational provider path covers Calm loaded on, loaded off, default preference, extension absent, exact watcher delivery, narrow bare-marker legacy input, persisted restart replay, a genuine captain prompt, and adjacent notifications coalesced into one intended processing turn. It asserts one persisted and rendered captain answer, exact user-role operational envelopes in order, no replacement custom messages, one processing result, zero operational transcript rows, and the two-row neighboring-assistant geometry for live, adjacent, and restart paths. Quoted current markers, ASCII-only labels, ordinary text before a marker, unrelated U+2063 placement, and image-bearing input remain visible in component and native transcript checks. -`tests/fm-pi-primary-live-e2e.test.sh` also proves the unchanged built-in `Working...` row while Calm is active on the credentialed provider path before continuing its ordinary watcher lifecycle. +`tests/fm-pi-primary-live-e2e.test.sh` also proves the working ship replaces the built-in `Working...` row while Calm is active on the credentialed provider path, and that it clears when the run settles, before continuing its ordinary watcher lifecycle. `tests/fm-pi-primary-types.test.sh` performs strict no-emit TypeScript checking against the installed Pi declarations, currently package version 0.81.1. The relevant commands are: @@ -288,3 +318,110 @@ ok - Pi calm native E2E keeps Working and captain turns visible, hides exact ope $ tests/fm-pi-primary-types.test.sh ok - tracked Pi extensions pass strict no-emit typecheck against Pi 0.81.1 ``` + +## 2026-07-30 Calm working-presentation verification (superseded) + +This record captures the first working-presentation implementation and is retained as pipeline history. +Its same-orientation sail, theme-derived colors, and single-cadence motion were all replaced later the same day; the revision record at the end of this document owns current behavior. + +The working ship was verified against the installed Pi 0.82.0 CLI with a deterministic in-process provider and no credentials. +The globally installed declaration package remained 0.81.1, so the strict typecheck continued to cover that declaration-evidence version while the real CLI exercised 0.82.0. +The real-TUI regression captures two frames at different hull columns, resizes the same running TUI, asserts the reflowed water row equals the new width on a single wave row, types into the editor while the animation runs, aborts with Escape, and then proves Pi's stock `Working...` row returns with Calm off. + +```text +$ pi --version +0.82.0 + +$ tests/fm-calm-pi-extension.test.sh +ok - Pi calm resolves its persistent home independently of Pi's launch directory +ok - Pi calm compatibility evidence never rejects a Pi version for being newer than 0.82.0, and still fails closed on a missing or malformed version +ok - a missing collapsed-thinking presentation API degrades only that Calm adapter with a clear skip reason, while the rest of Calm still registers +ok - missing Pi presentation class exports reach the independent adapter degradation path +ok - Pi calm centralizes transcript visibility, preserves execution/export data, keeps Pi's stock working row visible while no run is active, and persists its choice across session starts +ok - Pi operational follow-up E2E processes exact user-role notifications once while Calm hides current and adjacent rows, Calm off and absent render them, and restart preserves semantics +ok - Pi Calm native /skill:ahoy geometry keeps every collapsed thinking and tool block at zero height while preserving expansion, history, restart, and Calm-off rendering +ok - Pi Calm working ship renders an exact two-row full-width sprite, clamps every resize, bounces at both edges, falls back deterministically when narrow, and installs and removes one timer-owning widget across starts, settle, abort, failure, shutdown, reload, replacement, and Calm toggles +ok - Pi calm native E2E replaces the stock working row with a moving, resize-clamped working ship that clears on abort, keeps captain turns visible, hides exact operational user rows without changing persistence, restores stock rendering Calm-off, survives restart, and preserves export plus Ctrl+O behavior + +$ tests/fm-pi-primary-types.test.sh +ok - tracked Pi extensions pass strict no-emit typecheck against Pi 0.81.1 + +$ bin/fm-lint.sh +fm-lint.sh: ShellCheck 0.11.0 (pinned 0.11.0) + +$ bin/fm-doc-audience-check.sh +fm-doc-audience-check: ok surfaces=57 local_links=160 + +$ bin/fm-test-run.sh --changed --base origin/main +FM_TEST_SUMMARY total=32 failed=0 skipped_gate=7 duration_ms=196009 +FM_TEST_SUMMARY_FAMILY family=live-harness-optin count=7 duration_ms=202 failed=0 +FM_TEST_SUMMARY_FAMILY family=pure-contract-unit count=25 duration_ms=194670 failed=0 +``` + +One rendered frame at 120 columns, with Pi's stock working row hidden and the boat directly above the editor: + +```text + |> +\__/~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` + +The same run after resizing that TUI to 64 columns, showing the waves refilled to the new width on one row with the boat still on screen: + +```text + |> +~~~~~~~~~~~~~~~~~~~~~~~~\__/~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` + +Colors at that time were confirmed from an escape-preserving capture as theme-derived entries; the revision below replaced them with standard ANSI blue and yellow. +Pressing Escape during a run left `Operation aborted` with no boat and no residual blank row, and toggling Calm off restored Pi's stock `⠴ Working...` row on the next run. + +## 2026-07-30 Calm working-presentation revision verification + +The revision replaced the single-cadence, theme-colored, same-orientation sprite with a slower boat over independently animated water, standard ANSI colors, and a directional mainsail. +It was verified against the installed Pi 0.82.0 CLI with a deterministic in-process provider and no credentials. + +```text +$ pi --version +0.82.0 + +$ tests/fm-pi-primary-types.test.sh +ok - tracked Pi extensions pass strict no-emit typecheck against Pi 0.81.1 + +$ bin/fm-lint.sh +fm-lint.sh: ShellCheck 0.11.0 (pinned 0.11.0) + +$ bin/fm-doc-audience-check.sh +fm-doc-audience-check: ok surfaces=57 local_links=163 + +$ bin/fm-test-run.sh --changed --base origin/main +FM_TEST_SUMMARY total=32 failed=0 skipped_gate=7 duration_ms=386738 +FM_TEST_SUMMARY_FAMILY family=live-harness-optin count=7 duration_ms=257 failed=0 +FM_TEST_SUMMARY_FAMILY family=pure-contract-unit count=25 duration_ms=383010 failed=0 +``` + +Real Pi TUI observations from the isolated deterministic trial at 100 columns. +The hull column held steady across consecutive samples while the water pattern shifted, then advanced about one column every 880ms, which separates the two cadences: + +```text +hull_col=12 water=~-~~~-~~~-~\__/~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~ +hull_col=12 water=~~~-~~~-~~~\__/-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~- +hull_col=13 water=~~-~~~-~~~-~\__/~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~~~-~ +hull_col=16 (about 2.6s later) +``` + +An escape-preserving capture confirmed standard ANSI foreground codes only, blue water and yellow boat, with a default-foreground reset closing each run: + +```text +^[[34m~~~-~~~-~~~-~~~^[[33m\__/^[[34m-~~~-~~~-~~~-~~~-... +^[[33m<|^[[39m +``` + +Resizing the same running TUI to 12 columns shortened the track enough to observe both reversals, each already showing the heading it was about to travel: + +```text +left-heading : |> over ~-~~~-~~\__/ +right-heading: <| over \__/~~-~~~-~ +``` + +At 3 columns the sprite fell back to a single exact-width row, `<|~`. +Escape aborted the run leaving `Operation aborted`, no boat, and no stale sprite rows, and the trial exited 0 after deleting its temporary state. diff --git a/docs/calm.md b/docs/calm.md index 8d63b6d0b56..1018b818b93 100644 --- a/docs/calm.md +++ b/docs/calm.md @@ -3,7 +3,16 @@ Calm is a Pi-only conversation presentation toggle. It is off by default, and the last `/calm` choice persists for the effective Firstmate home across Pi session starts and resumes. -While Calm is active, Pi's built-in `Working...` activity remains visible and no separate Calm status row is added. +While Calm is active and an agent run is under way, Calm hides Pi's built-in `Working...` row and shows a small two-row animated boat in its place, and no separate Calm status row is added. +The water fills the usable width in standard ANSI blue and the complete boat is standard ANSI yellow. +The boat is deliberately calm: it moves one column every 880ms, while the water ripples on its own faster cadence so the surface stays alive between boat steps. +Its mainsail is directional, showing `<|` while travelling right and `|>` while travelling left, and it flips on the exact frame the boat turns at either edge. +Every resize reflows the sprite without wrapping, and it disappears when the run settles, aborts, or fails. +Within one Pi session and Calm extension lifetime, the next working period resumes the boat from its last rendered column and travel direction rather than restarting at the left edge. +Hidden elapsed time does not advance the animation, and a resize while hidden clamps the frozen boat to the new width without changing its valid travel direction. +A fresh Pi session or new Calm extension lifetime starts at the normal initial position. +Very narrow terminals fall back to a smaller deterministic sprite. +While Calm is off, Pi's stock working row is left exactly as Pi renders it. Calm hides collapsed thinking labels, the shells for Pi's seven built-in tools, the `fm_watch_arm_pi` tool shell, and canonically classified Firstmate operational user rows. The operational inputs remain ordinary user-role messages, while Pi's transcript layout renders their complete rows at zero height. The session-start nudge remains on its existing non-displayed custom-message path. @@ -26,7 +35,7 @@ If Pi removes one of those seams, Calm logs a diagnostic naming the unavailable [`calm-mode-feasibility.md`](calm-mode-feasibility.md) owns the version-scoped renderer taxonomy and empirical evidence. [`configuration.md`](configuration.md#pi-calm-preference-configcalm) owns the persisted preference file and resolution rules. -`.pi/extensions/lib/fm-calm-visibility.ts` owns the visibility policy, and `.pi/extensions/lib/fm-calm-operational-user-layout.ts` owns the zero-height operational-user row adapter. +`.pi/extensions/lib/fm-calm-visibility.ts` owns the visibility policy, `.pi/extensions/lib/fm-calm-operational-user-layout.ts` owns the zero-height operational-user row adapter, and `.pi/extensions/lib/fm-calm-working-ship.ts` owns the animated working presentation. Regression entry points: diff --git a/docs/cmux-backend.md b/docs/cmux-backend.md index bdf17374b71..93a45ccb742 100644 --- a/docs/cmux-backend.md +++ b/docs/cmux-backend.md @@ -94,7 +94,8 @@ Literal send and Enter are separate calls. Enter, Escape, and Ctrl-C are supported. The composer verifier locates the last bordered composer row and delegates the content decision to `bin/fm-composer-lib.sh`. A bare shell prompt is `unknown`, and a slash-popup placeholder remains `pending`, so only Enter is retried and text is never retyped. -cmux exposes no native generic agent busy signal, so supervision uses the shared capture/hash and busy-regex path. +cmux exposes no native generic agent busy signal, so supervision uses capture/hash polling for screen changes and each harness adapter's semantic lifecycle for worker state. +Grok alone retains its isolated rendered-tail fallback. A task workspace's last surface cannot be closed directly. Cleanup owns the whole workspace and uses `close-workspace`. diff --git a/docs/configuration.md b/docs/configuration.md index feb2b3fa20d..c7e92696ff0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -51,7 +51,7 @@ The file format is unchanged in both modes; tasks-axi and manual edits produce t For spawn-capable adapters, the runtime session-provider backend controls where task windows/endpoints are created, captured, sent to, watched, and killed. `tmux` is the verified reference backend (see [`docs/tmux-backend.md`](tmux-backend.md)); `herdr`, `zellij`, `orca`, and `cmux` are experimental spawn backends (see [`docs/herdr-backend.md`](herdr-backend.md), [`docs/zellij-backend.md`](zellij-backend.md), [`docs/orca-backend.md`](orca-backend.md), and [`docs/cmux-backend.md`](cmux-backend.md)). Treehouse remains the worktree provider for tmux, herdr, zellij, and cmux, since herdr, zellij, and cmux are session providers only; Orca provides both the task worktree and terminal endpoint. -New spawns choose the backend in this order: an explicit `--backend` flag firstmate passes when it spawns a task, then `FM_BACKEND`, then the first non-empty line of local gitignored `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, or cmux runtime signals, then default `tmux`. +New spawns choose the backend in this order: an explicit `--backend` flag that current authority for that exact task alone has authorized (a present captain instruction or the task's own accepted brief; never later-task precedent by analogy), then `FM_BACKEND`, then the first non-empty line of local gitignored `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, or cmux runtime signals, then default `tmux`. If more than one runtime marker is present, detection resolves innermost-first: `$TMUX` is checked before `HERDR_ENV=1`, which is checked before cmux's primary `CMUX_WORKSPACE_ID` marker and its documented fallback signals - tmux or herdr started from inside a cmux terminal is the innermost, currently-executing layer, while cmux itself (a terminal application, not a nestable multiplexer) is always checked last. See [`docs/cmux-backend.md`](cmux-backend.md#runtime-detection) for why cmux can be selected when `CMUX_WORKSPACE_ID` is absent. Auto-detected herdr or cmux prints a stderr notice naming `config/backend` and `--backend tmux` as opt-outs; auto-detected tmux stays silent to preserve existing default behavior. @@ -98,6 +98,7 @@ Orca resolves even an empty legacy `worktree=` from its durable worktree id, app After provenance succeeds, teardown atomically adds the binding, revalidates the current schema, and rechecks any authorized live endpoint at removal. By default, Herdr workspaces are derived from `FM_HOME`: the primary home uses `firstmate`, and a secondmate home marked by `.fm-secondmate-home` uses `2ndmate-<secondmate-id>`. The default-container spawn, list-live, and recovery paths read that label from the active home, so a secondmate's own crewmates stay inside that secondmate home's herdr space. +[`herdr-backend.md`](herdr-backend.md#watching-and-task-containers) owns launcher-bound workspace placement, the label-only fallback, collision handling, and recovery behavior. The optional local `config/herdr-presentation-spaces` presence flag instead enables Herdr's default-off disposable single-task visual projection; [Optional presentation spaces](herdr-backend.md#optional-presentation-spaces) owns its behavior, safety limits, recovery contract, and narrow locked session-start cleanup of exact restored idle-shell children. The flag is default-off and inherited into secondmate homes under the primary-authoritative contract owned by [`secondmate-provisioning`](../.agents/skills/secondmate-provisioning/SKILL.md). For normal herdr operations, `HERDR_SESSION` selects the named session, but destructive test cleanup must not rely on `HERDR_SESSION` alone. @@ -152,11 +153,25 @@ Fleet-local operational facts and gotchas live locally in `data/learnings.md`; i The file is created lazily on first learning and follows the same dated, evidence-backed, curated style as `data/captain.md`: inspect the current file first, then rewrite or prune stale entries instead of appending forever. There is no shared learnings file by captain decision. +## Startup memory budget (config/startup-memory-budget) + +`config/startup-memory-budget` is the primary-authoritative per-home allowance for the startup prompt-memory surface: `data/captain.md`, `data/captain-shared.md`, and `data/learnings.md` together. +The locked mutable bootstrap path materializes its visible default of `7500` estimated tokens in a primary home when the file is absent. +To select another allowance, replace the primary home's file with one valid positive value in the exact format below; the next locked bootstrap convergence or `bin/fm-config-push.sh` propagates it to registered secondmates. +A secondmate does not create an independent default and instead receives the primary value through the inherited-local-material contract in [`secondmate-provisioning`](../.agents/skills/secondmate-provisioning/SKILL.md). +The file must be one positive base-10 integer followed by exactly one newline in a regular, single-linked file beneath a non-symlinked `config/` directory. +Malformed, multi-line, symlinked, hardlinked, special, or otherwise unsafe values are rejected rather than treated as a default. +Use `bin/fm-startup-memory-budget.sh read` to validate and print the effective value, or `bin/fm-startup-memory-budget.sh report` to account for the three files. +The stable local estimate is `ceil(UTF-8 bytes / 3)` per file, a conservative portable approximation rather than a provider-exact tokenizer. +An inherited `data/captain-shared.md` counts in a secondmate's total but remains primary-owned and read-only there. +The internal `/stow` skill curates only the editable local files in that case and reports the primary-owned shared file as a concrete exception if it alone exceeds the budget. +The helper's header owns exact parsing, publication, and report output mechanics. + ## Secondmate routes (data/secondmates.md) Persistent secondmate routes live locally in `data/secondmates.md`. The concise single-line route contract is owned by the [`secondmate-provisioning` skill](../.agents/skills/secondmate-provisioning/SKILL.md#routing-table), including the parser-compatible fields, one-sentence summary requirement, `home:` pointer to the seeded charter, and limit on extra registry prose. -`fm-home-seed.sh validate` refuses duplicate ids, duplicate homes, and nested or overlapping homes. +Use `fm-home-seed.sh validate` to check the complete operational registry contract documented by the command itself. The main first mate routes by reading those scopes with judgment; the project list is provisioning data, not exclusive ownership. Use `fm-home-seed.sh <id> - {<project>...|--no-projects}` to lease a fresh firstmate worktree for the secondmate home. Use the deliberate `--no-projects` signal only for a firstmate-repo domain that needs no separate project clones. @@ -196,7 +211,7 @@ The full cmux home label also includes a short hash of the resolved `FM_ROOT` pa claude, codex, opencode, pi, pi-signed, grok, and kimi are empirically verified for crewmate and secondmate launches; [README requirements](../README.md#requirements) own the set supported for the primary session. New harnesses get verified through a supervised trial task before joining the set. -The verified adapter knowledge - busy signatures, interrupt and exit commands, skill-invocation syntax, and per-harness quirks - lives in [`.agents/skills/harness-adapters/SKILL.md`](../.agents/skills/harness-adapters/SKILL.md). +The verified adapter knowledge - each harness's busy-state source, interrupt and exit commands, skill-invocation syntax, and per-harness quirks - lives in [`.agents/skills/harness-adapters/SKILL.md`](../.agents/skills/harness-adapters/SKILL.md). Launch mechanics, including the verified command templates, live in [`bin/fm-spawn.sh`](../bin/fm-spawn.sh). Enabled primary-session turn-end guard integrations are tracked as repo-level hook files and documented in [`docs/turnend-guard.md`](turnend-guard.md). Kimi remains outside the primary turn-end guard integrations; [`docs/turnend-guard.md`](turnend-guard.md#compatibility-limits) owns its separate captain-approved crew wake hook. @@ -232,7 +247,7 @@ When the file exists, `fm-spawn.sh` enforces that contract by refusing crewmate Batch spawns satisfy the same requirement with a shared `--harness`. Secondmate spawns are exempt and still resolve through `config/secondmate-harness` and its optional model and effort tokens. This section is the single owner of the canonical schema and its per-field semantics. -`AGENTS.md` section 4 owns the always-loaded dispatch intake boundary, and `quota-array-dispatch` owns the pace-aware profile-array selection procedure. +`AGENTS.md` section 4 owns the always-loaded dispatch intake boundary, and `quota-array-dispatch` owns the completion-aware profile-array selection procedure. ```json { @@ -271,7 +286,7 @@ Secondmate homes inherit this file from the primary, so a secondmate's own crewm On session start the first mate detects what its required toolchain is missing or too old and lists each problem with either an exact install command or manual instructions. It installs automatically supported tools only after you say go; manual-only tools remain for you to install from the printed instructions. Required tools come in two parts: a universal toolchain every home needs regardless of backend, and a per-backend delta that follows the runtime backend actually resolved for this home. -The universal toolchain is node, git, gh with GitHub auth via `gh auth login`, no-mistakes v1.31.2 or newer, gh-axi, chrome-devtools-axi, lavish-axi, compatible tasks-axi per "Backlog backend" above, and quota-axi. +The universal toolchain is node, git, gh with GitHub auth via `gh auth login`, no-mistakes v1.31.2 or newer, gh-axi, chrome-devtools-axi, lavish-axi, compatible tasks-axi per "Backlog backend" above, and quota-axi v0.1.16 or newer. This section is the single owner of that universal toolchain list; backend guides' prerequisites point here and add only their backend-specific tools. In that list, no-mistakes runs the validation pipeline, gh-axi, chrome-devtools-axi, and lavish-axi cover GitHub, browser, and rich-review operations, and tasks-axi plus quota-axi back backlog mutations and quota-aware array dispatch. The per-backend delta is required only for the backend resolved from `FM_BACKEND`, then `config/backend`, then runtime auto-detection, then default `tmux`, so a home is never told to install a tool an inactive backend or feature would need. @@ -284,7 +299,8 @@ When `config/crew-dispatch.json` exists, bootstrap also requires `jq` for dispat When X mode is opted in, bootstrap also requires `curl` and `jq` before arming the relay poll shim. `tasks-axi` and `quota-axi` are required bootstrap tools in every profile, the same class as `lavish-axi`. An absent or incompatible `tasks-axi` reports `MISSING: tasks-axi (install: npm install -g tasks-axi)`; when `config/backlog-backend` is not `manual` and compatible `tasks-axi` is on `PATH`, bootstrap stays silent and firstmate uses its verbs for routine backlog mutations, otherwise it hand-edits `data/backlog.md` until installation is approved and completed. -An absent `quota-axi` reports `MISSING: quota-axi (install: npm install -g quota-axi)`; firstmate cannot resolve a profile array until current quota output is available for every candidate. +An absent or too-old `quota-axi` reports `MISSING: quota-axi (install: npm install -g quota-axi)`; firstmate cannot resolve a profile array without a compatible binary. +That floor exists because it is the first build reporting per-credential auth sources, without which a candidate cannot be judged against the authentication surface it actually uses. Bootstrap also reports a `TANGLE:` line when `FM_ROOT` is on a named non-default branch; follow the printed checkout remediation rather than treating it as an installable tool problem. In a read-only session that did not get the fleet lock, the same line is advisory and omits the checkout command. The locked session-start bootstrap step also runs a best-effort project clone refresh through `fm-fleet-sync.sh`. @@ -300,7 +316,7 @@ When a running home advances and its loaded instruction surface (`AGENTS.md`, `b If that send fails, bootstrap keeps an idempotent retry marker and emits `NUDGE_SECONDMATES:` with the failure reason. The same bootstrap run emits `SECONDMATE_LIVENESS:` only when a registered secondmate is skipped or its relaunch fails; already-live and successfully relaunched secondmates are handled silently. For a mid-session inherited local-material edit where tracked-file sync is not needed, run `bin/fm-config-push.sh`. -It uses the same live secondmate discovery and propagation helper as bootstrap, prints each live home's `crew-dispatch.json`, `crew-harness`, `backlog-backend`, `backend`, `herdr-presentation-spaces`, and `data/captain-shared.md` result as `pushed`, `unchanged`, `skipped`, or `error`, and exits non-zero for real propagation errors or config-reread send failures. +It uses the same live secondmate discovery and propagation helper as bootstrap, prints each live home's `crew-dispatch.json`, `crew-harness`, `backlog-backend`, `backend`, `herdr-presentation-spaces`, `startup-memory-budget`, and `data/captain-shared.md` result as `pushed`, `unchanged`, `skipped`, or `error`, and exits non-zero for real propagation errors or config-reread send failures. When an allowlisted config item changes for an already-running home, it sends the literal-content reread pointer described in [`secondmate-provisioning`](../.agents/skills/secondmate-provisioning/SKILL.md); unchanged allowlisted config sends no pointer unless a previous delivery is pending. The locked bootstrap inheritance pass uses the same per-home changed-set and reread path for already-running homes; see `secondmate-provisioning` for the single contract owner. That live discovery starts from `state/*.meta` records with `kind=secondmate`; `data/secondmates.md` only backfills `home=` for older or incomplete meta records. @@ -343,7 +359,7 @@ The record is written only when a platform or explicit budget is actually known, The `fmx-respond` skill decides whether the stashed mention is an actionable request, a question, or a pure acknowledgment. Actionable reversible requests are run through intake, backlog, dispatch, investigation, or ship flow as appropriate. If the work completes in that turn, the public reply reports the outcome. -If the request spawns a longer-running task, firstmate posts an acknowledgement through the normal answer endpoint, links the task to the mention with `bin/fm-x-link.sh`, and posts up to three completion follow-ups on genuine milestones, always finishing with a `--final` one when the task reaches a terminal state. +If the request spawns a longer-running task, firstmate posts an acknowledgement through the normal answer endpoint, links the task to the mention with `bin/fm-x-link.sh`, and posts up to three completion follow-ups on genuine milestones, finishing with a `--final` one for ordinary X-linked work. When a typed promised-final commitment is registered, `bin/fm-public-followup.sh` owns the terminal reply and clears the legacy link after its receipt is validated. That link stores optional reply-platform context so Discord-originated follow-ups keep Discord's larger message budget after the inbox file has been drained. Platform/budget resolution is layered and independent of the task link: a per-axis `FMX_REPLY_PLATFORM` / `FMX_REPLY_MAX_CHARS` override (how `bin/fm-x-followup.sh` passes a recorded link's context) wins. For either axis without an override, `bin/fm-x-lib.sh:fmx_resolve_reply_context` owns the source order: the durable per-request registry is consulted first, then the still-present inbox payload, then - for a follow-up posted live by request_id - an authoritative relay lookup via `POST /connector/request-context` (`{request_id}` in, `{platform, reply_max_chars}` back). @@ -380,6 +396,28 @@ In dry-run, `fm-x-dismiss.sh` records `{request_id, endpoint:"dismiss"}` to the The live answer and follow-up bodies intentionally stay the same shape, including optional `image`; the relay distinguishes them by endpoint, and dismiss stays `{request_id}`. These paths need `jq` to build the JSON payload, but they run before token and network checks, so they need neither `FMX_PAIRING_TOKEN` nor `curl`. +### Promised public replies (state/public-followup) + +A relay request that spawns real work can leave firstmate owing a specific public reply in a specific thread. +That promise is a typed `kind=public-followup` obligation owned entirely by `tasks-axi public-followup`, with the full private request context staying in `state/x-context/`; firstmate keeps no parallel copy of either. +`bin/fm-public-followup.sh` is firstmate's side: it registers a commitment, reconciles typed terminal work results into it, and posts the final reply through `bin/fm-x-reply.sh --followup`. +Run `bin/fm-public-followup.sh --help` for the exact subcommands and flags. + +Registration is what creates this home's private transport under `state/public-followup/` (mode 0700): `registry/` for the bounded public-safe binding of each live commitment, `events/` for typed terminal results awaiting reconciliation, `consumed/` for the accepted-event ledger, `rejected/` for refusals kept with a one-line reason, and `surfaced` for the poll's last-surfaced signature. +The home that owns the commitment also owns the outward post, because only it holds the relay consent, the request context, and the opaque thread binding. +Work routed elsewhere reports a typed terminal result with `bin/fm-public-followup-emit.sh` and never looks for the thread; that emitter refuses to write into a home with no registration for the named obligation. +A terminal event's id is derived from its identity tuple, so a duplicate report, a retry, or a replay after restart resolves to the same event and changes nothing. + +Activation is the same `.env` `FMX_PAIRING_TOKEN` contract as the rest of X mode, with no second flag. +A home without that token runs one file test and stops: no `tasks-axi` call, no backlog or request-context scan, and no `state/public-followup/` directory. +Ordinary startup, polling, cleanup, and silent read-side subcommands also produce no output; commands that require an active relay report that configuration error after the same gate. +A relay-enabled home with no registered commitment stops at an O(1) directory presence check, so the empty state costs no CLI call and adds no periodic scan. +Unreconciled terminal results ride the existing 30-second relay poll rather than a new process or timer: `bin/fm-x-poll.sh` compares the pending-event signature against `surfaced` and wakes firstmate once per new result set. +The session-start digest separately prints an "Public commitments awaiting delivery" subsection from disk when, and only when, this home is relay-active and still owes a reply, so compaction and restart are non-events. +`bin/fm-teardown.sh` refuses to clean up a task while this home still owes a public reply for exactly that work, unless `--force` carries explicit discard approval. +`FM_PF_RETRY_BACKOFF_SECS` (default 900) sets the next-attempt time recorded with a retryable delivery error. +See [verification/public-followup.md](verification/public-followup.md) for the current maintainer evidence behind the restart end-to-end and the relay-disabled zero-overhead guarantee. + ## Environment variables Runtime tuning via environment variables (defaults shown): @@ -428,6 +466,7 @@ FMX_DISCORD_REPLY_MAX_CHARS=1900 # Discord reply per-message split budget; val FMX_X_THREAD_MAX=25 # maximum messages in one auto-split reply thread FMX_FOLLOWUP_MAX_AGE_SECS=604800 # local window for posting X-mode completion follow-ups (7 days) FMX_FOLLOWUP_MAX_COUNT=3 # local cap on X-mode completion follow-ups per linked mention +FM_PF_RETRY_BACKOFF_SECS=900 # seconds before the next attempt after a retryable promised-public-reply delivery error FM_LOCK_STALE_AFTER=2 # seconds before dead-pid lock records can be reclaimed; mid-acquire locks keep at least 2s grace FM_GUARD_GRACE=300 # seconds before guard warnings, arm health checks, and the primary turn-end guard treat a watcher beacon as stale FM_CLAUDE_AUTOARM_SYNC_WAIT_MS=800 # milliseconds the --claude turn-end guard waits for the Stop auto-arm's claim, health, or fresh rewake epoch before re-blocking @@ -461,7 +500,7 @@ FM_STALE_WORKTREE_LOCK_RETRY_WAIT_SECS= # legacy alias for FM_TREEHOUSE_RETURN FM_FLEET_SYNC_PACKED_REFS_LOCK_RETRIES=3 # fetch retries after fm-fleet-sync.sh hits the orphaned .git/packed-refs.lock signature FM_FLEET_SYNC_PACKED_REFS_LOCK_RETRY_WAIT_SECS=1 # seconds fm-fleet-sync.sh waits before each of those retries FM_FLEET_SYNC_PACKED_REFS_LOCK_AGE_SECS=30 # min mtime age before fm-fleet-sync.sh treats a leftover packed-refs.lock as provably stale -FM_BUSY_REGEX= # optional global override for every harness-scoped busy-pane matcher; unset uses each recorded harness's verified signature +FM_BUSY_REGEX= # optional override for rendered delivery guards and Grok's isolated task-state fallback; converted worker state ignores it FM_COMPOSER_IDLE_RE= # optional empty-composer regex, applied after ghost and border stripping FM_COMPOSER_GHOST_LUMA_MAX=128 # fleet-wide: max perceived luminance (0.299R+0.587G+0.114B, 0-255) for a TRUECOLOR foreground to count as de-emphasised ghost/placeholder text and be stripped; dim/faint (SGR 2) is stripped regardless. Assumes a dark terminal theme (bin/fm-composer-lib.sh's fm_composer_strip_ghost, shared by the tmux and herdr composer readers) GROK_HOME= # optional Grok config home for firstmate's global grok turn-end hook; defaults to ~/.grok diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index d15e31bbc56..a36792a49a7 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -308,10 +308,22 @@ "path": "docs/turnend-guard.md", "audience": "operator-current" }, + { + "path": "docs/verification/dispatch-auth.md", + "audience": "maintainer-verification" + }, + { + "path": "docs/verification/public-followup.md", + "audience": "maintainer-verification" + }, { "path": "docs/verification/runtime-backends.md", "audience": "maintainer-verification" }, + { + "path": "docs/verification/stow-memory.md", + "audience": "maintainer-verification" + }, { "path": "docs/verification/supervision.md", "audience": "maintainer-verification" diff --git a/docs/examples/crew-dispatch.json b/docs/examples/crew-dispatch.json index 23a5391d20a..b404e95e777 100644 --- a/docs/examples/crew-dispatch.json +++ b/docs/examples/crew-dispatch.json @@ -16,7 +16,7 @@ { "harness": "claude", "model": "claude-sonnet-5", "effort": "high" }, { "harness": "codex", "model": "gpt-5.5", "effort": "high" } ], - "why": "Firstmate compares every candidate with current relevant quota and pace before dispatch, so use a strong coding profile." + "why": "Use a strong coding profile for big, ambiguous work; resolve the alternatives through quota-array-dispatch." } ], "default": [ diff --git a/docs/herdr-backend.md b/docs/herdr-backend.md index 91047bcc6f3..83d527c588b 100644 --- a/docs/herdr-backend.md +++ b/docs/herdr-backend.md @@ -33,10 +33,11 @@ Real harness credential tests remain opt-in rather than part of default CI. ## Watching and task containers -Each Firstmate home gets one durable workspace with one task tab per endpoint. -The primary workspace is `firstmate`. -A secondmate home uses `2ndmate-<secondmate-id>`, derived from its validated `.fm-secondmate-home` marker. -The secondmate process and every child it launches resolve the same home label; a secondmate launched by the primary receives a narrowly scoped home override during container creation. +The ordinary topology puts one task tab per endpoint in the exact workspace of the Firstmate or secondmate that launches it. +When the launcher has no Herdr workspace to inherit, the adapter maintains one durable home-labeled workspace instead. +The primary home label is `firstmate`. +A secondmate home label is `2ndmate-<secondmate-id>`, derived from its validated `.fm-secondmate-home` marker. +A secondmate launched by the primary receives a narrowly scoped home override during container creation. Attach to the selected named Herdr session and switch to the relevant home workspace to watch its task tabs. Routine supervision uses `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.sh <id> '<text>'` without attaching. @@ -44,10 +45,21 @@ Routine supervision uses `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.s Workspace and tab creation use `--no-focus`. The first workspace in a completely empty Herdr session must become focused because no prior target exists, but later task creation does not intentionally steal focus. -Herdr does not enforce workspace or tab label uniqueness. -Firstmate adopts the first workspace matching its derived home label and refuses duplicate task tabs inside it. -Avoid naming a personal workspace `firstmate` or `2ndmate-<id>` because the adapter cannot distinguish that label collision from its own container. +Herdr does not enforce workspace or tab label uniqueness, so a label can never decide where a worker goes. +Herdr 0.7.5 exports `HERDR_ENV`, `HERDR_PANE_ID`, `HERDR_SESSION`, `HERDR_SOCKET_PATH`, `HERDR_TAB_ID`, and `HERDR_WORKSPACE_ID` into every process it manages a pane for, and a Firstmate or secondmate agent's own commands inherit them. +Older injection shapes are unverified, so a claimed launcher pane without the injected socket identity cannot be trusted. +With presentation spaces disabled, a crewmate or scout is created in the exact workspace that identity currently resolves to, read live from Herdr rather than from the injected snapshot, so the worker always appears beside the agent that launched it. +Duplicate labels elsewhere in the session are irrelevant, and the globally focused workspace is never the target. +A `--secondmate` launch is the deliberate exception: it stands up that secondmate home's own workspace instead of joining the launcher's. + +A claimed parent identity that cannot be resolved exactly stops the spawn before any worker endpoint exists, rather than falling back to a label search. +That covers a missing or unusable socket identity, a closed or unreadable launcher pane, a pane and tab that disagree about their workspace, a workspace missing from the session, and a pane belonging to another named session or Herdr server. + +Firstmate running outside Herdr entirely has no launcher workspace to inherit, so its workers use this home's own labeled workspace, created on first use. +That path needs the home label to identify exactly one workspace: two workspaces sharing it are an unresolvable placement and refuse rather than adopting either. +Avoid naming a personal workspace `firstmate` or `2ndmate-<id>` for that reason, and because the adapter cannot distinguish that label collision from its own container. An older secondmate workspace using `firstmate-<id>` is not migrated automatically; rename it manually before expecting new tasks or recovery to use it. +Recovery and list-live still scan the first workspace matching the home label, because they address panes they already recorded rather than choosing where new work goes. Existing task operations use recorded endpoint ids and do not move a live task when labels change. The per-home workspace is reused while it has task tabs. @@ -63,9 +75,12 @@ An absent or unconverged setting keeps the flat default. Presentation is a best-effort visual projection, never task ownership or lifecycle authority. Only a fresh task with neither metadata nor an existing presentation journal is eligible for projected creation. Firstmate atomically publishes a three-field version 1 journal containing a random 128-bit base64url token before asking Herdr to create anything. -After the new workspace converges to one exact task endpoint beneath one exact parent, the journal advances to a version 2 binding that records the physical home, named session, endpoint, parent, and immutable expected labels. +After the new workspace converges to one exact task endpoint beneath one exact parent workspace id, the journal advances to a version 2 binding that records the physical home, named session, endpoint, parent, and immutable expected labels. +Another parent with the same presentation label does not prevent publication or participate in restart reclaim. The token is visible in the workspace title because Herdr exposes no verified hidden persistent field, but neither token, title, nor journal authorizes send, capture, task ownership, Treehouse return, or general recovery. +The owning parent is the launcher's own exact workspace, resolved from the same identity the flat path uses, and falls back to a unique home-label lookup only for a Firstmate outside Herdr. +Projected children are never collapsed back into that parent; it is the placement and ordering reference the projection is bound under. The normal `fm-<id>` task tab is created in the exact new workspace returned by Herdr. Only the exact seeded default tab returned by the same workspace-create response can be pruned. Before and after create, prune, order, abort cleanup, and normal cleanup, Firstmate verifies exact workspace, tab, pane, and active-focus ids. @@ -83,7 +98,17 @@ The worker remains on the ordinary flat or Herdr-current-order path. Normal task metadata remains the sole endpoint authority after creation. Cleanup closes only the exact recorded task pane and never calls `workspace close`. -Herdr can move focus when closing the last pane of a non-focused projected workspace, so projected cleanup runs under the same session lock, captures the exact active tab, refuses to delete the active tab, closes the exact task pane, and restores only the exact prior tab when needed. +Herdr 0.7.5's explicit close moves focus to a neighbor whenever it empties a non-focused workspace, while its pane-death removal preserves the focused workspace whenever the dying workspace sits behind it or the focused workspace is last; both behaviors are fixed on the upstream default branch but in no release, and the exact rules live in the adapter header of `bin/backends/herdr.sh`. +Projected cleanup therefore runs under the same session lock, captures the exact active tab, refuses to delete the active tab, and treats a workspace-emptying close as a focus-safe removal: it verifies the close would empty the workspace, repositions the doomed workspace behind the focused one through the verified `workspace.move` transport when needed, proves the pane holds one lone idle shell, and ends that shell so Herdr removes the emptied workspace through its focus-preserving pane-death path. +The repositioning move-to-last preserves every surviving workspace's relative order, and removal is confirmed against the exact moved workspace rather than inferred from pane disappearance before an unconfirmed removal makes one verified attempt under the same session lock to roll the doomed workspace back to its exact original position. +If that rollback cannot restore the verified original order, cleanup warns loudly and leaves the retained records for inspection rather than retrying the shared-layout mutation. +The pane-death signals are pid-exact: the escalation re-reads the pane's process information and refuses unless the same shell pid still passes the strict bare-idle ownership proof, so an exited and reused pid is never signaled. +Any ambiguity, unsupported or failed move, or unproved shell falls back to the plain explicit close, and the exact prior-tab restore remains the backstop behind every close, so degraded behavior is never worse than the pre-mitigation sub-second restore. +Ordinary non-projected task removal serializes through the same session lock, applies the same focus-safe plan when its close would empty a non-focused workspace, keeps the legitimate plain close when the target is the active tab, and refuses an unlocked close if the lock cannot be acquired. +Task cleanup acquires that session lock before the task's isolated copy is returned, so a contended lock refuses up front while the copy, every durable record, and the endpoint are all intact for a plain rerun. +Forced secondmate cleanup recursively preflights every Herdr child endpoint and acquires every affected named-session lock before mutating any child, then retains each child's durable identity unless that exact pane returns structured not-found after its close. +Durable task records are erased only once the exact pane is confirmed gone through its structured presence: after every close path, only a structured not-found response counts as gone, while a present or unknown result retains every record with a visible, retryable error. +Missing or malformed endpoint identity and missing confirmation machinery are ambiguity, never proof of a gone pane, and refuse record removal the same way. If lock, snapshot, pane identity, or restoration is ambiguous, cleanup warns and preserves the journal for manual inspection. Recovery is deliberately conservative and presentation-only. @@ -104,6 +129,7 @@ The task's ordinary metadata must be absent, and the candidate must have exactly Before cleanup, Firstmate acquires the existing task-id spawn lock and then the shared named-session presentation lock. Inside both locks it takes one exact snapshot, requires one unambiguous non-target focus and the exact title, token, tab, and pane shape, positively confirms no registered agent, and reads Herdr's process information for the exact named-session pane. The process proof requires one recognized idle shell as both the shell process and the sole foreground process-group member, an operating-system process-table row for that shell, no child process, and a sleeping or idle shell state. +The proof retries strict single samples for a bounded settle window because an idle interactive shell transiently hosts short-lived prompt helpers; a genuinely busy pane fails every sample. Any foreground command, child process, active shell job, unknown shell, unreadable process table, missing field, or API error preserves the pane. Firstmate immediately revalidates the same journal, metadata absence, workspace title and token uniqueness, one-tab and one-pane topology, exact pane relationship, absent agent, process proof, and non-target focus before calling the existing exact-pane focus-preserving close helper. It closes only that pane, never a workspace. @@ -124,7 +150,8 @@ Operational compromises: `tests/fm-backend-herdr-presentation-e2e.test.sh` covers multi-home ordering, concurrency, lock contention, legacy coexistence, focus preservation, exact same-identity restart replacement, ambiguous bindings and tokens, and exact-pane cleanup through the guarded lab path. `tests/fm-herdr-session-cleanup.test.sh` covers every discovery, ownership, topology, process, locking, revalidation, focus, retirement, and continue-on-error boundary. -`tests/fm-herdr-session-cleanup-e2e.test.sh` covers the restored-shell cleanup in a guarded non-default named lab; [`verification/runtime-backends.md`](verification/runtime-backends.md#per-home-and-presentation-topology) owns the active versioned evidence. +`tests/fm-herdr-session-cleanup-e2e.test.sh` covers the restored-shell cleanup in a guarded non-default named lab. +`tests/fm-backend-herdr-focus-flash-e2e.test.sh` reproduces the raw explicit-close focus steal on the installed release and proves the focus-safe emptying-close plan removes a doomed workspace with no wrong-focus interval; [`verification/runtime-backends.md`](verification/runtime-backends.md#workspace-removal-focus-safety) owns the active versioned evidence. ## Default-tab prune safety @@ -176,7 +203,7 @@ The capture owner requests at least 200 lines from Herdr and trims locally to th This generous floor is required for small composer and peek reads. Herdr's native agent state can read idle while a harness waits on its own long foreground tool. -The shared crew-state path therefore corroborates every native non-busy or unreadable result with the recorded harness's rendered busy signature before concluding that a pane is not working. +The shared crew-state path therefore accepts a native `busy` as evidence of activity but never a native `idle` as evidence that a worker has stopped; the task's own semantic busy state (`bin/fm-busy-lib.sh`) decides that. A human-blocked permission dialog has no busy banner and still surfaces. ## Composer and injection safety @@ -259,7 +286,8 @@ Tests use thin compatibility wrappers in `tests/herdr-test-safety.sh` and never - Herdr remains experimental. - Presentation ordering needs protocol 16 and Python and is best-effort only. -- Mutable labels can collide; they are never destructive authority. +- Mutable labels can collide; they are never placement or destructive authority. +- A Firstmate outside Herdr cannot resolve a launcher workspace, so a colliding home label refuses new spawns until the collision is cleared. - Ghost and placeholder recognition depends on ANSI de-emphasis and fails safely to pending when unavailable. - Mid-session secondmate liveness is not implemented. - OpenCode 1.18.4 can accept Enter while busy without clearing the composer. @@ -274,6 +302,7 @@ tests/fm-backend-herdr-smoke.test.sh tests/fm-backend-herdr-prune-safety-e2e.test.sh tests/fm-backend-herdr-respawn-idem-e2e.test.sh tests/fm-backend-herdr-workspace-per-home-e2e.test.sh +tests/fm-backend-herdr-launcher-workspace-e2e.test.sh tests/fm-backend-herdr-presentation-e2e.test.sh tests/fm-backend-herdr-eventwait-smoke.test.sh tests/fm-herdr-session-cleanup.test.sh diff --git a/docs/orca-backend.md b/docs/orca-backend.md index 9812993e830..42b9815cec5 100644 --- a/docs/orca-backend.md +++ b/docs/orca-backend.md @@ -51,7 +51,8 @@ Exact command flags and response parsing are owned by `bin/backends/orca.sh` and `fm-peek.sh` reads with `orca terminal read`. `fm-send.sh` types and verifies composer clearance, follows `oldestCursor` when Orca returns a limited page, and retries Enter without retyping when a slash popup first fills an argument placeholder. A bare shell row is `unknown`, not an empty agent composer. -The watcher has no native Orca busy signal and uses the shared terminal-tail fallback. +The watcher has no native Orca busy signal, so each harness adapter's semantic lifecycle supplies worker state. +Grok alone retains its isolated rendered-tail fallback. Cleanup keeps all shared Firstmate safety checks. A scout still requires its report and completed decision inventory. diff --git a/docs/scripts.md b/docs/scripts.md index 4e646537fed..a75e0d1955e 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -62,7 +62,7 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize | `fm-afk-launch.sh` | Own away-mode entry, exit, rollback, and any backend terminal lifecycle | | `fm-afk-return.sh` | Own deterministic return shutdown, catch-up evidence, and the firstmate-actionable blocker gate | | `fm-supervisor-target-lib.sh` | Resolve the shared supervisor target and backend for the daemon and launcher | -| `fm-supervise-daemon.sh` | Presence-gated away-mode sub-supervisor: self-handle routine wakes, escalate batched digests, alert on failed delivery | +| `fm-supervise-daemon.sh` | Presence-gated away-mode sub-supervisor: self-handle routine wakes, guard injection by the detected primary harness, escalate batched digests, alert on failed delivery | | `fm-crew-state.sh` | Print one deterministic current-state line for a crew | | `fm-tangle-lib.sh` | Shared default-branch resolution and primary-checkout tangle classification | | `fm-supervision-lib.sh` | Shared in-flight-work-without-fresh-watcher-beacon predicate | @@ -70,11 +70,15 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize | `fm-lock-lib.sh` | Shared "is this git lock provably abandoned?" proof used by teardown and fleet-sync | | `fm-config-inherit-lib.sh` | Shared primary-to-secondmate inherited local-material propagation and config-reread delivery | | `fm-tasks-axi-lib.sh` | Shared backlog-backend selector and `tasks-axi` compatibility probe | +| `fm-quota-axi-lib.sh` | Shared `quota-axi` compatibility floor for the bootstrap diagnostic | +| `fm-vendor-auth-probe.sh`| Run one hard-bounded, non-destructive authentication probe of a named vendor CLI and report the fact | | `fm-wake-drain.sh` | Atomically drain queued watcher wakes, emit bounded best-effort status-event annotations, then assert watcher liveness | | `fm-wake-lib.sh` | Shared durable wake queue, portable locks, and watcher identity/health helpers | | `fm-classify-lib.sh` | Shared captain-relevant and declared-external-wait wake classification vocabulary | | `fm-send.sh` | Send one verified literal line or supported key through the target's recorded backend | -| `fm-tmux-lib.sh` | Shared tmux pane primitives for busy detection, composer capture, and verified submit | +| `fm-busy-lib.sh` | Single owner of the semantic busy-state contract: verdicts, source attribution, and per-harness sources | +| `fm-busy-event.sh` | The only writer of a task's semantic busy-state record; arms an incarnation and applies lifecycle events | +| `fm-tmux-lib.sh` | Shared tmux pane primitives for composer capture, verified submit, and the submit-time busy check | | `fm-peek.sh` | Print a bounded tail of a crewmate endpoint | | `fm-check-register.sh` | Bind an intentional custom watcher check to its current bytes | | `fm-check-lib.sh` | Validate custom-check registrations and prepare private execution snapshots | @@ -96,3 +100,6 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize | `fm-x-dismiss.sh` | Dismiss a skipped X-mode mention at the relay without replying | | `fm-x-link.sh` | Link a spawned task to its originating X-mode mention in task meta | | `fm-x-followup.sh` | Detect, post, and cap completion follow-ups for an X-mode-linked task | +| `fm-public-followup-lib.sh` | Shared relay-activation gate, O(1) presence checks, and private transport paths for promised public replies | +| `fm-public-followup.sh` | Reconcile typed terminal work results into a public commitment and deliver its final reply once | +| `fm-public-followup-emit.sh` | Report one typed terminal work result into the home that owes the public reply | diff --git a/docs/tmux-backend.md b/docs/tmux-backend.md index 3bf20fe9d1a..936e0e7b47d 100644 --- a/docs/tmux-backend.md +++ b/docs/tmux-backend.md @@ -59,9 +59,11 @@ Unreadable, incomplete, or structurally ambiguous boxes fail closed, and panes w The shared classifier accepts a shell glyph as an empty agent composer only inside a verified bordered composer. A bare shell prompt is `unknown`, so away-mode escalation is never injected into a dead shell. -Rendered busy detection is also harness-scoped. -Task metadata selects only that harness's verified signature, so output from one harness cannot make another harness appear busy. -The exact selection contract and safety rationale live in [architecture](architecture.md#runtime-session-backends), while the signatures live in [the harness-adapters skill](../.agents/skills/harness-adapters/SKILL.md). +Busy state is not read from rendered text on this backend. +A task's busy, idle, unknown, or dead verdict comes from the semantic busy-state contract owned by `bin/fm-busy-lib.sh`; [architecture](architecture.md#busy-state-is-semantic-per-adapter) owns its boundaries. +The one remaining rendered-tail reader is Grok's isolated fallback inside that contract, which can only classify a Grok task. +The submit acknowledgement and away-mode supervisor-pane busy guard below still consult rendered output, but only to decide whether input can be delivered, never to decide recorded task state. +The supervisor guard selects only the detected primary harness's signature rather than a global union of vendor patterns. `bin/fm-tmux-lib.sh` owns exact type-and-submit mechanics. It types a message once and retries Enter only until the composer clears. diff --git a/docs/verification/dispatch-auth.md b/docs/verification/dispatch-auth.md new file mode 100644 index 00000000000..86b9f4795df --- /dev/null +++ b/docs/verification/dispatch-auth.md @@ -0,0 +1,178 @@ +# Dispatch authentication verification + +Audience: maintainer verification. + +This record supports the dispatch judgment rules in `.agents/skills/quota-array-dispatch/SKILL.md` and the bounded vendor probe in `bin/fm-vendor-auth-probe.sh`. +It records only facts that must be re-established when a producer or vendor version changes. +Task chronology, incident transcripts, and credential metadata stay in private reports or PR evidence. + +Firstmate resolves a candidate's provider family, credential surface, and applicable quota by reading the evidence below and reasoning in the open. +No script maps a model to a provider, a provider to a credential store, or a name prefix to a family, so the facts here are what that reasoning rests on. +Credential paths below are shown with the home directory replaced by `<home>`. + +## Quota granularity the judgment depends on + +Verified 2026-07-30 against quota-axi 0.1.16. + +`quota-axi --json` reports availability at whatever granularity the vendor supplies, and states the vendor's own bounding rule in `quotaSemantics.description`. + +```json +{ + "provider": "codex", + "state": { "status": "fresh", "stale": false }, + "quotaSemantics": { + "status": "known", + "description": "Codex base account windows bound every model. Named model windows add bounds for that model; code-review windows describe a separate workload and are not included in model availability.", + "effectiveAvailability": [ + { "scope": "all_models", "status": "known", "effectivePercentRemaining": 64, "boundedBy": ["weekly"] }, + { "scope": "model:codex_bengalfox", "status": "known", "effectivePercentRemaining": 64, "boundedBy": ["weekly", "model:codex_bengalfox:7d"] } + ] + } +} +``` + +Three properties follow and are load-bearing for dispatch: + +- An `all_models` (or `all_products`) scope is real evidence for every model in that provider family, including a model with no window of its own. +- A `model:`-scoped entry is an additional bound for that one model. `model:codex_bengalfox` is the GPT-5.3-Codex-Spark window and bounds nothing else. +- A named-model window can be tighter than the account bound, so it must not be read across models. In the same snapshot Claude reported `all_models` with `effectivePercentRemaining` 10 while `model:fable` reported 4, limited by the `model:fable` window itself. A non-Fable Claude model reads 10, not 4. + +`quotaSemantics.status` is `unknown` with no `effectiveAvailability` entries at all for providers whose vendor exposes no window (observed for `cursor` and `copilot`). +`state.authStatus` is present only for some providers (observed for `grok` alone), so its absence is missing evidence, not a credential fault. + +## Completion-runway shape the judgment depends on + +Verified 2026-07-31 against quota-axi 0.1.17 schema 3. +The command below records the producer shape without persisting account-specific quota values: + +```sh +quota-axi --json | jq '{schemaVersion, effectiveAvailabilityFields: ([.providers[]?.quotaSemantics.effectiveAvailability[]? | keys] | unique), runwayFields: ([.providers[]?.quotaSemantics.effectiveAvailability[]?.runway? | select(type == "object") | keys] | unique)}' +``` + +```json +{ + "schemaVersion": 3, + "effectiveAvailabilityFields": [ + [ + "boundedBy", + "effectivePercentRemaining", + "limitingWindowIds", + "pace", + "runway", + "scope", + "status" + ] + ], + "runwayFields": [ + [ + "limitingWindowId", + "projectedExhaustedAt", + "projectionBasis", + "projectionConfidence", + "status", + "usableRunwaySeconds" + ], + [ + "limitingWindowId", + "projectedExhaustedAt", + "status", + "usableRunwaySeconds" + ] + ] +} +``` + +`runway` is nested under each effective-availability scope, so the same provider/model applicability rules govern both effective headroom and runway. +Projection confidence and basis are not present on every known runway, so selection must preserve their absence as uncertainty rather than fabricate them. +The older-schema fallback contract is owned by `quota-array-dispatch`; this evidence does not reinterpret an absent runway or pace field. + +## Provider-family counterfactual that this producer schema supports + +Verified 2026-07-30 on Pi 0.82.0 and quota-axi 0.1.16. + +```sh +pi --list-models terra +``` + +```text +provider model context max-out thinking images +openai-codex gpt-5.6-terra 272K 128K yes yes +``` + +The Pi catalog is authoritative for Pi model support and reports the provider family in its own column. +For `harness=pi`, `model=openai-codex/gpt-5.6-terra` the catalog establishes the model is supported and belongs to the `openai-codex` family, and the Codex `all_models` scope above supplies fresh, known 64 effective remaining for every model in that family. +No Terra-specific window exists in the snapshot, and `quota-axi auth --json` lists no `pi:openai-codex` source. +Both absences are missing model-level and source-level detail, not contradictory evidence, so this candidate is dispatchable with the model-level uncertainty disclosed. + +```sh +pi --list-models gpt-9.9-nonexistent +``` + +```text +No models matching "gpt-9.9-nonexistent" +``` + +A listing that reaches the account and returns no row is the authoritative negative that does block a candidate. + +## Credential sources are independent per provider + +Verified 2026-07-30 against quota-axi 0.1.16. + +`quota-axi auth --json` reports each provider's credential sources separately, which is what lets a candidate be scoped to the one surface it actually authenticates through: + +```json +[ + { "provider": "claude", "sources": [ + { "source": "oauth-file", "path": "<home>/.claude/.credentials.json", "status": "missing" }, + { "source": "keychain", "status": "available" } ] }, + { "provider": "codex", "sources": [ + { "source": "auth-json", "path": "<home>/.codex/auth.json", "status": "available" }, + { "source": "cli-rpc", "path": "<path-to>/codex", "status": "available" } ] }, + { "provider": "grok", "sources": [ + { "source": "auth-json", "path": "<home>/.grok/auth.json", "status": "available" }, + { "source": "pi:xai", "status": "available" } ] }, + { "provider": "kimi", "sources": [ + { "source": "pi:kimi-coding", "status": "available" }, + { "source": "kimi-code-cli", "status": "expired", "error": "kimi_code_cli_credential_expired" } ] } +] +``` + +Observed source statuses are `available`, `expired` (with an `error` slug), and `missing`. + +- A provider can carry a healthy source beside a missing or expired one, so a provider must not be collapsed to a single status. Claude's `oauth-file` is missing while its keychain source is available, and Kimi's standalone CLI credential is expired while its Pi source is available. +- A `pi:`-prefixed source exists only where Pi holds its own credential for that family (`pi:xai`, `pi:kimi-coding`). Pi's `openai-codex` family has none, because it authenticates through the Codex store that the `codex` provider already lists. A missing `pi:` source is therefore never evidence against a Pi candidate. + +Neither this per-source shape nor `state.authStatus` exists before quota-axi 0.1.16. +`bin/fm-bootstrap.sh` enforces that floor through `bin/fm-quota-axi-lib.sh`. + +Grok also reports `credits.remaining: 0` alongside `percentRemaining: 41` on a healthy account. +That zero is a prepaid balance, not the subscription window, and is never headroom. + +## Standalone Grok discovery probe + +Verified 2026-07-30 on `grok 0.2.117 (f1c06093089f) [stable]`. + +```sh +grok --version +grok models # stdin closed, single attempt, hard-bounded +``` + +Observed: + +- `grok models` exits `0` and its first stdout line is `You are logged in with grok.com.` for an authenticated session. +- With a home directory holding no Grok credential, the first stdout line is `You are not authenticated.`, also with exit status `0`. +- Because the status is `0` in both cases, the exit status is not a verdict; only the literal first stdout line is examined, and a blank first line does not authenticate. +- `<home>/.grok/auth.json` was byte-identical across the authenticated run (`mtime`, `size`, and mode `0600` unchanged), so the probe is a read in that path. + +These discriminator strings are un-owned vendor UI text. +`bin/fm-vendor-auth-probe.sh` pins the verified version, reports `versionVerified=no` when the running CLI differs, and classifies any unrecognized first line as `indeterminate` rather than authenticated. +Re-run the two commands above and update this section and the pinned version together when the vendor CLI changes. + +## Regression coverage + +`tests/fm-vendor-auth-probe.test.sh` drives the real script against a fake vendor CLI that records every invocation's argv and anything readable on stdin. +It asserts that the script accepts no harness, model, or provider input, never calls `quota-axi`, exits alike for every probe result because it renders no verdict, invokes only the two fixed non-destructive argv forms with stdin closed, holds a real bound even when the configured bound is zero or malformed, and never echoes raw vendor output. +`tests/fm-spawn-dispatch-profile.test.sh` owns spawn's deterministic profile and harness refusals. +`tests/fm-bootstrap.test.sh` owns the quota-axi version-floor diagnostic. +`tests/fm-quota-array-dispatch-live-e2e.test.sh` drives the public Pi skill-loading interface against one fake `quota-axi --json` snapshot per case. +It covers the Claude 1 percent versus Codex 55 percent reserve regression, explicit accounting for unmeasurable runway, and the strongest-reasoning constraint. diff --git a/docs/verification/public-followup.md b/docs/verification/public-followup.md new file mode 100644 index 00000000000..48f9f6d39e1 --- /dev/null +++ b/docs/verification/public-followup.md @@ -0,0 +1,102 @@ +# Promised public reply verification + +Audience: maintainer verification. + +This record supports two active guarantees for promised public replies made through the myfirstmate relay: + +1. A promised final reply survives compaction and restart, reconciles from disk alone, and lands in the original thread exactly once. +2. A home that never opted into the relay pays nothing for any of it. + +[`docs/configuration.md`](../configuration.md#promised-public-replies-statepublic-followup) owns the operator-facing contract, [`docs/architecture.md`](../architecture.md#optional-x-mode) owns the mechanism boundary, and `tasks-axi public-followup --help` owns the typed obligation schema. +Task chronology and delivery evidence stay outside this record. + +## Environment + +Recorded 2026-07-30 on Darwin 25.5.0 (arm64) with GNU bash 5.3.9, tasks-axi 0.2.3, jq 1.8.1, and ShellCheck 0.11.0 (the version `bin/fm-lint.sh` pins). +The relay is a fakebin `curl` in every case, so no public post is ever made; `tasks-axi` and `jq` are the real tools, because stubbing the obligation state machine would verify nothing. + +## Restart end-to-end and regressions + +```sh +bash tests/fm-public-followup.test.sh +``` + +``` +ok - outcome text is collapsed to one line, bounded by codepoint, and never corrupts characters +ok - restart end-to-end: typed result reconciles from disk and delivers one reply to the original thread +ok - duplicate terminal results, restart replay, and repeated delivery are all no-ops +ok - wrong source, wrong work id, stale generation, malformed, unsupported deliverable, and forged identity are all refused +ok - a relay transport failure is held as retryable with no false completion, and the retry posts once +ok - a late success receipt closes the exact attempt with no second post, and a mismatched attempt is refused +ok - a delivery interrupted between post and receipt refuses to repost +ok - a child home reports typed results but can never become the outward-post owner +ok - the retained private request context keeps the original thread deliverable after inbox cleanup +ok - cleanup refuses while a public reply is owed and proceeds once it has landed +ok - a relay-disabled home runs no tasks-axi call, prints nothing, and gains no artifact +ok - a relay-enabled home with no commitments makes no backlog call and stays silent +ok - a relay-exhausted follow-up binding is escalated rather than retried into the thread +ok - the relay poll stays inert without a token, silent with no commitments, and surfaces a new result once +ok - startup surfaces unresolved public commitments only in a relay home that owes one +ok - typed public-followup records carry only public-safe summaries and deliverables +``` + +The first case is the end-to-end proof. +It reproduces the stranded state first (work bound, no reconciled terminal result, delivery refused with "still waiting on its bound work" and zero posts), then has a secondmate-shaped child report a typed `pr-merged` result, deletes the drained inbox payload, reconciles from disk, and asserts exactly one `connector/followup` call carrying the original `request_id`, a validated `posted` receipt, and a Done obligation. + +The existing X-mode suite is unchanged by this work: + +```sh +bash tests/fm-x-mode.test.sh | grep -c '^ok -' +``` + +``` +103 +``` + +## Relay-disabled zero overhead + +A home with no `.env` at all, a `tasks-axi` shim that logs every invocation, and a full session-start run: + +```sh +find "$HOME_DIR/state" | LC_ALL=C sort > state-before.txt +FAKE_TASKS_AXI_LOG=tasks-axi.log bin/fm-session-start.sh > session-start.out 2>&1 +find "$HOME_DIR/state" | LC_ALL=C sort > state-after.txt +grep -c 'public-followup' tasks-axi.log +grep -ci 'public commitment' session-start.out +diff state-before.txt state-after.txt | grep '^>' +``` + +``` +0 +0 +> <home>/state/.lock +> <home>/state/.pr-check-migration-scan-v1 +> <home>/state/.pr-check-migration-v1 +> <home>/state/.wake-queue +``` + +No `tasks-axi public-followup` invocation, no public-commitments output, and no `state/public-followup` directory. +The four created paths are session-start's pre-existing session lock, PR-check migration markers, and wake queue, none of which this work touches. + +The whole added cost in that home is the activation predicate, measured over 1000 in-process calls including loop overhead: + +```sh +. bin/fm-public-followup-lib.sh +for i in $(seq 1 1000); do fm_pf_relay_active "$HOME_DIR" || true; done +``` + +``` +total_ns=69694000 per_call_us=69 +``` + +Roughly 0.07 ms per session start, from a single `[ -f "$FM_HOME/.env" ]` test that returns false before anything else runs. + +## Compatibility axes reviewed + +Primary harnesses (`claude`, `codex`, `opencode`, `pi`, `pi-signed`, `grok`, `kimi`): not applicable after inspection. +Nothing here reads or renders harness-specific state. +The only supervision surfaces touched are the session-start digest, which `bin/fm-supervision-instructions.sh` already renders per harness without knowing this section exists, and the wake payload produced by the existing relay poll, which every harness protocol consumes identically. + +Runtime backends (tmux, herdr, zellij, orca, cmux): not applicable after inspection. +No command here reads `state/<id>.meta`'s backend fields, resolves an endpoint, or captures a pane. +The one lifecycle integration is `bin/fm-teardown.sh`'s refusal, which runs before any backend command and keys only on the task id, so it behaves identically on every backend. diff --git a/docs/verification/runtime-backends.md b/docs/verification/runtime-backends.md index 2060dd22f72..17166acd96a 100644 --- a/docs/verification/runtime-backends.md +++ b/docs/verification/runtime-backends.md @@ -123,7 +123,8 @@ Claude, Codex, OpenCode, Pi, pi-signed, Grok, and Kimi share that backend cleanu ## Herdr The compatibility floor is protocol 14. -The latest core CLI matrix verification uses Herdr 0.7.5 protocol 16 on macOS aarch64, with earlier 0.7.4, protocol-14, and 0.7.3 evidence retained where they define current behavior or fallbacks. +The latest active verification uses Herdr 0.7.5 protocol 17 on macOS aarch64, with earlier 0.7.5 protocol-16, 0.7.4, protocol-14, and 0.7.3 evidence retained where they define current behavior or fallbacks. +Protocol 17 keeps every protocol-16 feature gate satisfied; the event and workspace-move floors remain 16. Core read-only probes: @@ -133,11 +134,11 @@ herdr status --json | jq -c '{client:.client.protocol,server:.server.protocol}' herdr api schema --json | jq -c '.schemas.subscription_event["$defs"].SubscriptionEventKind.enum' ``` -Observed current shapes: +Observed protocol-16 compatibility shapes: ```text herdr 0.7.5 -{"client":16,"server":16} +{"client":17,"server":17} ["pane.output_matched","pane.agent_status_changed","pane.scroll_changed"] ``` @@ -149,7 +150,7 @@ The CLI matrix was checked directly: | Literal send | `herdr pane send-text <pane> <text> --session <name>` | Left text unsubmitted until Enter. | | Keys | `herdr pane send-keys <pane> enter|escape|ctrl+c --session <name>` | Enter and Escape worked; Ctrl-C interrupted foreground work. | | Capture | `herdr pane read <pane> --source recent --lines N` | Small N could return empty below viewport height; a 200-line request plus local trim was stable. | -| Native state | `herdr agent get <pane>` | Working and done transitions were visible; long foreground tool waits required rendered-busy corroboration. | +| Native state | `herdr agent get <pane>` | Working and done transitions were visible; native `busy` remains positive activity evidence, while native `idle` cannot close a turn and the adapter's semantic lifecycle decides worker state. | | Restart | guarded named-session stop then start | Workspace, tab, pane, and labels persisted; the agent process and registration did not. | | Close | `herdr pane close <pane> --session <name>` | The exact one-pane task tab closed; closing a final tab could remove the workspace. | @@ -176,6 +177,63 @@ HERDR_LAB_HELPER=bin/fm-herdr-lab.sh \ Observed guarantee: a restored no-agent tab was replaced create-before-close, while a registered live agent caused refusal. +### Launcher workspace placement + +Herdr exports its pane identity into every process it manages, checked on 2026-07-30 against Herdr 0.7.5 protocol 17 inside a guarded lab pane: + +```sh +HERDR_LAB_HELPER=bin/fm-herdr-lab.sh +"$HERDR_LAB_HELPER" run "$LAB" pane run "$PANE" "sh -c 'env | grep ^HERDR | sort > /tmp/env.txt'" +``` + +```text +HERDR_ENV=1 +HERDR_PANE_ID=w1:p1 +HERDR_SESSION=fm-lab-fm-herdr-env-pro-65961-25535 +HERDR_SOCKET_PATH=/Users/kunchen/.config/herdr/sessions/fm-lab-fm-herdr-env-pro-65961-25535/herdr.sock +HERDR_TAB_ID=w1:t1 +HERDR_WORKSPACE_ID=w1 +``` + +This complete injection shape is verified only for Herdr 0.7.5. +Firstmate requires both `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` before accepting claimed launcher ancestry. + +`pane get` reports the pane's current owning tab and workspace, which is what placement resolves from; the injected `HERDR_TAB_ID` and `HERDR_WORKSPACE_ID` are creation-time snapshots and are not read as current identity: + +```sh +"$HERDR_LAB_HELPER" run "$LAB" pane get w1:p1 | jq -c '.result.pane | {pane_id,tab_id,workspace_id}' +``` + +```text +{"pane_id":"w1:p1","tab_id":"w1:t1","workspace_id":"w1"} +``` + +Placement is owned by: + +```sh +HERDR_LAB_HELPER=bin/fm-herdr-lab.sh \ + tests/fm-backend-herdr-launcher-workspace-e2e.test.sh +``` + +Observed guarantees on 2026-07-30 against Herdr 0.7.5 protocol 17: + +```text +ok - real herdr E2E: with one 'firstmate' workspace and no herdr parent, a crewmate still lands in this home's own workspace without stealing focus +ok - real herdr E2E: the normal unique-label path is unchanged when the launcher's own pane identifies the workspace +ok - real herdr E2E: presentation spaces still create the isolated child workspace and bind it under the launcher's exact parent, without stealing focus +ok - real herdr E2E: with two 'firstmate' workspaces, a worker spawned from inside the second one lands in that exact workspace +ok - real herdr E2E: the duplicate-labeled sibling workspace is left entirely untouched and focus is preserved +ok - real herdr E2E: with a duplicated home label, a projected worker still hangs off the launcher's exact workspace and the sibling stays untouched +ok - real herdr E2E: an ambiguous home label with no launcher identity refuses before any worker endpoint exists +ok - real herdr E2E: a launcher pane that no longer exists refuses before any worker endpoint exists +ok - real herdr E2E: a secondmate launching its own worker gets the same exact-workspace guarantee, and its same-labeled sibling is untouched +ok - real herdr E2E: a --secondmate launch still stands up that secondmate's own workspace instead of inheriting the launcher's +ok - real herdr E2E: teardown closes only the worker's own pane and leaves the launcher, its workspace, and the same-labeled sibling intact +``` + +That suite's headline case runs `bin/fm-spawn.sh` inside a real Herdr pane, so the parent identity comes from Herdr's own injection rather than a composed environment. +Cross-session and contradictory bindings are covered deterministically in `tests/fm-backend-herdr.test.sh`, which can script a second server's socket without provisioning one. + ### Per-home and presentation topology Per-home behavior is owned by: @@ -233,6 +291,57 @@ HERDR_LAB_HELPER=bin/fm-herdr-lab.sh \ Observed guarantee: one exact home-local, journal-correlated, one-tab and one-pane childless idle shell was closed after restoration while the exact non-target focus and default fleet session remained unchanged, and a repeat run was a no-op. +### Workspace-removal focus safety + +The focus-flash regression ran on 2026-07-28 against Herdr 0.7.5 protocol 17 on macOS aarch64: + +```sh +HERDR_LAB_HELPER=bin/fm-herdr-lab.sh \ + tests/fm-backend-herdr-focus-flash-e2e.test.sh +``` + +Observed output: + +```text +ok - old path: the explicit last-pane close of a non-focused workspace stole focus (w3 w3:t1 -> w2 w2:t1) +ok - mitigation: every in-operation sample preserved exact focus while the doomed workspace was removed +ok - mitigation: no explicit close and no corrective focus were needed on the defective release +evidence: herdr=0.7.5 protocol=17 steal_live=1 default-session-tripwire=armed +``` + +Direct lab probes on the same day established the removal rules the emptying-close plan relies on, each verified with `workspace list` focus reads around one mutation in a guarded `fm-lab-` session: + +- An explicit `pane close` that emptied a non-focused workspace moved focus off the focused workspace in both before-focus and after-focus geometries. +- Ending a workspace's lone shell preserved the focused workspace exactly when the dying workspace sat behind it or the focused workspace was last, and moved focus to the focused workspace's right neighbor otherwise. +- The production focus-preserving close in the dangerous geometry repositioned the doomed workspace, ended its proved shell, and left every concurrent focus sample on the exact anchor with no corrective `tab focus` issued. + +Two real-hardware conditions were required for the pane-death path to engage and are now encoded in the adapter and its unit fixtures: BSD `ps` reports a login shell's `comm` as `-zsh`, and an idle shell transiently hosts a prompt helper (starship) as a second foreground process immediately after a `workspace.move` relayout, which the bounded settle window absorbs. + +The rules match the v0.7.5 tag source (`close_selected_workspace` reassigns focus from the closing workspace's index; `handle_pane_died` only clamps the stale focused index), and the upstream default branch resolves both paths by workspace id (PR #1877, commit `165dca45`, for the explicit close; PR #1912, commit `a979916`, for pane death), so the plan degrades to a harmless reorder-then-remove once a release carries them. + +The full projection and restored-shell suites were re-run the same day on the same version with the updated close path; the presentation suite completed with `real Herdr lab validation completed on Herdr 0.7.5 with the default-session tripwire intact`, and the restored-shell cleanup guarantee above was unchanged. + +The teardown-level record-retention gate was verified on 2026-07-28 with metadata fixtures and a live contending lock holder: + +```sh +tests/fm-teardown.test.sh +tests/fm-backend-herdr.test.sh +``` + +Observed guarantees: a contended presentation lock refused the teardown before the isolated copy was returned, with the task branch, every durable record, and the endpoint intact and no pane close attempted; the retry after the contention cleared returned the copy, closed the pane under the lock, and removed the records; an unknown structured-presence result after an attempted projected close retained the journal and every record with a nonzero exit; and every presence-gate mode accepted only a structured not-found as gone. + +The same fixtures verified three further boundaries on 2026-07-29: missing or malformed endpoint identity and an unparseable pane presence refused record removal with everything retained; the SIGKILL escalation re-read the exact pane's process information and refused to signal when a different shell pid owned the pane, falling back to the plain close with the original process untouched; and a reposition whose removal then failed on every path restored the exact original workspace order through a second verified move and reported the close as failed. + +The teardown fixture was re-run on 2026-07-31 after extending the same fail-closed boundary through forced secondmate cleanup, including recursive cleanup of a nested secondmate whose Herdr grandchild close remains unconfirmed. + +Observed output: + +```text +ok - forced secondmate teardown preflights every Herdr child before cleanup mutation +ok - forced secondmate teardown retains Herdr child identity until exact pane disappearance +ok - forced teardown retains a nested secondmate home and its grandchild's Herdr identity when the grandchild close is unconfirmed +``` + ### Composer and operational input Real captures verified these active distinctions: diff --git a/docs/verification/stow-memory.md b/docs/verification/stow-memory.md new file mode 100644 index 00000000000..39e61eac4fb --- /dev/null +++ b/docs/verification/stow-memory.md @@ -0,0 +1,217 @@ +# Startup-memory `/stow` verification + +Audience: maintainer verification. + +This record supports the active bounded-memory and whole-file curation guarantees for Firstmate's internal `/stow` skill. +[`docs/configuration.md`](../configuration.md) owns the current operator-facing setting and estimate. +The internal skill owns curation and completion-receipt behavior. +Task chronology, fixture paths, and delivery evidence remain outside this record. + +## Synthetic real-agent pass + +The development-only real-agent pass ran on 2026-07-30 with Pi 0.82.0 on `openai-codex/gpt-5.6-terra` at medium thinking. +It used disposable primary and secondmate-shaped `FM_HOME` directories under the repository worktree only. +No live Firstmate memory, project data, credential content, or external system was placed in either fixture or prompt. +The following exact Bash shell body created the sanitized fixtures, invoked the model-qualified skill twice per home, and captured reports, hashes, and file modes: + +```bash +set -eu +VERIFY_ROOT=$(mktemp -d "$PWD/.stow-verification.XXXXXX") +RUNTIME_ROOT="$VERIFY_ROOT/runtime-root" +PRIMARY="$VERIFY_ROOT/primary" +SECONDMATE="$VERIFY_ROOT/secondmate" +SECONDMATE_ID=stow-verification +mkdir -p "$RUNTIME_ROOT" "$PRIMARY/config" "$PRIMARY/data" \ + "$SECONDMATE/bin" "$SECONDMATE/config" "$SECONDMATE/data" +printf '%s\n' 350 >"$PRIMARY/config/startup-memory-budget" +printf '%s\n' "$SECONDMATE_ID" >"$SECONDMATE/.fm-secondmate-home" +printf '%s\n' '# Synthetic Firstmate home' >"$SECONDMATE/AGENTS.md" + +file_mode() { + if [ "$(uname)" = Darwin ]; then + stat -f %Lp "$1" + else + stat -c %a "$1" + fi +} + +record_shared_state() { + label=$1 + path=$2 + printf '%s sha256=%s mode=%s\n' "$label" \ + "$(shasum -a 256 "$path" | awk '{print $1}')" \ + "$(file_mode "$path")" +} + +cat >"$PRIMARY/data/captain.md" <<'EOF' +# Captain + +## Current preferences + +- Prefer the simplest direct end-to-end operational path. +- Preserve unique current facts when compacting memory. +- Use plain dashes in prose. + +## Duplicate and superseded material + +- Prefer the simplest direct end-to-end operational path. +- Old policy: build a wrapper before every one-off operation. +- Old policy copy: always build a wrapper for one-off work. +- Stale tool path: `/opt/old-firstmate/bin/fm`. +- Stale release version: 0.41.0. +- Completed task: migrated the demo fixture on Monday. +- Completed task detail: checked the demo fixture again on Tuesday. +- Metric from the completed task: 47 records moved. +EOF + +cat >"$PRIMARY/data/captain-shared.md" <<'EOF' +# Shared captain preferences + +This file is main-authoritative in the main firstmate home. +In secondmate homes it is read-only in secondmate homes and must not be edited there. +Route new captain-preference discoveries to the main firstmate through marked status or a document pointer. + +- Never expose secrets or weaken an accepted safety boundary. +- Prefer the simplest direct end-to-end operational path. +- Superseded policy: secondmates may rewrite shared memory when convenient. +- Duplicate safety note: do not expose secrets. +EOF + +cat >"$PRIMARY/data/learnings.md" <<'EOF' +# Learnings + +- Stable fact: startup-memory configuration is documented in `docs/configuration.md`. +- Authoritative pointer: incident detail belongs in `data/reports/synthetic-incident.md`. +- Stable fact copy: consult `docs/configuration.md` for startup-memory configuration. +- Completed chronology: first the synthetic incident was detected, then triaged, then assigned. +- Completed chronology continued: a patch was drafted, reviewed, merged, and announced. +- Old metric: the discarded prototype used 812 estimated tokens. +- Stale path: the discarded prototype lived at `/tmp/old-memory-prototype`. +- Superseded alternative: maintain both a JSON memory database and Markdown files. +- Report-sized procedure: create a staging directory, enumerate every file, copy each file, compare every line, write a status ledger, notify all operators, archive the ledger, and repeat the entire sequence after every prompt. +EOF + +FM_HOME="$PRIMARY" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/primary.before.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$PRIMARY/data/$file" +done >"$VERIFY_ROOT/primary.before.sha256" + +FM_HOME="$PRIMARY" pi -p --no-session --no-extensions --no-context-files \ + --model openai-codex/gpt-5.6-terra --thinking medium \ + --skill .agents/skills/stow/SKILL.md \ + 'Invoke /stow now against only the disposable synthetic Firstmate home in $FM_HOME. There are no new session facts to file. Follow every requirement in the loaded stow skill. Run the repository-owned bin/fm-startup-memory-budget.sh report command, with the existing FM_HOME environment, before and after curation; that executable is the only permitted path outside $FM_HOME. Retain the exact before total, preserve the complete main-authoritative routing header in data/captain-shared.md, and make the completion receipt state the effective budget, exact before and after totals, an action for each of the three files, every exception, and reset safety. Inspect all three startup-memory files completely, preserve every unique current preference, authority or safety boundary, stable fact, and authoritative pointer, and consolidate the supplied duplicate, superseded, stale, chronological, metric, and report-sized material. Do not access or modify any other home, credential, project data, or external system.' \ + >"$VERIFY_ROOT/primary.pass1.out" +FM_HOME="$PRIMARY" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/primary.after.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$PRIMARY/data/$file" +done >"$VERIFY_ROOT/primary.after.sha256" + +FM_HOME="$PRIMARY" pi -p --no-session --no-extensions --no-context-files \ + --model openai-codex/gpt-5.6-terra --thinking medium \ + --skill .agents/skills/stow/SKILL.md \ + 'Invoke /stow now against only the disposable synthetic Firstmate home in $FM_HOME. There are no new session facts to file. Follow every requirement in the loaded stow skill. Run the repository-owned bin/fm-startup-memory-budget.sh report command, with the existing FM_HOME environment, before and after curation; that executable is the only permitted path outside $FM_HOME. Retain the exact before total, preserve the complete main-authoritative routing header in data/captain-shared.md, and make the completion receipt state the effective budget, exact before and after totals, an action for each of the three files, every exception, and reset safety. Inspect all three startup-memory files completely, preserve every unique current preference, authority or safety boundary, stable fact, and authoritative pointer, and consolidate the supplied duplicate, superseded, stale, chronological, metric, and report-sized material. Do not access or modify any other home, credential, project data, or external system.' \ + >"$VERIFY_ROOT/primary.pass2.out" +FM_HOME="$PRIMARY" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/primary.repeat.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$PRIMARY/data/$file" +done >"$VERIFY_ROOT/primary.repeat.sha256" + +cat >"$SECONDMATE/data/captain.md" <<'EOF' +# Secondmate captain memory + +- Current preference: report concrete blockers instead of guessing. +- Current preference copy: never guess when a concrete blocker can be reported. +- Shared overlap: never expose secrets. +- Superseded preference: silently infer missing configuration. +- Stale version: the fleet uses 0.41.0. +- Completed task: inspected the synthetic queue yesterday. +- Completed task detail: closed the synthetic queue inspection after 19 checks. +EOF + +cat >"$SECONDMATE/data/learnings.md" <<'EOF' +# Secondmate learnings + +- Unique current learning: inherited shared memory counts against the local total. +- Authoritative pointer: startup-memory behavior is documented in `docs/configuration.md`. +- Duplicate learning: include inherited shared memory in the local total. +- Stale path: `/tmp/secondmate-memory-v1`. +- Superseded alternative: copy shared facts into every local file. +- Completed chronology: opened the sample, measured it, discussed it, revised it, remeasured it, and closed it. +- Old metric: the sample once measured 604 estimated tokens. +- Report-sized procedure: take a snapshot, copy it to a ledger, annotate every old measurement, preserve every discarded alternative, append a timestamp, and repeat after each completed task. +EOF + +FM_ROOT="$RUNTIME_ROOT" +FM_HOME="$PRIMARY" +. bin/fm-ff-lib.sh +. bin/fm-config-inherit-lib.sh +validate_secondmate_home "$SECONDMATE_ID" "$SECONDMATE" +printf 'secondmate_validation=accepted id=%s home=%s\n' \ + "$SECONDMATE_ID" "$VALIDATED_HOME" >"$VERIFY_ROOT/inheritance.out" +FM_CONFIG_INHERIT_REPORT="$VERIFY_ROOT/inheritance.report" \ + propagate_secondmate_inheritance \ + "$PRIMARY" "$VALIDATED_HOME" "$PRIMARY/config" "$PRIMARY/data" +cat "$VERIFY_ROOT/inheritance.report" >>"$VERIFY_ROOT/inheritance.out" +cmp -s "$PRIMARY/data/captain-shared.md" \ + "$SECONDMATE/data/captain-shared.md" +record_shared_state inherited "$SECONDMATE/data/captain-shared.md" \ + >>"$VERIFY_ROOT/inheritance.out" + +FM_HOME="$SECONDMATE" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/secondmate.before.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$SECONDMATE/data/$file" +done >"$VERIFY_ROOT/secondmate.before.sha256" +record_shared_state before "$SECONDMATE/data/captain-shared.md" \ + >"$VERIFY_ROOT/secondmate.shared-state" + +FM_HOME="$SECONDMATE" pi -p --no-session --no-extensions --no-context-files \ + --model openai-codex/gpt-5.6-terra --thinking medium \ + --skill .agents/skills/stow/SKILL.md \ + 'Invoke /stow now against only the validated disposable synthetic secondmate home in $FM_HOME. There are no new session facts to file. Follow every requirement in the loaded stow skill. Run the repository-owned bin/fm-startup-memory-budget.sh report command, with the existing FM_HOME environment, before and after curation; that executable is the only permitted path outside $FM_HOME. Retain the exact before total, and make the completion receipt state the effective budget, exact before and after totals, an action for each of the three files, every exception, and reset safety. Inspect all three startup-memory files completely, keep data/captain-shared.md byte-identical and filesystem read-only because it was installed through primary-authoritative inheritance, preserve every unique current preference, stable learning, and authoritative pointer, and consolidate the supplied duplicate, superseded, stale, chronological, metric, overlap, and report-sized material in editable local memory. Do not access or modify any other home, credential, project data, or external system.' \ + >"$VERIFY_ROOT/secondmate.pass1.out" +FM_HOME="$SECONDMATE" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/secondmate.after.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$SECONDMATE/data/$file" +done >"$VERIFY_ROOT/secondmate.after.sha256" +record_shared_state after "$SECONDMATE/data/captain-shared.md" \ + >>"$VERIFY_ROOT/secondmate.shared-state" + +FM_HOME="$SECONDMATE" pi -p --no-session --no-extensions --no-context-files \ + --model openai-codex/gpt-5.6-terra --thinking medium \ + --skill .agents/skills/stow/SKILL.md \ + 'Invoke /stow now against only the validated disposable synthetic secondmate home in $FM_HOME. There are no new session facts to file. Follow every requirement in the loaded stow skill. Run the repository-owned bin/fm-startup-memory-budget.sh report command, with the existing FM_HOME environment, before and after curation; that executable is the only permitted path outside $FM_HOME. Retain the exact before total, and make the completion receipt state the effective budget, exact before and after totals, an action for each of the three files, every exception, and reset safety. Inspect all three startup-memory files completely, keep data/captain-shared.md byte-identical and filesystem read-only because it was installed through primary-authoritative inheritance, preserve every unique current preference, stable learning, and authoritative pointer, and consolidate the supplied duplicate, superseded, stale, chronological, metric, overlap, and report-sized material in editable local memory. Do not access or modify any other home, credential, project data, or external system.' \ + >"$VERIFY_ROOT/secondmate.pass2.out" +FM_HOME="$SECONDMATE" bin/fm-startup-memory-budget.sh report \ + >"$VERIFY_ROOT/secondmate.repeat.report" +for file in captain.md captain-shared.md learnings.md; do + shasum -a 256 "$SECONDMATE/data/$file" +done >"$VERIFY_ROOT/secondmate.repeat.sha256" +record_shared_state repeat "$SECONDMATE/data/captain-shared.md" \ + >>"$VERIFY_ROOT/secondmate.shared-state" +``` + +Bounded observed output: + +```text +secondmate_validation=accepted id=stow-verification +startup-memory-budget pushed +data/captain-shared.md pushed +inherited sha256=d08ce8e35b17c8342773d551b5c1551a5a6ded5f45ab0f7ed5b6ef91ea1d408c mode=444 +primary: 699 -> 219 estimated tokens against a 350-token budget +primary repeat: 219 -> 219; all three files byte-identical +secondmate: 518 -> 192 estimated tokens against a 350-token budget +secondmate repeat: 192 -> 192; all three files byte-identical +before sha256=d08ce8e35b17c8342773d551b5c1551a5a6ded5f45ab0f7ed5b6ef91ea1d408c mode=444 +after sha256=d08ce8e35b17c8342773d551b5c1551a5a6ded5f45ab0f7ed5b6ef91ea1d408c mode=444 +repeat sha256=d08ce8e35b17c8342773d551b5c1551a5a6ded5f45ab0f7ed5b6ef91ea1d408c mode=444 +``` + +The first pass preserved current preferences, shared-memory and safety authority, a stable operating fact, and authoritative configuration and incident-report pointers while removing duplicate, superseded, stale, and chronological material. +The secondmate fixture passed the production home validator before the existing inheritance owner installed the main-authoritative file read-only. +Both secondmate passes preserved its unique local preference and learning while leaving those inherited bytes and mode untouched. +This verifies the real instruction path consolidates to budget, reports truthful deltas, preserves the primary-owned shared boundary, and does not grow on an identical second pass. diff --git a/docs/verification/supervision.md b/docs/verification/supervision.md index 63e0ebaa1a5..cddb920002e 100644 --- a/docs/verification/supervision.md +++ b/docs/verification/supervision.md @@ -60,6 +60,40 @@ The Ahoy first-message boundary was reverified on 2026-07-22 with Pi 0.81.1 and Marked current operational input and the two exact legacy compatibility shapes selected Bearings, while genuine near-miss captain messages remained real boundaries. The detailed reconciliation and task chronology stay in the private audit report and PR evidence. +## Semantic busy state + +The per-adapter semantic sources behind [`bin/fm-busy-lib.sh`](../../bin/fm-busy-lib.sh) were live-verified on 2026-07-28 against firstmate-launched workers wired exactly as `fm-spawn` writes them. +Each pass polled `state/<id>.busy-state` while a real turn ran. + +| Harness | Version verified | Semantic source | Observed result | +| --- | --- | --- | --- | +| Pi | 0.82.0 | Extension `agent_start` / `agent_settled` with `ctx.isIdle()` | The spawn seed `busy source=fm-spawn`, then `busy source=pi-ext event=agent-start`, then `idle source=pi-ext event=agent-settled`; the turn-end marker was still touched. | +| OpenCode | 1.17.18 | Plugin `session.status` | In a real TUI pane: seed, then `busy source=opencode-plugin event=session-busy`, then `idle source=opencode-plugin event=session-status-idle`. | +| Claude | 2.1.220 (Claude Code) | Hooks `UserPromptSubmit`, `Stop`, `StopFailure`, `SessionEnd` | `UserPromptSubmit` fired for the argv launch prompt and each steer, and `Stop` closed every completed turn. A mid-stream Escape interrupt fired no closing hook, which is why the firstmate-controlled clear exists. `StopFailure` and `SessionEnd` are wired from the four hook names present in the installed binary; only the abnormal paths they cover were not reproduced live. | +| Codex | codex-cli 0.145.0 | None usable | See below; classifies `unknown codex-unverified`. | +| Kimi (standalone) | not installed | None usable | No binary on `PATH`, so the gate stays closed and it classifies `unknown kimi-unverified`. | +| Grok | 0.2.112 | Isolated rendered-tail fallback | Retained unconverted; the approved audit could not credit a live structured-lifecycle run. | + +Codex was probed two ways, both refused: + +```sh +codex app-server daemon start +codex exec --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust 'Reply with exactly PROBE2.' +``` + +The daemon refused with `managed standalone Codex install not found`, and an interactive TUI worker neither starts nor attaches to the app-server control socket, so no client can observe its turns. +Firstmate-written project hooks under `<worktree>/.codex/hooks.json` fired for neither an interactive pane whose directory trust was granted nor `codex exec`, in both cases with `--dangerously-bypass-hook-trust`, while global `~/.codex/hooks.json` `SessionStart` hooks fired in the same runs. +Codex also exposes no `StopFailure` hook, so an API-error turn end would need separate coverage even after hook discovery works. +The app-server protocol schema does define the required lifecycle (`turn/started`, plus a `turn/completed` status of `completed`, `interrupted`, `failed`, or `inProgress`), so the gate is a reachability problem rather than a protocol gap. + +Deterministic entry points: + +```sh +tests/fm-busy-state.test.sh +tests/fm-busy-adapter-wiring.test.sh +tests/fm-crew-state.test.sh +``` + ## Turn-end guard The direct and passive mechanisms were validated across all five harnesses on 2026-07-08 through 2026-07-12, with Claude's replacement Stop-owned path revalidated on 2026-07-24. diff --git a/docs/zellij-backend.md b/docs/zellij-backend.md index 9b6b05acd94..536bd062633 100644 --- a/docs/zellij-backend.md +++ b/docs/zellij-backend.md @@ -91,7 +91,8 @@ Real test cleanup uses only an isolated non-`firstmate` session and the guard in - Zellij is experimental and explicit-only. - All homes share one session and tab bar; scoped titles prevent cross-home identity collisions but do not create per-home visual containers. -- There is no native busy or push-event signal, so supervision uses capture/hash and busy-regex polling. +- There is no native busy or push-event signal, so supervision uses capture/hash polling for screen changes and each harness adapter's semantic lifecycle for worker state. + Grok alone retains its isolated rendered-tail fallback. - There is no verified agent-process liveness signal, so a dead Zellij secondmate is reported inconclusive rather than auto-respawned. - New-tab focus restoration has a narrow visible race. - CLI exit status is not meaningful; a target can still disappear after structural readiness checks. diff --git a/tests/fixtures/quota-array-dispatch/cases.json b/tests/fixtures/quota-array-dispatch/cases.json deleted file mode 100644 index c6fc3c3a867..00000000000 --- a/tests/fixtures/quota-array-dispatch/cases.json +++ /dev/null @@ -1,394 +0,0 @@ -{ - "cases": [ - { - "id": "higher-raw-ahead-vs-lower-raw-sustainable", - "expect": "B", - "reason": "prefer sustainable pace over higher raw headroom with conservation pressure", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "strong-a", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 80, - "paceStatus": "ahead", - "aheadWindowIds": ["weekly"], - "worstReserve": -12.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "strong-b", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 55, - "paceStatus": "behind", - "aheadWindowIds": [], - "worstReserve": 18.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "mixed-effective-with-ahead-bound", - "expect": "B", - "reason": "mixed with aheadWindowIds is conservation pressure", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "mixed-a", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 75, - "paceStatus": "mixed", - "aheadWindowIds": ["seven_day"], - "worstReserve": -8.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "steady-b", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 60, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "worstReserve": 0.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "both-ahead-least-negative-reserve", - "expect": "B", - "reason": "among pressured candidates prefer least-negative worst reserve", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "pressured-a", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 50, - "paceStatus": "ahead", - "aheadWindowIds": ["weekly"], - "worstReserve": -22.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "pressured-b", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 48, - "paceStatus": "ahead", - "aheadWindowIds": ["weekly"], - "worstReserve": -5.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "ahead-bounding-window-overrides-neutral-effective-summary", - "expect": "B", - "reason": "an ahead applicable bounding window creates conservation pressure even when the effective summary is neutral", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "bounded-a", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 72, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "boundingWindows": [ - { - "id": "weekly", - "paceStatus": "ahead", - "reservePercentPoints": -9.0 - } - ], - "worstReserve": -9.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "steady-b", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 58, - "paceStatus": "behind", - "aheadWindowIds": [], - "boundingWindows": [ - { - "id": "weekly", - "paceStatus": "behind", - "reservePercentPoints": 7.0 - } - ], - "worstReserve": 7.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "known-sustainable-vs-unknown", - "expect": "A", - "reason": "prefer known sustainable evidence over unknown pace", - "candidates": [ - { - "id": "A", - "harness": "codex", - "model": "known-a", - "effort": "medium", - "fit": "comparable", - "reasoningClass": "standard", - "tight": false, - "rawHeadroom": 40, - "paceStatus": "behind", - "aheadWindowIds": [], - "worstReserve": 10.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "claude", - "model": "unknown-b", - "effort": "medium", - "fit": "comparable", - "reasoningClass": "standard", - "tight": false, - "rawHeadroom": 42, - "paceStatus": "unknown", - "aheadWindowIds": [], - "worstReserve": null, - "unknownPace": true, - "paceAvailable": true - } - ] - }, - { - "id": "select-pi-xai-before-authentication", - "expect": "pi-xai", - "reason": "an unauthenticated standalone Grok candidate cannot block selected authenticated Pi/xAI", - "candidates": [ - { - "id": "pi-xai", - "harness": "pi", - "model": "xai/grok-4.5", - "provider": "xai", - "authenticationSurface": "Pi xAI OAuth", - "authAvailable": true, - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 55, - "paceStatus": "behind", - "aheadWindowIds": [], - "worstReserve": 15.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "standalone-grok", - "harness": "grok", - "model": "grok-4.5", - "provider": "grok", - "authenticationSurface": "Grok Build CLI", - "authAvailable": false, - "authFailure": "Grok Build CLI login missing", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 80, - "paceStatus": "ahead", - "aheadWindowIds": ["weekly"], - "worstReserve": -12.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "all-tight-strongest-reasoning", - "expect": "A", - "reason": "preserve strongest-reasoning class when every candidate is tight", - "requiredReasoningClass": "strong", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "strong-tight", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": true, - "rawHeadroom": 8, - "paceStatus": "behind", - "aheadWindowIds": [], - "worstReserve": 2.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "weaker-roomier", - "effort": "medium", - "fit": "comparable", - "reasoningClass": "standard", - "tight": true, - "rawHeadroom": 25, - "paceStatus": "behind", - "aheadWindowIds": [], - "worstReserve": 12.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "genuine-tie-captain-choice", - "expectError": "genuine tie requires captain choice", - "reason": "report genuine ties instead of selecting by array order or harness identity", - "candidates": [ - { - "id": "A", - "harness": "claude", - "model": "same-model", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 50, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "worstReserve": 0.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "B", - "harness": "codex", - "model": "same-model", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 50, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "worstReserve": 0.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "genuine-tie-reversed-array-order", - "expectError": "genuine tie requires captain choice", - "reason": "reversing a genuine tie must still require captain choice", - "candidates": [ - { - "id": "B", - "harness": "codex", - "model": "same-model", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 50, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "worstReserve": 0.0, - "unknownPace": false, - "paceAvailable": true - }, - { - "id": "A", - "harness": "claude", - "model": "same-model", - "effort": "high", - "fit": "comparable", - "reasoningClass": "strong", - "tight": false, - "rawHeadroom": 50, - "paceStatus": "on_pace", - "aheadWindowIds": [], - "worstReserve": 0.0, - "unknownPace": false, - "paceAvailable": true - } - ] - }, - { - "id": "schema-v2-absent-pace", - "expect": "A", - "reason": "absent pace degrades to raw headroom without fabricating pace health", - "candidates": [ - { - "id": "A", - "harness": "codex", - "model": "legacy-a", - "effort": "medium", - "fit": "comparable", - "reasoningClass": "standard", - "tight": false, - "rawHeadroom": 70, - "paceStatus": null, - "aheadWindowIds": [], - "worstReserve": null, - "unknownPace": false, - "paceAvailable": false - }, - { - "id": "B", - "harness": "claude", - "model": "legacy-b", - "effort": "medium", - "fit": "comparable", - "reasoningClass": "standard", - "tight": false, - "rawHeadroom": 40, - "paceStatus": null, - "aheadWindowIds": [], - "worstReserve": null, - "unknownPace": false, - "paceAvailable": false - } - ] - } - ] -} diff --git a/tests/fixtures/quota-array-dispatch/schema-v3-shape.json b/tests/fixtures/quota-array-dispatch/schema-v3-shape.json deleted file mode 100644 index a79f86aca32..00000000000 --- a/tests/fixtures/quota-array-dispatch/schema-v3-shape.json +++ /dev/null @@ -1,103 +0,0 @@ -{ - "schemaVersion": 3, - "generatedAt": "1970-01-01T00:00:00.000Z", - "providers": [ - { - "provider": "claude", - "label": "Claude", - "source": "test", - "plan": "test", - "windows": [ - { - "id": "five_hour", - "label": "session", - "kind": "session", - "percentUsed": 20, - "percentRemaining": 80, - "windowSeconds": 18000, - "pace": { - "status": "behind", - "timeRemainingPercent": 40.0, - "elapsedPercent": 60.0, - "reservePercentPoints": 40.0 - } - }, - { - "id": "seven_day", - "label": "week", - "kind": "weekly", - "percentUsed": 55, - "percentRemaining": 45, - "windowSeconds": 604800, - "pace": { - "status": "ahead", - "timeRemainingPercent": 60.0, - "elapsedPercent": 40.0, - "reservePercentPoints": -15.0 - } - } - ], - "quotaSemantics": { - "status": "known", - "description": "sanitized representative schemaVersion 3 shape", - "effectiveAvailability": [ - { - "scope": "all_models", - "status": "known", - "effectivePercentRemaining": 45, - "boundedBy": ["five_hour", "seven_day"], - "limitingWindowIds": ["seven_day"], - "pace": { - "status": "mixed", - "aheadWindowIds": ["seven_day"], - "behindWindowIds": ["five_hour"], - "worstReservePercentPoints": -15.0, - "worstReserveWindowId": "seven_day" - } - } - ] - } - }, - { - "provider": "codex", - "label": "Codex", - "source": "test", - "plan": "test", - "windows": [ - { - "id": "weekly", - "label": "week", - "kind": "weekly", - "percentUsed": 30, - "percentRemaining": 70, - "windowSeconds": 604800, - "pace": { - "status": "behind", - "timeRemainingPercent": 50.0, - "elapsedPercent": 50.0, - "reservePercentPoints": 20.0 - } - } - ], - "quotaSemantics": { - "status": "known", - "description": "sanitized representative schemaVersion 3 shape", - "effectiveAvailability": [ - { - "scope": "all_models", - "status": "known", - "effectivePercentRemaining": 70, - "boundedBy": ["weekly"], - "limitingWindowIds": ["weekly"], - "pace": { - "status": "behind", - "behindWindowIds": ["weekly"], - "worstReservePercentPoints": 20.0, - "worstReserveWindowId": "weekly" - } - } - ] - } - } - ] -} diff --git a/tests/fm-afk-inject-herdr-e2e.test.sh b/tests/fm-afk-inject-herdr-e2e.test.sh index 644d015086f..9c5c66c5e88 100755 --- a/tests/fm-afk-inject-herdr-e2e.test.sh +++ b/tests/fm-afk-inject-herdr-e2e.test.sh @@ -41,6 +41,11 @@ command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the her # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + fail() { printf 'not ok - %s\n' "$1" >&2; cleanup_all; exit 1; } pass() { printf 'ok - %s\n' "$1"; } diff --git a/tests/fm-afk-launch.test.sh b/tests/fm-afk-launch.test.sh index 2697e388670..eea8acf4abd 100755 --- a/tests/fm-afk-launch.test.sh +++ b/tests/fm-afk-launch.test.sh @@ -307,12 +307,23 @@ unit_signal_exits_with_lock_cleanup() { : > "$2" ' _ "$LAUNCH" "$marker" & child=$! - for _ in $(seq 1 40); do - [ -d "$st/state/.afk-launch.lock" ] && break + # Signal only once the lifecycle actually holds its lock. Killing before the + # lock exists tests nothing, and on a loaded machine it used to race: the + # lock could be created just after the kill and outlive the process. + local locked=0 _ + for _ in $(seq 1 100); do + if [ -d "$st/state/.afk-launch.lock" ]; then locked=1; break; fi sleep 0.05 done + [ "$locked" = 1 ] || fail "launcher signal: lifecycle never acquired its lock to interrupt" kill -TERM "$child" 2>/dev/null || true wait "$child" 2>/dev/null || true + # The signal handler releases the lock as it exits; give that removal a + # bounded settle rather than sampling the instant `wait` returns. + for _ in $(seq 1 100); do + [ -e "$st/state/.afk-launch.lock" ] || break + sleep 0.05 + done if [ ! -e "$marker" ] && [ ! -e "$st/state/.afk-launch.lock" ]; then pass "launcher signal: TERM exits and releases the lifecycle lock" else diff --git a/tests/fm-backend-autodetect-smoke.test.sh b/tests/fm-backend-autodetect-smoke.test.sh index 4fd95a80ae6..c75057a2cf9 100755 --- a/tests/fm-backend-autodetect-smoke.test.sh +++ b/tests/fm-backend-autodetect-smoke.test.sh @@ -43,6 +43,14 @@ command -v treehouse >/dev/null 2>&1 || { echo "skip: treehouse not found (requi export FM_GATE_REFUSE_BYPASS=1 +# shellcheck source=tests/herdr-test-safety.sh +. "$ROOT/tests/herdr-test-safety.sh" +# This suite asserts that HERDR_ENV=1 alone selects the backend, and it runs +# against its own isolated lab session. A Herdr pane inherited from the terminal +# it was launched in must not follow spawn into that session as a cross-session +# parent identity; the spawn below sets HERDR_ENV explicitly. +herdr_forget_inherited_pane + # TMP_ROOT is physically resolved (mktemp -d "$(pwd -P)"-relative) to keep this # real-herdr smoke fixture free of unrelated OS symlink noise. # The old fm-spawn bug that originally motivated this fixture shape was fixed in diff --git a/tests/fm-backend-herdr-eventwait-smoke.test.sh b/tests/fm-backend-herdr-eventwait-smoke.test.sh index 5616a5bc751..b383176d7d1 100755 --- a/tests/fm-backend-herdr-eventwait-smoke.test.sh +++ b/tests/fm-backend-herdr-eventwait-smoke.test.sh @@ -25,6 +25,11 @@ command -v python3 >/dev/null 2>&1 || { echo "skip: python3 not found (required # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + SESSION="fm-lab-eventwait-smoke-$$" export HERDR_SESSION="$SESSION" SCRATCH= diff --git a/tests/fm-backend-herdr-focus-flash-e2e.test.sh b/tests/fm-backend-herdr-focus-flash-e2e.test.sh new file mode 100755 index 00000000000..6145dec365b --- /dev/null +++ b/tests/fm-backend-herdr-focus-flash-e2e.test.sh @@ -0,0 +1,205 @@ +#!/usr/bin/env bash +# Real-Herdr regression for the projected-cleanup focus flash (upstream +# ogulcancelik/herdr#1621 family, live on 0.7.5 stable). +# Part A reproduces the OLD path: an explicit last-pane close that empties a +# non-focused workspace steals the focused workspace. +# Part B proves the mitigation: the focus-safe emptying-close plan +# (repositioning move plus pane-death removal) removes the doomed workspace +# with no focus change and no corrective tab focus at all. +# On a future release whose explicit close preserves focus, Part A records +# that and Part B keeps outcome-only assertions, so no version is guessed. +# Every CLI operation is routed through one guarded named non-default lab, and +# lab teardown verifies that the default fleet session is byte-identical. +set -u + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +HERDR_LAB_HELPER=${HERDR_LAB_HELPER:-$ROOT/bin/fm-herdr-lab.sh} + +fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; } +pass() { printf 'ok - %s\n' "$1"; } + +command -v herdr >/dev/null 2>&1 || { echo 'skip: herdr not found'; exit 0; } +command -v jq >/dev/null 2>&1 || { echo 'skip: jq not found'; exit 0; } +command -v python3 >/dev/null 2>&1 || { echo 'skip: python3 not found'; exit 0; } +[ -x "$HERDR_LAB_HELPER" ] || { echo "skip: Herdr lab helper not executable at $HERDR_LAB_HELPER"; exit 0; } + +HERDR_ORIGINAL_PATH=$PATH +TMP_ROOT=$(mktemp -d "$(cd "${TMPDIR:-/tmp}" && pwd -P)/fm-herdr-focus-flash-e2e.XXXXXX") +FAKEBIN="$TMP_ROOT/fakebin" +mkdir -p "$FAKEBIN" + +HERDR_LAB_SESSION=$("$HERDR_LAB_HELPER" name fm-herdr-focus-flash-regression-r1) +export HERDR_LAB_HELPER HERDR_LAB_SESSION HERDR_ORIGINAL_PATH +B_SAMPLER_PID= +B_SAMPLER_STOP= +cleanup() { + local status=$? + if [ -n "$B_SAMPLER_STOP" ]; then + : > "$B_SAMPLER_STOP" + fi + if [ -n "$B_SAMPLER_PID" ]; then + wait "$B_SAMPLER_PID" 2>/dev/null || true + fi + env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" teardown "$HERDR_LAB_SESSION" || status=1 + rm -rf "$TMP_ROOT" + exit "$status" +} +trap cleanup EXIT +"$HERDR_LAB_HELPER" provision "$HERDR_LAB_SESSION" + +# Keep the lab helper as the only CLI transport. Production adapter calls have +# already appended the exact session; this shim strips that pair, refuses every +# other caller-supplied session, and delegates the command to helper run. +cat > "$FAKEBIN/herdr" <<'SH' +#!/usr/bin/env bash +set -u +args=("$@") +last=$((${#args[@]} - 1)) +flag=$((last - 1)) +if [ "${#args[@]}" -ge 2 ] \ + && [ "${args[$flag]}" = --session ] \ + && [ "${args[$last]}" = "$HERDR_LAB_SESSION" ]; then + unset "args[$last]" "args[$flag]" +fi +set -- "${args[@]}" +for arg in "$@"; do + case "$arg" in --session|--session=*) exit 9 ;; esac +done +exec env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESSION" "$@" +SH +chmod +x "$FAKEBIN/herdr" + +lab() { env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESSION" "$@"; } +mkws() { # <label> -> "<workspace_id> <tab_id> <pane_id>" + lab workspace create --cwd "$ROOT" --label "$1" --no-focus \ + | jq -er '"\(.result.workspace.workspace_id) \(.result.tab.tab_id) \(.result.root_pane.pane_id)"' +} +focus_snapshot() { + local list workspace tab tabs + list=$(lab workspace list) || return 1 + workspace=$(printf '%s' "$list" | jq -er '[.result.workspaces[] | select(.focused == true)] | select(length == 1) | .[0].workspace_id') || return 1 + tab=$(printf '%s' "$list" | jq -er --arg workspace "$workspace" '[.result.workspaces[] | select(.workspace_id == $workspace)] | select(length == 1) | .[0].active_tab_id') || return 1 + tabs=$(lab tab list --workspace "$workspace") || return 1 + printf '%s' "$tabs" | jq -e --arg tab "$tab" '([.result.tabs[] | select(.focused == true)] | length) == 1 and ([.result.tabs[] | select(.focused == true)][0].tab_id == $tab)' >/dev/null || return 1 + printf '%s\t%s' "$workspace" "$tab" +} +ws_order() { lab workspace list | jq -er '[.result.workspaces[].workspace_id] | join(",")'; } +wait_ws_gone() { # <workspace_id> + local i=0 + while [ "$i" -lt 80 ]; do + lab workspace get "$1" >/dev/null 2>&1 || return 0 + sleep 0.1 + i=$((i + 1)) + done + return 1 +} + +# --- Part A: the OLD path (plain explicit close) steals focus on 0.7.5 ----- +# The spacer keeps the focused anchor away from the doomed workspace's right +# neighbor, where the 0.7.5 explicit close would land by coincidence. +read -r A_DOOMED_WS _ A_DOOMED_PANE <<<"$(mkws flash-a-doomed)" || fail 'could not create the Part A doomed workspace' +read -r _ _ _ <<<"$(mkws flash-a-spacer)" || fail 'could not create the Part A spacer workspace' +read -r A_ANCHOR_WS A_ANCHOR_TAB _ <<<"$(mkws flash-a-anchor)" || fail 'could not create the Part A anchor workspace' +read -r _ _ _ <<<"$(mkws flash-a-tail)" || fail 'could not create the Part A tail workspace' +lab tab focus "$A_ANCHOR_TAB" >/dev/null || fail 'could not focus the Part A anchor' +A_BEFORE=$(focus_snapshot) || fail 'could not capture the Part A pre-close focus' +[ "$A_BEFORE" = "$(printf '%s\t%s' "$A_ANCHOR_WS" "$A_ANCHOR_TAB")" ] \ + || fail 'Part A anchor focus does not match the intended workspace and tab' +lab pane close "$A_DOOMED_PANE" >/dev/null || fail 'Part A explicit close failed' +wait_ws_gone "$A_DOOMED_WS" || fail 'Part A doomed workspace survived the explicit close' +A_AFTER=$(focus_snapshot) || fail 'could not capture the Part A post-close focus' +STEAL_LIVE=0 +if [ "$A_AFTER" != "$A_BEFORE" ]; then + STEAL_LIVE=1 + pass "old path: the explicit last-pane close of a non-focused workspace stole focus ($A_BEFORE -> $A_AFTER)" + lab tab focus "$A_ANCHOR_TAB" >/dev/null || fail 'could not restore the Part A anchor focus' +else + pass 'old path note: this Herdr release preserves focus across the explicit close; continuing with outcome-only assertions' +fi + +# --- Part B: the mitigation in the dangerous geometry ---------------------- +# The doomed workspace sits BEFORE the focused anchor and the anchor is not +# last, the exact shape where an unrepositioned pane death also steals focus. +read -r B_DOOMED_WS _ B_DOOMED_PANE <<<"$(mkws flash-b-doomed)" || fail 'could not create the Part B doomed workspace' +read -r B_ANCHOR_WS B_ANCHOR_TAB _ <<<"$(mkws flash-b-anchor)" || fail 'could not create the Part B anchor workspace' +read -r _ _ _ <<<"$(mkws flash-b-tail)" || fail 'could not create the Part B tail workspace' +lab tab focus "$B_ANCHOR_TAB" >/dev/null || fail 'could not focus the Part B anchor' +B_BEFORE=$(focus_snapshot) || fail 'could not capture the Part B pre-close focus' +[ "$B_BEFORE" = "$(printf '%s\t%s' "$B_ANCHOR_WS" "$B_ANCHOR_TAB")" ] \ + || fail 'Part B anchor focus does not match the intended workspace and tab' +B_SURVIVOR_ORDER=$(ws_order | tr ',' '\n' | grep -v "^$B_DOOMED_WS\$" | paste -sd, -) \ + || fail 'could not capture the Part B survivor order' + +CALL_LOG="$TMP_ROOT/call.log" +B_FOCUS_SAMPLES="$TMP_ROOT/focus.samples" +B_OPERATION_ACTIVE="$TMP_ROOT/operation.active" +B_SAMPLER_READY="$TMP_ROOT/sampler.ready" +B_SAMPLER_STOP="$TMP_ROOT/sampler.stop" +: > "$CALL_LOG" +: > "$B_FOCUS_SAMPLES" +( + : > "$B_SAMPLER_READY" + while [ ! -e "$B_SAMPLER_STOP" ]; do + if [ -e "$B_OPERATION_ACTIVE" ]; then + if B_SAMPLE=$(focus_snapshot); then + printf '%s\n' "$B_SAMPLE" >> "$B_FOCUS_SAMPLES" + else + printf '%s\n' UNREADABLE >> "$B_FOCUS_SAMPLES" + fi + fi + done +) & +B_SAMPLER_PID=$! +B_READY_ATTEMPT=0 +while [ ! -e "$B_SAMPLER_READY" ] && [ "$B_READY_ATTEMPT" -lt 100 ]; do + sleep 0.01 + B_READY_ATTEMPT=$((B_READY_ATTEMPT + 1)) +done +[ -e "$B_SAMPLER_READY" ] || fail 'the Part B focus sampler did not start' +: > "$B_OPERATION_ACTIVE" +B_OUT=$(PATH="$FAKEBIN:$HERDR_ORIGINAL_PATH" FM_FLASH_CALL_LOG="$CALL_LOG" bash -c ' + . "$1/bin/backends/herdr.sh" + fm_backend_herdr_cli() { + local session=$1 + shift + printf "%s\n" "$*" >> "$FM_FLASH_CALL_LOG" + HERDR_SESSION="$session" herdr "$@" --session "$session" + } + fm_backend_herdr_projection_close_pane_focus_preserving "$2" "$3" +' _ "$ROOT" "$HERDR_LAB_SESSION" "$B_DOOMED_PANE" 2>&1) +B_STATUS=$? +rm -f "$B_OPERATION_ACTIVE" +: > "$B_SAMPLER_STOP" +wait "$B_SAMPLER_PID" 2>/dev/null || true +B_SAMPLER_PID= +[ "$B_STATUS" -eq 0 ] || fail "the production focus-preserving close failed (status $B_STATUS): $B_OUT" +[ -s "$B_FOCUS_SAMPLES" ] || fail 'the Part B sampler captured no focus sample during the production close' +B_WRONG_SAMPLE=$(grep -Fvx -- "$B_BEFORE" "$B_FOCUS_SAMPLES" | head -1) +if [ -n "$B_WRONG_SAMPLE" ]; then + fail "the mitigation exposed a wrong or unreadable in-operation focus sample ($B_BEFORE -> $B_WRONG_SAMPLE)" +fi +wait_ws_gone "$B_DOOMED_WS" || fail 'the mitigation left the doomed workspace behind' +if lab pane get "$B_DOOMED_PANE" >/dev/null 2>&1; then + fail 'the mitigation left the doomed pane behind' +fi +B_AFTER=$(focus_snapshot) || fail 'could not capture the Part B post-close focus' +[ "$B_AFTER" = "$B_BEFORE" ] \ + || fail "the mitigation changed the exact focused workspace or tab ($B_BEFORE -> $B_AFTER)" +[ "$(ws_order)" = "$B_SURVIVOR_ORDER" ] \ + || fail "the mitigation left a lasting workspace order change ($B_SURVIVOR_ORDER -> $(ws_order))" +grep -q '^pane process-info' "$CALL_LOG" || fail 'the idle-shell proof never ran' +pass 'mitigation: every in-operation sample preserved exact focus while the doomed workspace was removed' + +if [ "$STEAL_LIVE" = 1 ]; then + grep -q '^tab focus' "$CALL_LOG" \ + && fail 'the corrective tab focus fired, so a wrong-focus interval existed on the defective release' + grep -q '^pane close' "$CALL_LOG" \ + && fail 'the focus-unsafe explicit close was used on the defective release' + pass 'mitigation: no explicit close and no corrective focus were needed on the defective release' +fi + +STATUS=$(lab status --json) || fail 'could not read final named-lab version evidence' +printf 'evidence: herdr=%s protocol=%s steal_live=%s default-session-tripwire=armed\n' \ + "$(printf '%s' "$STATUS" | jq -r '.client.version')" \ + "$(printf '%s' "$STATUS" | jq -r '.client.protocol')" \ + "$STEAL_LIVE" diff --git a/tests/fm-backend-herdr-launcher-workspace-e2e.test.sh b/tests/fm-backend-herdr-launcher-workspace-e2e.test.sh new file mode 100755 index 00000000000..31fc2acf86b --- /dev/null +++ b/tests/fm-backend-herdr-launcher-workspace-e2e.test.sh @@ -0,0 +1,439 @@ +#!/usr/bin/env bash +# tests/fm-backend-herdr-launcher-workspace-e2e.test.sh - mandatory ISOLATED +# end-to-end real-Herdr test for worker PLACEMENT with presentation spaces +# disabled. +# +# The guarantee under test: a crewmate or scout is created in the exact Herdr +# workspace of the firstmate or secondmate process that launched it, identified +# from that process's own Herdr pane rather than from a workspace label. Herdr +# enforces no workspace-label uniqueness, so two workspaces can both be labeled +# "firstmate", and the previous label-first-match resolution put the worker in +# whichever one sorted first - visibly the wrong space whenever the launcher was +# not in it. +# +# This drives the REAL bin/fm-spawn.sh and bin/fm-teardown.sh, because the +# guarantee spans the whole spawn handoff (fm-spawn.sh's herdr arm -> +# fm_backend_herdr_container_ensure -> fm_backend_herdr_workspace_ensure -> +# fm_backend_herdr_launcher_identity) and no adapter primitive holds it alone. +# The headline duplicate-label case additionally runs fm-spawn.sh INSIDE a real +# Herdr pane, so the pane identity comes from Herdr's own injection rather than +# from an environment this test composed. +# +# Safety (2026-07-02 incident, see tests/herdr-test-safety.sh): every lifecycle +# operation goes through bin/fm-herdr-lab.sh, which appends the named session +# flag and verifies the default fleet session is unchanged after teardown. +set -u + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" + +fail() { printf 'not ok - %s\n' "$1" >&2; cleanup_all; exit 1; } +pass() { printf 'ok - %s\n' "$1"; } +assert_contains_local() { # <haystack> <needle> <msg> + case "$1" in + *"$2"*) : ;; + *) fail "$3"$'\n'"--- got ---"$'\n'"$1" ;; + esac +} + +command -v herdr >/dev/null 2>&1 || { echo "skip: herdr not found"; exit 0; } +command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the herdr adapter)"; exit 0; } +command -v treehouse >/dev/null 2>&1 || { echo "skip: treehouse not found (required by fm-spawn.sh)"; exit 0; } + +# shellcheck source=tests/herdr-test-safety.sh +. "$ROOT/tests/herdr-test-safety.sh" + +# Every spawn below states its own launcher identity, so a pane inherited from +# the terminal this suite was started in must not leak into any of them. +herdr_forget_inherited_pane + +TMP_ROOT=$(mktemp -d "$(cd "${TMPDIR:-/tmp}" && pwd -P)/fm-herdr-launcher-e2e.XXXXXX") +HERDR_LAB_HELPER="$ROOT/bin/fm-herdr-lab.sh" +HERDR_LAB_SESSION=$("$HERDR_LAB_HELPER" name fm-herdr-launcher-ws) || { + rm -rf "$TMP_ROOT" + printf 'not ok - could not generate an isolated Herdr lab session name\n' >&2 + exit 1 +} +export HERDR_SESSION="$HERDR_LAB_SESSION" + +WORKTREES=() +CLEANED=0 +# Idempotent: fail() cleans up before exiting and the EXIT trap fires after it, +# so a second teardown would otherwise report the already-consumed fleet-state +# tripwire as if the lab had gone wrong. +cleanup_all() { + local wt status=0 + [ "$CLEANED" = 0 ] || return 0 + CLEANED=1 + for wt in ${WORKTREES[@]+"${WORKTREES[@]}"}; do + [ -n "$wt" ] && treehouse return --force "$wt" >/dev/null 2>&1 + done + WORKTREES=() + "$HERDR_LAB_HELPER" teardown "$HERDR_LAB_SESSION" || status=$? + rm -rf "$TMP_ROOT" + return "$status" +} +trap cleanup_all EXIT +"$HERDR_LAB_HELPER" provision "$HERDR_LAB_SESSION" || fail "could not provision isolated Herdr lab session" + +lab() { "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESSION" "$@"; } + +# --- helpers ---------------------------------------------------------------- + +make_scratch_project() { # <dir> + local dir=$1 + mkdir -p "$dir" + git -C "$dir" init -q + printf '# scratch\n' > "$dir/README.md" + git -C "$dir" add README.md + git -C "$dir" -c user.name='Firstmate Tests' -c user.email='tests@example.invalid' commit -qm initial +} + +# make_workspace <label> -> "<workspace_id> <tab_id> <root_pane_id>" +make_workspace() { # <label> + local out + out=$(lab workspace create --cwd "$TMP_ROOT" --label "$1" --no-focus 2>/dev/null) || return 1 + printf '%s' "$out" | jq -r ' + [.result.workspace.workspace_id, .result.tab.tab_id, .result.root_pane.pane_id] | @tsv + ' 2>/dev/null | tr '\t' ' ' +} + +workspace_of_pane() { # <pane_id> + lab pane get "$1" 2>/dev/null | jq -r '.result.pane.workspace_id // empty' 2>/dev/null +} + +label_of_workspace() { # <workspace_id> + lab workspace list 2>/dev/null \ + | jq -r --arg id "$1" '.result.workspaces[]? | select(.workspace_id == $id) | .label' 2>/dev/null +} + +tab_labels_of_workspace() { # <workspace_id> + lab tab list --workspace "$1" 2>/dev/null \ + | jq -r '[.result.tabs[]?.label] | sort | join(",")' 2>/dev/null +} + +journal_field() { # <presentation-journal> <key> + grep "^$2=" "$1" 2>/dev/null | head -1 | cut -d= -f2- +} + +# spawn_from_launcher <launcher-pane|""> <home> <task-id> <project> [extra fm-spawn args...] +# Composes exactly the Herdr identity Herdr itself injects into a pane's +# processes. An empty launcher pane means "this firstmate is not running inside +# Herdr at all". +SPAWN_OUT=; SPAWN_ERR=; SPAWN_RC= +spawn_from_launcher() { + local pane=$1 home=$2 id=$3 proj=$4 + shift 4 + SPAWN_OUT="$TMP_ROOT/$id.out"; SPAWN_ERR="$TMP_ROOT/$id.err" + if [ -n "$pane" ]; then + env HERDR_ENV=1 HERDR_PANE_ID="$pane" HERDR_SESSION="$HERDR_LAB_SESSION" \ + HERDR_SOCKET_PATH="$LAB_SOCKET" \ + FM_SPAWN_NO_GUARD=1 FM_HOME="$home" FM_ROOT_OVERRIDE="$ROOT" \ + "$ROOT/bin/fm-spawn.sh" "$id" "$proj" "sh -c 'echo launcher-ws-ok'" --backend herdr "$@" \ + >"$SPAWN_OUT" 2>"$SPAWN_ERR" + else + env -u HERDR_ENV -u HERDR_PANE_ID -u HERDR_SOCKET_PATH HERDR_SESSION="$HERDR_LAB_SESSION" \ + FM_SPAWN_NO_GUARD=1 FM_HOME="$home" FM_ROOT_OVERRIDE="$ROOT" \ + "$ROOT/bin/fm-spawn.sh" "$id" "$proj" "sh -c 'echo launcher-ws-ok'" --backend herdr "$@" \ + >"$SPAWN_OUT" 2>"$SPAWN_ERR" + fi + SPAWN_RC=$? + return 0 +} + +record_worktree() { # <meta> + local wt + wt=$(grep '^worktree=' "$1" 2>/dev/null | cut -d= -f2-) + [ -n "$wt" ] && WORKTREES+=("$wt") + return 0 +} + +LAB_SOCKET=$(lab session list --json 2>/dev/null \ + | jq -r --arg s "$HERDR_LAB_SESSION" '.sessions[]? | select(.name == $s) | .socket_path' 2>/dev/null) +[ -n "$LAB_SOCKET" ] || fail "could not read the isolated lab session's socket path" + +# --- scratch world ---------------------------------------------------------- + +PRIMARY_HOME="$TMP_ROOT/primary-home" +mkdir -p "$PRIMARY_HOME/state" "$PRIMARY_HOME/config" +SM_ID="lwsm1" +SM_HOME="$TMP_ROOT/secondmate-home" +mkdir -p "$SM_HOME/state" "$SM_HOME/config" "$SM_HOME/projects" "$SM_HOME/bin" "$SM_HOME/data" +printf '# scratch secondmate home AGENTS.md placeholder\n' > "$SM_HOME/AGENTS.md" +printf '%s\n' "$SM_ID" > "$SM_HOME/.fm-secondmate-home" +printf 'trivial e2e secondmate charter: nothing to do.\n' > "$SM_HOME/data/charter.md" + +SM2_ID="lwsm2" +SM2_HOME="$TMP_ROOT/secondmate-home-2" +mkdir -p "$SM2_HOME/state" "$SM2_HOME/config" "$SM2_HOME/projects" "$SM2_HOME/bin" "$SM2_HOME/data" +printf '# scratch secondmate home AGENTS.md placeholder\n' > "$SM2_HOME/AGENTS.md" +printf '%s\n' "$SM2_ID" > "$SM2_HOME/.fm-secondmate-home" +printf 'trivial e2e secondmate charter: nothing to do.\n' > "$SM2_HOME/data/charter.md" + +# A third primary-shaped home with presentation spaces ON, so the flat-path +# homes above stay flag-free and each layout is asserted in isolation. +PRES_HOME="$TMP_ROOT/presentation-home" +mkdir -p "$PRES_HOME/state" "$PRES_HOME/config" +: > "$PRES_HOME/config/herdr-presentation-spaces" + +for id in uniqA uniqB dupC dupD staleF smE presU presD; do + mkdir -p "$PRIMARY_HOME/data/$id" "$SM_HOME/data/$id" "$PRES_HOME/data/$id" + printf 'trivial launcher-placement brief: nothing to do.\n' > "$PRIMARY_HOME/data/$id/brief.md" + printf 'trivial launcher-placement brief: nothing to do.\n' > "$SM_HOME/data/$id/brief.md" + printf 'trivial launcher-placement brief: nothing to do.\n' > "$PRES_HOME/data/$id/brief.md" +done +mkdir -p "$PRIMARY_HOME/data/$SM2_ID" +printf 'trivial secondmate charter brief: nothing to do.\n' > "$PRIMARY_HOME/data/$SM2_ID/brief.md" + +PROJ="$TMP_ROOT/scratch-project"; make_scratch_project "$PROJ" +# Register the scratch project as local-only in every home that spawns against +# it: it has no remote, so a PR-mode task could never clear the fork's delivery +# gate at teardown (same binding as tests/fm-backend-herdr-workspace-per-home-e2e.test.sh). +mkdir -p "$PRIMARY_HOME/data" "$SM_HOME/data" "$PRES_HOME/data" +printf -- '- scratch-project [local-only] - herdr launcher-workspace e2e scratch\n' \ + > "$PRIMARY_HOME/data/projects.md" +printf -- '- scratch-project [local-only] - herdr launcher-workspace e2e scratch\n' \ + > "$SM_HOME/data/projects.md" +printf -- '- scratch-project [local-only] - herdr launcher-workspace e2e scratch\n' \ + > "$PRES_HOME/data/projects.md" + +# One unrelated workspace, kept FOCUSED throughout, so every placement result +# below is also evidence that the globally focused workspace is never the target. +read -r WS_OTHER WS_OTHER_TAB _ <<EOF +$(make_workspace captain-other) +EOF +[ -n "$WS_OTHER" ] || fail "could not create the unrelated captain workspace" +lab tab focus "$WS_OTHER_TAB" >/dev/null 2>&1 || fail "could not focus the unrelated captain workspace" + +focused_workspace() { + lab workspace list 2>/dev/null | jq -r '[.result.workspaces[]? | select(.focused == true) | .workspace_id][0] // empty' 2>/dev/null +} +[ "$(focused_workspace)" = "$WS_OTHER" ] || fail "the unrelated captain workspace did not take focus" + +# --- 1. unique label, no herdr ancestry: the per-home container still works -- + +spawn_from_launcher "" "$PRIMARY_HOME" uniqA "$PROJ" +[ "$SPAWN_RC" -eq 0 ] || fail "a primary-shaped spawn with no herdr parent failed"$'\n'"$(cat "$SPAWN_ERR")" +UNIQA_META="$PRIMARY_HOME/state/uniqA.meta" +record_worktree "$UNIQA_META" +UNIQA_PANE=$(grep '^herdr_pane_id=' "$UNIQA_META" | cut -d= -f2-) +[ -n "$UNIQA_PANE" ] || fail "uniqA meta is missing herdr_pane_id" +WS_PRIMARY=$(workspace_of_pane "$UNIQA_PANE") +[ -n "$WS_PRIMARY" ] || fail "could not read uniqA's workspace" +[ "$(label_of_workspace "$WS_PRIMARY")" = firstmate ] || fail "uniqA did not land in a 'firstmate' workspace" +[ "$(focused_workspace)" = "$WS_OTHER" ] || fail "the spawn stole focus from the captain's workspace" +pass "real herdr E2E: with one 'firstmate' workspace and no herdr parent, a crewmate still lands in this home's own workspace without stealing focus" + +# --- 2. unique label, WITH a launcher pane: same workspace, now by identity -- + +read -r _ _ LAUNCH_PRIMARY_PANE <<EOF +$(lab tab create --workspace "$WS_PRIMARY" --cwd "$TMP_ROOT" --label captain-shell --no-focus 2>/dev/null \ + | jq -r '["x","x", .result.root_pane.pane_id] | @tsv' | tr '\t' ' ') +EOF +[ -n "$LAUNCH_PRIMARY_PANE" ] || fail "could not create a launcher pane inside the 'firstmate' workspace" + +spawn_from_launcher "$LAUNCH_PRIMARY_PANE" "$PRIMARY_HOME" uniqB "$PROJ" +[ "$SPAWN_RC" -eq 0 ] || fail "a primary spawn from a launcher pane failed"$'\n'"$(cat "$SPAWN_ERR")" +UNIQB_META="$PRIMARY_HOME/state/uniqB.meta" +record_worktree "$UNIQB_META" +UNIQB_PANE=$(grep '^herdr_pane_id=' "$UNIQB_META" | cut -d= -f2-) +[ "$(workspace_of_pane "$UNIQB_PANE")" = "$WS_PRIMARY" ] \ + || fail "a crewmate launched from the 'firstmate' workspace must stay in it" +pass "real herdr E2E: the normal unique-label path is unchanged when the launcher's own pane identifies the workspace" + +# --- 2b. presentation spaces ON: the projected child is created and bound +# UNDER the launcher's exact workspace, not collapsed into it --------- + +spawn_from_launcher "$LAUNCH_PRIMARY_PANE" "$PRES_HOME" presU "$PROJ" +[ "$SPAWN_RC" -eq 0 ] || fail "a presentation-enabled spawn from a launcher pane failed"$'\n'"$(cat "$SPAWN_ERR")" +PRESU_META="$PRES_HOME/state/presU.meta" +record_worktree "$PRESU_META" +PRESU_PANE=$(grep '^herdr_pane_id=' "$PRESU_META" | cut -d= -f2-) +PRESU_WS=$(workspace_of_pane "$PRESU_PANE") +[ -n "$PRESU_WS" ] || fail "could not read presU's workspace" +[ "$PRESU_WS" != "$WS_PRIMARY" ] \ + || fail "a projected worker must get its own disposable workspace, not be collapsed into its parent" +case "$(label_of_workspace "$PRESU_WS")" in + "└ "*" · p:"*) : ;; + *) fail "presU's workspace is not a presentation projection: '$(label_of_workspace "$PRESU_WS")'" ;; +esac +PRESU_JOURNAL="$PRES_HOME/state/presU.herdr-presentation" +[ -f "$PRESU_JOURNAL" ] || fail "a projected spawn did not leave its presentation journal" +[ "$(journal_field "$PRESU_JOURNAL" version)" = 2 ] \ + || fail "the projection did not publish an exact restart binding"$'\n'"$(cat "$PRESU_JOURNAL")" +[ "$(journal_field "$PRESU_JOURNAL" parent_workspace_id)" = "$WS_PRIMARY" ] \ + || fail "the projection bound a parent other than the launcher's own workspace ($WS_PRIMARY)" +[ "$(journal_field "$PRESU_JOURNAL" workspace_id)" = "$PRESU_WS" ] \ + || fail "the projection journal does not name its own workspace" +[ "$(focused_workspace)" = "$WS_OTHER" ] || fail "a projected spawn stole focus from the captain's workspace" +pass "real herdr E2E: presentation spaces still create the isolated child workspace and bind it under the launcher's exact parent, without stealing focus" + +# --- 3. duplicate label, launcher in the NON-first match, driven from a real +# Herdr pane so the identity comes from Herdr's own injection ---------- + +read -r WS_PRIMARY_DUP _ LAUNCH_DUP_PANE <<EOF +$(make_workspace firstmate) +EOF +[ -n "$WS_PRIMARY_DUP" ] || fail "could not create the second 'firstmate' workspace" +[ "$WS_PRIMARY_DUP" != "$WS_PRIMARY" ] || fail "the two 'firstmate' workspaces must be distinct" +DUP_COUNT=$(lab workspace list 2>/dev/null | jq -r '[.result.workspaces[]? | select(.label == "firstmate")] | length') +[ "$DUP_COUNT" = 2 ] || fail "expected exactly two 'firstmate' workspaces, got $DUP_COUNT" +WS_PRIMARY_TABS_BEFORE=$(tab_labels_of_workspace "$WS_PRIMARY") + +cat > "$TMP_ROOT/spawn-in-pane.sh" <<SPAWN +#!/usr/bin/env bash +set -u +FM_SPAWN_NO_GUARD=1 FM_HOME="$PRIMARY_HOME" FM_ROOT_OVERRIDE="$ROOT" \\ + "$ROOT/bin/fm-spawn.sh" dupC "$PROJ" "sh -c 'echo launcher-ws-ok'" --backend herdr \\ + > "$TMP_ROOT/dupC.out" 2> "$TMP_ROOT/dupC.err" +echo \$? > "$TMP_ROOT/dupC.rc" +SPAWN +chmod +x "$TMP_ROOT/spawn-in-pane.sh" +lab pane run "$LAUNCH_DUP_PANE" "$TMP_ROOT/spawn-in-pane.sh" >/dev/null 2>&1 \ + || fail "could not run fm-spawn.sh inside the launcher's herdr pane" +i=0 +while [ ! -f "$TMP_ROOT/dupC.rc" ] && [ "$i" -lt 120 ]; do sleep 2; i=$((i + 1)); done +[ -f "$TMP_ROOT/dupC.rc" ] || fail "fm-spawn.sh never finished inside the launcher's herdr pane" +[ "$(cat "$TMP_ROOT/dupC.rc")" = 0 ] \ + || fail "the in-pane spawn failed"$'\n'"$(cat "$TMP_ROOT/dupC.err" 2>/dev/null)" + +DUPC_META="$PRIMARY_HOME/state/dupC.meta" +record_worktree "$DUPC_META" +DUPC_PANE=$(grep '^herdr_pane_id=' "$DUPC_META" | cut -d= -f2-) +DUPC_WS=$(workspace_of_pane "$DUPC_PANE") +[ "$DUPC_WS" = "$WS_PRIMARY_DUP" ] \ + || fail "a worker launched from the second 'firstmate' workspace ($WS_PRIMARY_DUP) landed in '$DUPC_WS' instead" +[ "$DUPC_WS" != "$WS_PRIMARY" ] || fail "the worker was placed in the first label match, the defect under test" +[ "$DUPC_WS" != "$WS_OTHER" ] || fail "the worker was placed in the globally focused workspace" +[ "$(grep '^herdr_workspace_id=' "$DUPC_META" | cut -d= -f2-)" = "$WS_PRIMARY_DUP" ] \ + || fail "the recorded endpoint workspace does not match the launcher's workspace" +pass "real herdr E2E: with two 'firstmate' workspaces, a worker spawned from inside the second one lands in that exact workspace" + +[ "$(tab_labels_of_workspace "$WS_PRIMARY")" = "$WS_PRIMARY_TABS_BEFORE" ] \ + || fail "the other same-labeled workspace's tabs changed; it must never be adopted or mutated" +[ "$(label_of_workspace "$WS_PRIMARY")" = firstmate ] \ + || fail "the other same-labeled workspace was renamed" +[ "$(focused_workspace)" = "$WS_OTHER" ] || fail "the in-pane spawn stole focus from the captain's workspace" +pass "real herdr E2E: the duplicate-labeled sibling workspace is left entirely untouched and focus is preserved" + +# --- 3b. presentation spaces ON with a duplicated parent label: the projection +# still hangs off the launcher's exact workspace --------------------- + +spawn_from_launcher "$LAUNCH_DUP_PANE" "$PRES_HOME" presD "$PROJ" +[ "$SPAWN_RC" -eq 0 ] || fail "a projected spawn under a duplicated parent label failed"$'\n'"$(cat "$SPAWN_ERR")" +PRESD_META="$PRES_HOME/state/presD.meta" +record_worktree "$PRESD_META" +PRESD_PANE=$(grep '^herdr_pane_id=' "$PRESD_META" | cut -d= -f2-) +PRESD_WS=$(workspace_of_pane "$PRESD_PANE") +[ -n "$PRESD_WS" ] || fail "could not read presD's workspace" +PRESD_JOURNAL="$PRES_HOME/state/presD.herdr-presentation" +[ "$(journal_field "$PRESD_JOURNAL" version)" = 2 ] \ + || fail "the duplicate-label projection did not publish a version 2 binding"$'\n'"$(cat "$PRESD_JOURNAL" 2>/dev/null)" +[ "$(journal_field "$PRESD_JOURNAL" parent_workspace_id)" = "$WS_PRIMARY_DUP" ] \ + || fail "the duplicate-label projection journal did not bind the launcher's exact parent workspace" +[ "$PRESD_WS" != "$WS_PRIMARY" ] && [ "$PRESD_WS" != "$WS_PRIMARY_DUP" ] \ + || fail "a projected worker must not be collapsed into either same-labeled parent workspace" +PRESD_ORDER=$(lab workspace list 2>/dev/null | jq -r --arg dup "$WS_PRIMARY_DUP" --arg child "$PRESD_WS" ' + [range(0; (.result.workspaces | length)) as $i + | {i: $i, id: .result.workspaces[$i].workspace_id}] + | ((map(select(.id == $child)) | .[0].i) - (map(select(.id == $dup)) | .[0].i))') +[ "$PRESD_ORDER" = 1 ] \ + || fail "the projected child should sit immediately after the launcher's own workspace, offset was '$PRESD_ORDER'" +[ "$(tab_labels_of_workspace "$WS_PRIMARY")" = "$WS_PRIMARY_TABS_BEFORE" ] \ + || fail "the other same-labeled workspace was mutated by a projected spawn" +[ "$(focused_workspace)" = "$WS_OTHER" ] || fail "a projected spawn stole focus from the captain's workspace" +pass "real herdr E2E: with a duplicated home label, a projected worker still hangs off the launcher's exact workspace and the sibling stays untouched" + +# --- 4. duplicate label with NO launcher identity refuses before publishing -- + +spawn_from_launcher "" "$PRIMARY_HOME" dupD "$PROJ" +[ "$SPAWN_RC" -ne 0 ] || fail "a duplicate-labeled home workspace with no herdr parent must refuse, not guess" +assert_contains_local "$(cat "$SPAWN_ERR")" "labeled 'firstmate'" \ + "the refusal did not name the duplicated home label" +[ ! -e "$PRIMARY_HOME/state/dupD.meta" ] || fail "a refused spawn must not publish task metadata" +DUP_TABS=$(lab tab list --workspace "$WS_PRIMARY" 2>/dev/null | jq -r '[.result.tabs[]? | select(.label == "fm-dupD")] | length') +DUP_TABS2=$(lab tab list --workspace "$WS_PRIMARY_DUP" 2>/dev/null | jq -r '[.result.tabs[]? | select(.label == "fm-dupD")] | length') +[ "$DUP_TABS" = 0 ] && [ "$DUP_TABS2" = 0 ] || fail "a refused spawn created a worker endpoint anyway" +pass "real herdr E2E: an ambiguous home label with no launcher identity refuses before any worker endpoint exists" + +# --- 5. a STALE launcher pane refuses, even though the home label is +# unambiguous from the launcher's own (now closed) workspace ----------- +# A firstmate whose own pane was closed under it has an identity that no longer +# resolves. Guessing a workspace from the label is exactly what must not happen. + +read -r _ _ STALE_PANE <<EOF +$(make_workspace stale-parent) +EOF +[ -n "$STALE_PANE" ] || fail "could not create the workspace whose pane goes stale" +lab pane close "$STALE_PANE" >/dev/null 2>&1 +if lab pane get "$STALE_PANE" >/dev/null 2>&1; then + fail "the launcher pane did not actually go away" +fi + +spawn_from_launcher "$STALE_PANE" "$PRIMARY_HOME" staleF "$PROJ" +[ "$SPAWN_RC" -ne 0 ] || fail "a launcher pane that no longer exists must refuse, not fall back to a label search" +assert_contains_local "$(cat "$SPAWN_ERR")" "$STALE_PANE" \ + "the stale-identity refusal did not name the launcher pane it could not resolve" +[ ! -e "$PRIMARY_HOME/state/staleF.meta" ] || fail "a refused spawn must not publish task metadata" +STALE_TABS=$(lab tab list --workspace "$WS_PRIMARY_DUP" 2>/dev/null | jq -r '[.result.tabs[]? | select(.label == "fm-staleF")] | length') +[ "$STALE_TABS" = 0 ] || fail "a refused spawn created a worker endpoint anyway" +pass "real herdr E2E: a launcher pane that no longer exists refuses before any worker endpoint exists" + +# --- 6. a secondmate launching its own worker gets the same guarantee ------- + +read -r WS_SM_DECOY _ _ <<EOF +$(make_workspace "2ndmate-$SM_ID") +EOF +read -r WS_SM_LAUNCH _ LAUNCH_SM_PANE <<EOF +$(make_workspace "2ndmate-$SM_ID") +EOF +[ -n "$WS_SM_DECOY" ] && [ -n "$WS_SM_LAUNCH" ] || fail "could not create the two secondmate-labeled workspaces" +WS_SM_DECOY_TABS_BEFORE=$(tab_labels_of_workspace "$WS_SM_DECOY") + +spawn_from_launcher "$LAUNCH_SM_PANE" "$SM_HOME" smE "$PROJ" +[ "$SPAWN_RC" -eq 0 ] || fail "a secondmate-owned crewmate spawn failed"$'\n'"$(cat "$SPAWN_ERR")" +SME_META="$SM_HOME/state/smE.meta" +record_worktree "$SME_META" +SME_PANE=$(grep '^herdr_pane_id=' "$SME_META" | cut -d= -f2-) +SME_WS=$(workspace_of_pane "$SME_PANE") +[ "$SME_WS" = "$WS_SM_LAUNCH" ] \ + || fail "a secondmate's own worker must land in the secondmate's exact workspace ($WS_SM_LAUNCH), got '$SME_WS'" +[ "$(tab_labels_of_workspace "$WS_SM_DECOY")" = "$WS_SM_DECOY_TABS_BEFORE" ] \ + || fail "the duplicate secondmate-labeled workspace was mutated" +pass "real herdr E2E: a secondmate launching its own worker gets the same exact-workspace guarantee, and its same-labeled sibling is untouched" + +# --- 7. a --secondmate launch is NOT collapsed into the launcher's workspace - + +spawn_from_launcher "$LAUNCH_DUP_PANE" "$PRIMARY_HOME" "$SM2_ID" "$SM2_HOME" --secondmate +[ "$SPAWN_RC" -eq 0 ] || fail "the primary's --secondmate launch failed"$'\n'"$(cat "$SPAWN_ERR")" +SM2_META="$PRIMARY_HOME/state/$SM2_ID.meta" +SM2_PANE=$(grep '^herdr_pane_id=' "$SM2_META" | cut -d= -f2-) +SM2_WS=$(workspace_of_pane "$SM2_PANE") +[ "$SM2_WS" != "$WS_PRIMARY_DUP" ] \ + || fail "a --secondmate launch must stand up the secondmate's own workspace, not join the launcher's" +[ "$(label_of_workspace "$SM2_WS")" = "2ndmate-$SM2_ID" ] \ + || fail "a --secondmate launch should land in '2ndmate-$SM2_ID', got '$(label_of_workspace "$SM2_WS")'" +pass "real herdr E2E: a --secondmate launch still stands up that secondmate's own workspace instead of inheriting the launcher's" + +# --- 8. teardown closes only the worker's own pane -------------------------- + +FM_ROOT_OVERRIDE="$ROOT" FM_STATE_OVERRIDE="$PRIMARY_HOME/state" FM_DATA_OVERRIDE="$PRIMARY_HOME/data" \ + FM_CONFIG_OVERRIDE="$PRIMARY_HOME/config" \ + "$ROOT/bin/fm-teardown.sh" dupC >"$TMP_ROOT/teardown.out" 2>&1 +status=$? +[ "$status" -eq 0 ] || fail "fm-teardown.sh failed for dupC"$'\n'"$(cat "$TMP_ROOT/teardown.out")" +[ ! -f "$DUPC_META" ] || fail "fm-teardown.sh did not remove dupC's meta" +if lab pane get "$DUPC_PANE" >/dev/null 2>&1; then + fail "fm-teardown.sh did not close dupC's own pane" +fi +lab pane get "$LAUNCH_DUP_PANE" >/dev/null 2>&1 || fail "teardown closed the launcher's own pane" +lab pane get "$UNIQB_PANE" >/dev/null 2>&1 || fail "teardown closed an unrelated worker's pane in the other same-labeled workspace" +[ "$(label_of_workspace "$WS_PRIMARY_DUP")" = firstmate ] || fail "teardown removed or renamed the launcher's workspace" +pass "real herdr E2E: teardown closes only the worker's own pane and leaves the launcher, its workspace, and the same-labeled sibling intact" + +if ! cleanup_all; then + trap - EXIT + printf 'not ok - isolated Herdr lab teardown failed or the default fleet session changed\n' >&2 + exit 1 +fi +trap - EXIT +pass "real herdr E2E: isolated lab session removed and default fleet session unchanged" diff --git a/tests/fm-backend-herdr-presentation-e2e.test.sh b/tests/fm-backend-herdr-presentation-e2e.test.sh index 158e943211c..3691e165934 100755 --- a/tests/fm-backend-herdr-presentation-e2e.test.sh +++ b/tests/fm-backend-herdr-presentation-e2e.test.sh @@ -253,6 +253,14 @@ chmod +x "$FAKEBIN/herdr-workspace-mover" export PATH="$FAKEBIN:$PATH" export FM_BACKEND_HERDR_WORKSPACE_MOVER="$FAKEBIN/herdr-workspace-mover" +# shellcheck source=tests/herdr-test-safety.sh +. "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity. Every projection below is anchored on the +# parent this suite sets up, not on the developer's own workspace. +herdr_forget_inherited_pane + HERDR_LAB_SESSION=$(PATH="$HERDR_ORIGINAL_PATH" \ "$HERDR_LAB_HELPER" name fm-herdr-presentation-projection) export HERDR_SESSION="$HERDR_LAB_SESSION" HERDR_LAB_SESSION @@ -331,38 +339,28 @@ assert_raw_presentation_mutations_preserved_since() { # <line-count> <case-name [ -z "$changed" ] || fail "$case_name changed active workspace/tab inside a create, move, or seeded cleanup: $changed" } -assert_cleanup_focus_steal_was_restored() { # <line-count> <pane-id> <expected-focus> - local start=$1 pane_id=$2 expected=$3 - sed -n "$((start + 1)),\$p" "$FOCUS_AUDIT_LOG" | awk -F '\t' -v pane="$pane_id" -v expected="$expected" ' - $1 == "pane-close" && $4 == pane && $2 == expected && $3 != expected { - drift = $3 - saw_close = 1 - next - } - saw_close && $1 == "tab-focus" && $2 == drift && $3 == expected { - restored = 1 - } - END { exit(restored ? 0 : 1) } - ' || fail "projected task-pane close did not demonstrate and immediately restore the exact focus-steal regression" -} - +# The focus-safe emptying-close plan removes a last pane through Herdr's +# pane-death path with no pane.close mutation at all (the raw explicit-close +# defect is demonstrated by tests/fm-backend-herdr-focus-flash-e2e.test.sh); +# a fallback plain close must preserve or immediately restore exact focus. assert_cleanup_focus_preserved() { # <line-count> <pane-id> <expected-focus> local start=$1 pane_id=$2 expected=$3 sed -n "$((start + 1)),\$p" "$FOCUS_AUDIT_LOG" | awk -F '\t' -v pane="$pane_id" -v expected="$expected" ' - $1 == "pane-close" && $4 == pane && $2 == expected { + $1 == "pane-close" && $4 == pane { saw_close = 1 - if ($3 == expected) { - preserved = 1 - } else { - drift = $3 - } + if ($2 != expected) { bad = 1 } + else if ($3 == expected) { preserved = 1 } + else { drift = $3 } next } saw_close && drift != "" && $1 == "tab-focus" && $2 == drift && $3 == expected { preserved = 1 } - END { exit(saw_close && preserved ? 0 : 1) } + END { exit(bad || (saw_close && !preserved) ? 1 : 0) } ' || fail "projected pane close did not preserve or restore the exact active workspace and tab" + if lab pane get "$pane_id" >/dev/null 2>&1; then + fail "projected cleanup left exact pane $pane_id alive" + fi } remember_meta_worktree() { # <meta> @@ -788,7 +786,7 @@ SHAPE_CLEANUP_AUDIT_START=$(focus_audit_line_count) teardown_task shape "$HOME_DIR" > "$TMP_ROOT/on-teardown.out" 2> "$TMP_ROOT/on-teardown.err" \ || fail "projected teardown failed: $(cat "$TMP_ROOT/on-teardown.err")" assert_focus_is "$CAPTAIN_FOCUS" "projected teardown" -assert_cleanup_focus_steal_was_restored "$SHAPE_CLEANUP_AUDIT_START" "$PROJECTED_PANE" "$CAPTAIN_FOCUS" +assert_cleanup_focus_preserved "$SHAPE_CLEANUP_AUDIT_START" "$PROJECTED_PANE" "$CAPTAIN_FOCUS" pass "real Herdr lab: Treehouse commands and metadata shape are byte-identical except for Herdr container IDs" if lab workspace get "$PROJECTED_WSID" >/dev/null 2>&1; then fail "closing the exact projected task pane did not remove its last-tab workspace" @@ -796,7 +794,7 @@ fi lab pane get "$SECOND_TWO_PANE" >/dev/null 2>&1 \ || fail "projected teardown affected the focused secondmate workspace" [ ! -e "$JOURNAL" ] || fail "confirmed projected teardown did not retire its presentation journal" -pass "real Herdr lab: exact task-pane close restores the exact captain workspace/tab after Herdr's raw focus steal" +pass "real Herdr lab: exact task-pane close removes the projected workspace with no unrestored wrong-focus interval" teardown_task order-a "$HOME_DIR" > "$TMP_ROOT/order-a-teardown.out" 2> "$TMP_ROOT/order-a-teardown.err" & ORDER_A_TEARDOWN_PID=$! @@ -866,7 +864,7 @@ touch "$SECOND_HOME_A/state/.last-watcher-beat" "$SECOND_HOME_B/state/.last-watc # may write config/herdr-presentation-spaces. git -C "$SECOND_HOME_A" init -q git -C "$SECOND_HOME_B" init -q -printf 'config/herdr-presentation-spaces\nconfig/crew-harness\nconfig/crew-dispatch.json\nconfig/backlog-backend\nconfig/backend\n' \ +printf 'config/herdr-presentation-spaces\nconfig/crew-harness\nconfig/crew-dispatch.json\nconfig/backlog-backend\nconfig/backend\nconfig/startup-memory-budget\n' \ > "$SECOND_HOME_A/.gitignore" cp "$SECOND_HOME_A/.gitignore" "$SECOND_HOME_B/.gitignore" git -C "$SECOND_HOME_A" add .gitignore diff --git a/tests/fm-backend-herdr-prune-safety-e2e.test.sh b/tests/fm-backend-herdr-prune-safety-e2e.test.sh index eca742fc4bc..f69160e0bde 100755 --- a/tests/fm-backend-herdr-prune-safety-e2e.test.sh +++ b/tests/fm-backend-herdr-prune-safety-e2e.test.sh @@ -33,6 +33,11 @@ command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the her # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + SESSION="fm-lab-prune-safety-e2e-$$" export HERDR_SESSION="$SESSION" SCRATCH=$(mktemp -d "${TMPDIR:-/tmp}/fm-herdr-prune-safety.XXXXXX") diff --git a/tests/fm-backend-herdr-respawn-idem-e2e.test.sh b/tests/fm-backend-herdr-respawn-idem-e2e.test.sh index 1274cde5876..382fb72d979 100755 --- a/tests/fm-backend-herdr-respawn-idem-e2e.test.sh +++ b/tests/fm-backend-herdr-respawn-idem-e2e.test.sh @@ -45,6 +45,11 @@ command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the her # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + SESSION="fm-lab-respawn-idem-e2e-$$" export HERDR_SESSION="$SESSION" SCRATCH=$(mktemp -d "${TMPDIR:-/tmp}/fm-herdr-respawn-idem.XXXXXX") diff --git a/tests/fm-backend-herdr-smoke.test.sh b/tests/fm-backend-herdr-smoke.test.sh index 9eef7a90242..98f1db2e974 100755 --- a/tests/fm-backend-herdr-smoke.test.sh +++ b/tests/fm-backend-herdr-smoke.test.sh @@ -27,6 +27,11 @@ command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the her # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + SESSION="fm-lab-backend-smoke-$$" export HERDR_SESSION="$SESSION" SM_SCRATCH= diff --git a/tests/fm-backend-herdr-workspace-per-home-e2e.test.sh b/tests/fm-backend-herdr-workspace-per-home-e2e.test.sh index c35da64d279..9d5aceea666 100755 --- a/tests/fm-backend-herdr-workspace-per-home-e2e.test.sh +++ b/tests/fm-backend-herdr-workspace-per-home-e2e.test.sh @@ -54,6 +54,11 @@ command -v treehouse >/dev/null 2>&1 || { echo "skip: treehouse not found (requi # shellcheck source=tests/herdr-test-safety.sh . "$ROOT/tests/herdr-test-safety.sh" +# This suite runs against its own isolated lab session, so a Herdr pane +# inherited from the terminal it was launched in must not follow spawn into it +# as a cross-session parent identity (tests/herdr-test-safety.sh). +herdr_forget_inherited_pane + # TMP_ROOT is physically resolved (mktemp -d "$(pwd -P)"-relative) for the same # low-noise scratch fixture shape used by # tests/fm-backend-autodetect-smoke.test.sh. diff --git a/tests/fm-backend-herdr.test.sh b/tests/fm-backend-herdr.test.sh index d4e2c41c458..41150f52c6f 100755 --- a/tests/fm-backend-herdr.test.sh +++ b/tests/fm-backend-herdr.test.sh @@ -12,9 +12,16 @@ set -u # shellcheck source=tests/lib.sh . "$(dirname "${BASH_SOURCE[0]}")/lib.sh" +# shellcheck source=tests/herdr-test-safety.sh +. "$(dirname "${BASH_SOURCE[0]}")/herdr-test-safety.sh" command -v jq >/dev/null 2>&1 || { echo "skip: jq not found (required by the herdr adapter)"; exit 0; } +# These cases script a canned fake CLI; a Herdr pane identity leaked in from the +# developer's own terminal would make the adapter resolve a launcher that this +# fake never models. The launcher cases below set HERDR_PANE_ID themselves. +herdr_forget_inherited_pane + TMP_ROOT=$(fm_test_tmproot fm-backend-herdr-tests) export FM_BACKEND_HERDR_SUBMIT_MIN_SLEEP=0 @@ -282,6 +289,214 @@ test_cli_helper_sets_env_and_appends_trailing_session_flag() { pass "fm_backend_herdr_cli: sets HERDR_SESSION AND appends a trailing --session flag on every call" } +# --- launcher_identity: the exact workspace a worker must be placed in ------- +# +# Herdr injects HERDR_ENV/HERDR_PANE_ID/HERDR_SESSION/HERDR_SOCKET_PATH into +# every process it manages a pane for, so a firstmate or secondmate agent's own +# tool calls carry the identity of the workspace the captain is watching it in. +# Placement resolves from that identity because workspace labels are mutable and +# non-unique, and the globally focused workspace is unrelated to the launcher. +# The refusal cases matter as much as the resolution: a broken binding must stop +# the spawn, never quietly degrade back to picking a workspace by label. + +test_launcher_identity_absent_without_a_herdr_pane() { + local dir log resp fb status + dir="$TMP_ROOT/launcher-none"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + fb=$(make_herdr_fakebin "$dir") + ( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" ) + status=$? + expect_code 2 "$status" "a process with no herdr pane must report 'no launcher to inherit' (2), not a refusal" + [ ! -s "$log" ] || fail "resolving an absent launcher identity must not call herdr at all"$'\n'"$(cat "$log")" + pass "fm_backend_herdr_launcher_identity: a firstmate not running inside herdr has no launcher workspace to inherit" +} + +test_launcher_identity_absent_when_herdr_env_alone_is_set() { + local dir log resp fb status + dir="$TMP_ROOT/launcher-env-only"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + fb=$(make_herdr_fakebin "$dir") + ( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" HERDR_ENV=1 \ + \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" ) + status=$? + expect_code 2 "$status" "HERDR_ENV=1 alone is a backend-selection marker, not a parent binding" + pass "fm_backend_herdr_launcher_identity: HERDR_ENV=1 without a pane id selects the backend but binds no parent" +} + +test_launcher_identity_resolves_the_exact_pane_tab_and_workspace() { + local dir log resp fb out + dir="$TMP_ROOT/launcher-ok"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + printf '{"result":{"pane":{"pane_id":"w7:p3","tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/2.out" + printf '{"result":{"tab":{"tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/3.out" + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"},{"workspace_id":"w7","label":"firstmate"}]}}\n' > "$resp/4.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/fmtest.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest || exit 1 + printf "%s|%s|%s" "$FM_BACKEND_HERDR_LAUNCHER_PANE_ID" "$FM_BACKEND_HERDR_LAUNCHER_TAB_ID" "$FM_BACKEND_HERDR_LAUNCHER_WORKSPACE_ID"' "$ROOT" ) + [ "$out" = 'w7:p3|w7:t3|w7' ] \ + || fail "launcher_identity should resolve the launcher's own pane, tab, and workspace, got '$out'" + assert_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''get'$'\x1f''w7:p3' "launcher_identity did not read its own pane" + assert_contains "$(cat "$log")" $'\x1f''tab'$'\x1f''get'$'\x1f''w7:t3' "launcher_identity did not cross-check the owning tab" + pass "fm_backend_herdr_launcher_identity: resolves the launcher's exact workspace even when a same-labeled workspace sorts first" +} + +test_launcher_identity_refuses_a_pane_from_another_session_name() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-xsession"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=someother \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a launcher pane naming another herdr session must refuse" + assert_contains "$out" "cross-session parent identity" "the cross-session refusal did not explain itself" + [ ! -s "$log" ] || fail "a cross-session launcher identity must be refused before any herdr call" + pass "fm_backend_herdr_launcher_identity: refuses a launcher pane that names a different herdr session" +} + +test_launcher_identity_refuses_a_missing_server_socket() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-no-socket"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a launcher pane without an injected server socket must refuse" + assert_contains "$out" "no injected socket identity" "the missing-socket refusal did not explain itself" + [ ! -s "$log" ] || fail "a missing-socket launcher identity must be refused before any herdr call" + pass "fm_backend_herdr_launcher_identity: refuses a claimed pane without exact server identity" +} + +test_launcher_identity_refuses_a_pane_from_another_server_socket() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-xsocket"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + # 1: session list --json, resolving THIS session's own socket. + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/other.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a launcher pane on a different herdr server socket must refuse" + assert_contains "$out" "cross-session parent identity" "the cross-socket refusal did not explain itself" + assert_not_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''get' "a cross-server launcher identity must be refused before its pane is trusted" + pass "fm_backend_herdr_launcher_identity: refuses a launcher pane whose injected socket belongs to another herdr server" +} + +test_launcher_identity_refuses_an_unreadable_pane() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-stale"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + printf '1\n' > "$resp/2.exit" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/fmtest.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a launcher pane that no longer reads must refuse, not fall back to a label search" + assert_contains "$out" "w7:p3" "the stale-pane refusal did not name the pane it could not resolve" + pass "fm_backend_herdr_launcher_identity: refuses when the launcher's own pane no longer resolves" +} + +test_launcher_identity_refuses_a_pane_and_tab_that_disagree() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-contradictory"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + printf '{"result":{"pane":{"pane_id":"w7:p3","tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/2.out" + # The tab claims a DIFFERENT owning workspace than the pane just did. + printf '{"result":{"tab":{"tab_id":"w7:t3","workspace_id":"w9"}}}\n' > "$resp/3.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/fmtest.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a pane and tab that disagree about their workspace must refuse" + assert_contains "$out" "contradictory parent identity" "the contradictory-identity refusal did not explain itself" + pass "fm_backend_herdr_launcher_identity: refuses when the launcher's pane and tab disagree about their workspace" +} + +test_launcher_identity_refuses_a_workspace_missing_from_the_session() { + local dir log resp fb out status + dir="$TMP_ROOT/launcher-gone"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + printf '{"result":{"pane":{"pane_id":"w7:p3","tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/2.out" + printf '{"result":{"tab":{"tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/3.out" + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"}]}}\n' > "$resp/4.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/fmtest.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_launcher_identity fmtest' "$ROOT" 2>&1 ) + status=$? + expect_code 1 "$status" "a launcher workspace absent from the session listing must refuse" + assert_contains "$out" "stale parent identity" "the stale-workspace refusal did not explain itself" + pass "fm_backend_herdr_launcher_identity: refuses when the launcher's workspace is gone from its own session" +} + +# --- workspace_ensure placement --------------------------------------------- + +test_workspace_ensure_prefers_the_launcher_over_the_first_label_match() { + local dir log resp fb out + dir="$TMP_ROOT/ensure-launcher"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fm-herdr-unit/fmtest.sock"}]}\n' > "$resp/1.out" + printf '{"result":{"pane":{"pane_id":"w7:p3","tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/2.out" + printf '{"result":{"tab":{"tab_id":"w7:t3","workspace_id":"w7"}}}\n' > "$resp/3.out" + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"},{"workspace_id":"w7","label":"firstmate"}]}}\n' > "$resp/4.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest HERDR_SOCKET_PATH=/tmp/fm-herdr-unit/fmtest.sock \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_workspace_ensure fmtest /tmp' "$ROOT" ) + [ "$out" = w7 ] || fail "workspace_ensure should place the worker in the launcher's own workspace w7, got '$out'" + assert_not_contains "$(cat "$log")" $'\x1f''workspace'$'\x1f''create' "the launcher's existing workspace must be reused, not duplicated" + pass "fm_backend_herdr_workspace_ensure: places a worker in the launcher's exact workspace, not the first same-labeled one" +} + +test_workspace_ensure_refuses_an_ambiguous_label_with_no_launcher() { + local dir log resp fb out status + dir="$TMP_ROOT/ensure-ambiguous"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"},{"workspace_id":"w7","label":"firstmate"}]}}\n' > "$resp/1.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" HERDR_SESSION=fmtest \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_workspace_ensure fmtest /tmp' "$ROOT" 2>&1 ) + status=$? + expect_code 3 "$status" "two same-labeled home workspaces with no launcher identity must refuse" + assert_contains "$out" "labeled 'firstmate'" "the ambiguity refusal did not name the duplicated label" + assert_contains "$out" "w1 w7" "the ambiguity refusal did not name the candidate workspaces" + assert_not_contains "$(cat "$log")" $'\x1f''workspace'$'\x1f''create' "an ambiguous placement must not mint a third same-labeled workspace" + pass "fm_backend_herdr_workspace_ensure: refuses to guess between two same-labeled home workspaces" +} + +test_workspace_ensure_other_home_ignores_the_launcher_identity() { + local dir log resp fb out + dir="$TMP_ROOT/ensure-other-home"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + # Only a workspace list: the launcher's own pane is never consulted, because a + # --secondmate launch stands up a different home's workspace by design. + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"}]}}\n' > "$resp/1.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + HERDR_ENV=1 HERDR_PANE_ID=w7:p3 HERDR_SESSION=fmtest \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_workspace_ensure fmtest /tmp other-home' "$ROOT" ) + [ "$out" = w1 ] || fail "an other-home container should resolve by this home's own label, got '$out'" + assert_not_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''get' "an other-home container must not inherit the launcher's workspace" + pass "fm_backend_herdr_workspace_ensure: a --secondmate container resolves that home's own workspace, not the launcher's" +} + +test_container_ensure_refuses_an_ambiguous_home_label() { + local dir log resp fb out status + dir="$TMP_ROOT/container-ambiguous"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"},{"workspace_id":"w7","label":"firstmate"}]}}\n' > "$resp/1.out" + fb=$(make_herdr_fakebin "$dir") + out=$( PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" HERDR_SESSION=fmtest \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_container_ensure /tmp' "$ROOT" 2>&1 ) + status=$? + [ "$status" -ne 0 ] || fail "container_ensure must fail when the home workspace is ambiguous" + assert_contains "$out" "labeled 'firstmate'" "container_ensure buried the specific ambiguity it refused" + assert_not_contains "$out" "failed to ensure herdr workspace" "container_ensure added a generic message over the specific one" + pass "fm_backend_herdr_container_ensure: surfaces the exact ambiguous-placement refusal instead of a generic failure" +} + # --- container_ensure / create_task ------------------------------------------ test_container_ensure_starts_server_and_workspace() { @@ -692,8 +907,12 @@ test_projection_create_uses_exact_response_ids_and_leaves_one_task_pane() { printf '{"result":{"panes":[{"pane_id":"w9:p1","tab_id":"w9:t1"},{"pane_id":"w9:p2","tab_id":"w9:t2"}]}}\n' > "$resp/4.out" printf '{"error":{"code":"agent_not_found"}}\n' > "$resp/5.out" printf '{"result":{"pane":{"pane_id":"w9:p1","tab_id":"w9:t1","workspace_id":"w9"}}}\n' > "$resp/6.out" - printf '{"result":{"tabs":[{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/8.out" - printf '{"result":{"panes":[{"pane_id":"w9:p2","tab_id":"w9:t2"}]}}\n' > "$resp/9.out" + # The emptying-close plan's tab list proves the seeded prune is NOT + # workspace-emptying (the task tab remains), so the close stays plain. + printf '{"result":{"tabs":[{"tab_id":"w9:t1","label":"1","workspace_id":"w9"},{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/7.out" + printf '{"error":{"code":"pane_not_found"}}\n' > "$resp/9.out" + printf '{"result":{"tabs":[{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/10.out" + printf '{"result":{"panes":[{"pane_id":"w9:p2","tab_id":"w9:t2"}]}}\n' > "$resp/11.out" fb=$(make_herdr_fakebin "$dir") out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" HERDR_SESSION=fmtest \ bash -c ' @@ -735,8 +954,10 @@ test_projection_create_never_closes_a_concurrent_same_label_tab() { printf '{"result":{"panes":[{"pane_id":"w9:p1","tab_id":"w9:t1"},{"pane_id":"w9:p2","tab_id":"w9:t2"},{"pane_id":"w9:p3","tab_id":"w9:t3"}]}}\n' > "$resp/4.out" printf '{"error":{"code":"agent_not_found"}}\n' > "$resp/5.out" printf '{"result":{"pane":{"pane_id":"w9:p1","tab_id":"w9:t1","workspace_id":"w9"}}}\n' > "$resp/6.out" - printf '{"result":{"tabs":[{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"},{"tab_id":"w9:t3","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/8.out" - printf '{"result":{"panes":[{"pane_id":"w9:p2","tab_id":"w9:t2"},{"pane_id":"w9:p3","tab_id":"w9:t3"}]}}\n' > "$resp/9.out" + printf '{"result":{"tabs":[{"tab_id":"w9:t1","label":"1","workspace_id":"w9"},{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"},{"tab_id":"w9:t3","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/7.out" + printf '{"error":{"code":"pane_not_found"}}\n' > "$resp/9.out" + printf '{"result":{"tabs":[{"tab_id":"w9:t2","label":"fm-task-p2","workspace_id":"w9"},{"tab_id":"w9:t3","label":"fm-task-p2","workspace_id":"w9"}]}}\n' > "$resp/10.out" + printf '{"result":{"panes":[{"pane_id":"w9:p2","tab_id":"w9:t2"},{"pane_id":"w9:p3","tab_id":"w9:t3"}]}}\n' > "$resp/11.out" fb=$(make_herdr_fakebin "$dir") out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" HERDR_SESSION=fmtest \ bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_focus_snapshot() { printf "captain-ws\tcaptain-tab"; }; fm_backend_herdr_projection_focus_restore() { return 0; }; fm_backend_herdr_projection_create_task /tmp/proj label fm-task-p2' "$ROOT" 2>&1) @@ -772,12 +993,16 @@ test_projection_close_restores_exact_prior_focus() { printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":true},{"workspace_id":"w9","active_tab_id":"w9:t2","focused":false}]}}' > "$resp/1.out" printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":false},{"tab_id":"w2:t2","focused":true}]}}' > "$resp/2.out" printf '%s\n' '{"result":{"pane":{"pane_id":"w9:p2","tab_id":"w9:t2","workspace_id":"w9"}}}' > "$resp/3.out" - printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":true}]}}' > "$resp/5.out" - printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","focused":true}]}}' > "$resp/6.out" - printf '%s\n' '{"result":{"tab":{"tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/7.out" - printf '%s\n' '{"result":{"tab":{"tab_id":"w2:t2","workspace_id":"w2","focused":true}}}' > "$resp/8.out" - printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/9.out" - printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":false},{"tab_id":"w2:t2","focused":true}]}}' > "$resp/10.out" + # The emptying-close plan sees a second tab in w9, so the close stays plain + # and the exact-tab restore backstop is what reclaims the stolen focus. + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w9:t1","workspace_id":"w9"},{"tab_id":"w9:t2","workspace_id":"w9"}]}}' > "$resp/4.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/6.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":true}]}}' > "$resp/7.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","focused":true}]}}' > "$resp/8.out" + printf '%s\n' '{"result":{"tab":{"tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tab":{"tab_id":"w2:t2","workspace_id":"w2","focused":true}}}' > "$resp/10.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/11.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":false},{"tab_id":"w2:t2","focused":true}]}}' > "$resp/12.out" fb=$(make_herdr_fakebin "$dir") out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w9:p2' "$ROOT" 2>&1) @@ -818,13 +1043,15 @@ test_projection_close_reports_focus_restore_failure() { printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w9","active_tab_id":"w9:t2","focused":false}]}}' > "$resp/1.out" printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" printf '%s\n' '{"result":{"pane":{"pane_id":"w9:p2","tab_id":"w9:t2","workspace_id":"w9"}}}' > "$resp/3.out" - : > "$resp/4.out" - printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true}]}}' > "$resp/5.out" - printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/6.out" - printf '%s\n' '{"result":{"tab":{"tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/7.out" - : > "$resp/8.out" - cp "$resp/5.out" "$resp/9.out" - cp "$resp/6.out" "$resp/10.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w9:t1","workspace_id":"w9"},{"tab_id":"w9:t2","workspace_id":"w9"}]}}' > "$resp/4.out" + : > "$resp/5.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/6.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true}]}}' > "$resp/7.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/8.out" + printf '%s\n' '{"result":{"tab":{"tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/9.out" + : > "$resp/10.out" + cp "$resp/7.out" "$resp/11.out" + cp "$resp/8.out" "$resp/12.out" fb=$(make_herdr_fakebin "$dir") out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w9:p2' "$ROOT" 2>&1) @@ -865,6 +1092,743 @@ test_projection_close_rechecks_required_agent_state_at_boundary() { pass "herdr presentation reclaim: live agent state at the close boundary refuses mutation" } +# --- emptying-close focus-safe removal (Herdr 0.7.5 #1621 mitigation) ------ +# +# The fixtures below model the verified 0.7.5 rules: an explicit close that +# empties a non-focused workspace moves focus to that workspace's neighbor, +# while a pane-death removal preserves focus whenever the dying workspace +# sits behind the focused one (or the focused one is last). + +# make_death_lab <dir> <shell-pid>: a fake ps and a fake workspace mover for +# the pane-death close fixtures. The mover appends to $FM_FAKE_MOVER_LOG and +# exits 9 unless $FM_FAKE_MOVER_RESPONSE names a readable response file. +make_death_lab() { # <dir> <shell-pid> + local dir=$1 pid=$2 + mkdir -p "$dir" + cat > "$dir/ps" <<SH +#!/usr/bin/env bash +case "\$*" in + "-axo pid=,ppid=") printf '1 0\n$pid 1\n' ;; + "-p $pid -o stat=") printf 'Ss+\n' ;; + "-p $pid -o comm=") printf -- '-zsh\n' ;; + *) exit 1 ;; +esac +SH + cat > "$dir/mover" <<'SH' +#!/usr/bin/env bash +printf '%s\t%s\t%s\n' "$1" "$2" "$3" >> "$FM_FAKE_MOVER_LOG" +calls=$(wc -l < "$FM_FAKE_MOVER_LOG" | tr -d ' ') +if [ "$calls" -ge 2 ] && [ -f "${FM_FAKE_MOVER_RESPONSE_2:-}" ]; then + cat "$FM_FAKE_MOVER_RESPONSE_2" + exit 0 +fi +if [ -f "$FM_FAKE_MOVER_RESPONSE" ]; then + cat "$FM_FAKE_MOVER_RESPONSE" + exit 0 +fi +exit 9 +SH + chmod +x "$dir/ps" "$dir/mover" + : > "$dir/mover.log" +} + +death_process_info_fixture() { # <pane> <pid> + printf '{"result":{"type":"pane_process_info","process_info":{"pane_id":"%s","shell_pid":%s,"foreground_process_group_id":%s,"foreground_processes":[{"pid":%s,"name":"zsh","argv0":"zsh"}]}}}\n' "$1" "$2" "$2" "$2" +} + +test_projection_close_emptying_after_focus_uses_pane_death_without_move() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-after"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + # w1 focused; target w2 sits after it (r > a), so no repositioning is needed. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "emptying close behind focus should succeed through the pane-death path: $out" + [ ! -s "$dir/mover.log" ] || fail "a close already behind focus invoked the workspace mover" + assert_contains "$(cat "$log")" $'pane\x1fprocess-info' "pane-death close skipped the idle-shell proof" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "emptying close behind focus used the focus-unsafe explicit close" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "focus moved despite the pane-death removal" + pass "herdr presentation cleanup: emptying close behind focus ends the exact shell without a move or focus change" +} + +test_projection_close_emptying_before_focus_repositions_then_uses_pane_death() { + local dir log resp fb out status bgpid mover_line + dir="$TMP_ROOT/close-death-before"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + # Target w1 sits BEFORE the focused w2, which is not last: reposition first. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w1:p1","tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","workspace_id":"w1"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w1:p1","tab_id":"w1:t1"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + printf '%s\n' '{"client":{"version":"0.7.5","protocol":16},"server":{"running":true}}' > "$resp/7.out" + # shellcheck disable=SC2016 # $defs is a literal JSON Schema key. + printf '%s\n' '{"schemas":{"request":{"oneOf":[{"properties":{"method":{"const":"workspace.move"}}}],"$defs":{"WorkspaceMoveParams":{"required":["workspace_id","insert_index"],"properties":{"insert_index":{"type":"integer"}}}}}}}' > "$resp/8.out" + printf '%s\n' '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fmtest.sock"}]}' > "$resp/9.out" + sleep 300 & bgpid=$! + death_process_info_fixture w1:p1 "$bgpid" > "$resp/10.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/11.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/12.out" + cp "$resp/12.out" "$resp/13.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/14.out" + make_death_lab "$dir" "$bgpid" + printf '%s\n' '{"id":"fm-workspace-move","result":{"type":"workspace_list","workspaces":[{"workspace_id":"w2","focused":true},{"workspace_id":"w3","focused":false},{"workspace_id":"w1","focused":false}]}}' > "$dir/mover-response" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" FM_HERDR_SCRIPT_STATUS=1 \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/mover-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w1:p1' "$ROOT" 2>&1) + status=$? + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "repositioned emptying close should succeed through the pane-death path: $out" + [ "$(cat "$dir/mover.log")" = "$(cd /tmp && pwd -P)/fmtest.sock"$'\t'"w1"$'\t'"3" ] \ + || fail "the repositioning move did not target the exact doomed workspace at the list length: $(cat "$dir/mover.log")" + mover_line=$(grep -n $'pane\x1fprocess-info' "$log" | head -1 | cut -d: -f1) + [ -n "$mover_line" ] || fail "repositioned close skipped the idle-shell proof" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "repositioned emptying close used the focus-unsafe explicit close" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "focus moved despite the repositioned pane-death removal" + pass "herdr presentation cleanup: emptying close before focus moves the doomed workspace to the end and ends its exact shell" +} + +test_projection_close_emptying_before_last_focus_needs_no_move() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-focus-last"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + # Focused w3 is LAST, so the pane-death clamp preserves it without a move. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":true}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w1:p1","tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","workspace_id":"w1"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w1:p1","tab_id":"w1:t1"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + death_process_info_fixture w1:p1 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":true}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","focused":true}]}}' > "$resp/10.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w1:p1' "$ROOT" 2>&1) + status=$? + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "emptying close with last focus should succeed through the pane-death path: $out" + [ ! -s "$dir/mover.log" ] || fail "a last-focused close invoked the workspace mover" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "last-focused emptying close used the focus-unsafe explicit close" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "focus moved despite the pane-death removal" + pass "herdr presentation cleanup: emptying close with the focused workspace last skips the move" +} + +test_projection_close_emptying_last_workspace_needs_no_move() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-target-last"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + # Target w3 is already last (r > a), so no repositioning is needed. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w3:p1","tab_id":"w3:t1","workspace_id":"w3"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","workspace_id":"w3"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w3:p1","tab_id":"w3:t1"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + death_process_info_fixture w3:p1 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w3:p1' "$ROOT" 2>&1) + status=$? + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "last-workspace emptying close should succeed through the pane-death path: $out" + [ ! -s "$dir/mover.log" ] || fail "an already-last close invoked the workspace mover" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "last-workspace emptying close used the focus-unsafe explicit close" + pass "herdr presentation cleanup: emptying close of the last workspace skips the move" +} + +test_projection_close_non_emptying_stays_plain_without_proof_or_move() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-non-emptying"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","workspace_id":"w2"},{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/6.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":false}]}}' > "$resp/7.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/8.out" + sleep 300 & bgpid=$! + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "non-emptying close should succeed through the plain close: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "non-emptying close did not use the plain close" + assert_not_contains "$(cat "$log")" $'pane\x1fprocess-info' "non-emptying close ran the idle-shell proof" + [ ! -s "$dir/mover.log" ] || fail "non-emptying close invoked the workspace mover" + kill -0 "$bgpid" 2>/dev/null || fail "non-emptying close signaled the pane's shell" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: a non-emptying close stays plain with no proof, move, or signal" +} + +test_projection_close_plain_without_move_requires_structured_removal() { + local dir log out status + dir="$TMP_ROOT/close-plain-unconfirmed"; mkdir -p "$dir" + log="$dir/log"; : > "$log" + out=$(ROOT="$ROOT" LOG="$log" bash -c ' + . "$ROOT/bin/backends/herdr.sh" + fm_backend_herdr_projection_focus_snapshot() { printf "w1\tw1:t1"; } + fm_backend_herdr_emptying_close_plan() { printf "plain\n"; } + fm_backend_herdr_projection_focus_restore() { return 0; } + fm_backend_herdr_cli() { + printf "%s\n" "$*" >> "$LOG" + case "$2 $3" in + "pane get") printf "{\"result\":{\"pane\":{\"pane_id\":\"w2:p2\",\"tab_id\":\"w2:t2\",\"workspace_id\":\"w2\"}}}\n" ;; + esac + } + fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2 + ' 2>&1) + status=$? + [ "$status" -ne 0 ] || fail "a no-move plain close must fail while structured presence remains present: $out" + assert_contains "$(cat "$log")" "pane close w2:p2" \ + "the no-move unconfirmed regression did not reach the explicit close" + pass "herdr presentation cleanup: no-move plain close requires structured pane removal" +} + +test_projection_close_ambiguous_positions_fall_back_to_plain_close() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-ambiguous-positions"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + # The position snapshot is ambiguous: the target workspace is absent. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/6.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + sleep 300 & bgpid=$! + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "an ambiguous position snapshot should fall back to the plain close: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "ambiguous positions did not use the plain close" + assert_not_contains "$(cat "$log")" $'pane\x1fprocess-info' "ambiguous positions ran the idle-shell proof" + [ ! -s "$dir/mover.log" ] || fail "ambiguous positions invoked the workspace mover" + kill -0 "$bgpid" 2>/dev/null || fail "ambiguous positions signaled the pane's shell" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: an ambiguous workspace layout falls back to the plain close" +} + +test_projection_close_move_failure_falls_back_to_plain_close() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-move-failure"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w1:p1","tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","workspace_id":"w1"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w1:p1","tab_id":"w1:t1"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + printf '%s\n' '{"client":{"version":"0.7.5","protocol":16},"server":{"running":true}}' > "$resp/7.out" + # shellcheck disable=SC2016 # $defs is a literal JSON Schema key. + printf '%s\n' '{"schemas":{"request":{"oneOf":[{"properties":{"method":{"const":"workspace.move"}}}],"$defs":{"WorkspaceMoveParams":{"required":["workspace_id","insert_index"],"properties":{"insert_index":{"type":"integer"}}}}}}}' > "$resp/8.out" + printf '%s\n' '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fmtest.sock"}]}' > "$resp/9.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/11.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/12.out" + cp "$resp/12.out" "$resp/13.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/14.out" + sleep 300 & bgpid=$! + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" FM_HERDR_SCRIPT_STATUS=1 \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w1:p1' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "a failed repositioning move should fall back to the plain close: $out" + assert_contains "$out" "could not move the doomed workspace behind the focused one" \ + "a failed repositioning move did not warn about losing the focus-safe path" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw1:p1' "move failure did not use the plain close" + assert_not_contains "$(cat "$log")" $'pane\x1fprocess-info' "move failure ran the idle-shell proof" + kill -0 "$bgpid" 2>/dev/null || fail "move failure signaled the pane's shell" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: a failed repositioning move falls back to the plain close with a warning" +} + +test_projection_close_busy_pane_falls_back_to_plain_close() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-busy-pane"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + # The pane still has a foreground agent, so the idle-shell proof refuses. + printf '{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p2","shell_pid":%s,"foreground_process_group_id":%s,"foreground_processes":[{"pid":%s,"name":"zsh","argv0":"zsh"},{"pid":99999,"name":"pi","argv0":"pi"}]}}}\n' "$bgpid" "$bgpid" "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/9.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/11.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=1 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "a busy pane should fall back to the plain close: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "a busy pane did not use the plain close" + kill -0 "$bgpid" 2>/dev/null || fail "a busy pane close signaled the pane's shell" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: a pane with a live foreground process falls back to the plain close" +} + +test_projection_close_transient_prompt_helper_settles_then_uses_pane_death() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-transient-helper"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + # Sample 1: the shell is transiently redrawing its prompt (real 0.7.5 shape: + # a helper such as starship rides along as a second foreground process). + printf '{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p2","shell_pid":%s,"foreground_process_group_id":%s,"foreground_processes":[{"pid":99998,"name":"starship","argv":["/usr/local/bin/starship","prompt","--continuation"]},{"pid":%s,"name":"zsh","argv0":"zsh"}]}}}\n' "$bgpid" "$bgpid" "$bgpid" > "$resp/7.out" + # Sample 2: the helper finished; the shell is provably alone and idle. + death_process_info_fixture w2:p2 "$bgpid" > "$resp/8.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/9.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/11.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=3 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "a transient prompt helper should settle into the pane-death path: $out" + [ "$(grep -c $'pane\x1fprocess-info' "$log")" -ge 2 ] \ + || fail "the settle window did not retry the idle-shell proof" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "a transient prompt helper forced the focus-unsafe explicit close" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "focus moved despite the settled pane-death removal" + pass "herdr presentation cleanup: a transient prompt helper settles into the pane-death path instead of the plain close" +} + +test_projection_close_death_escalates_sigkill_after_sighup_survival() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-escalate"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + bash -c 'trap "" HUP; sleep 300' & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"internal_error","message":"transient failure"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/9.out" + death_process_info_fixture w2:p2 "$bgpid" > "$resp/10.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/11.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/12.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/13.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "a SIGHUP-surviving shell should be finished by the SIGKILL escalation: $out" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "the SIGKILL escalation used the focus-unsafe explicit close" + if kill -0 "$bgpid" 2>/dev/null; then + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + fail "the SIGKILL escalation left the trapped shell alive" + fi + wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: a SIGHUP-surviving shell is escalated to SIGKILL before giving up" +} + +test_projection_close_death_failure_falls_back_to_plain_close() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-fallback"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + bash -c 'trap "" HUP; sleep 300' & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/8.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/9.out" + death_process_info_fixture w2:p2 "$bgpid" > "$resp/10.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/11.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/12.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/14.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/15.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/16.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "an unkillable shell should fall back to the plain close: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "a failed pane-death close did not use the plain close fallback" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "herdr presentation cleanup: a failed pane-death close falls back to the plain close" +} + +test_projection_close_death_still_restores_a_stolen_focus() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-restore"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + # The backstop still fires when the post-close snapshot disagrees. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":true}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w3:t1","focused":true}]}}' > "$resp/10.out" + printf '%s\n' '{"result":{"tab":{"tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/11.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/13.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/14.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "the pane-death close with a restored backstop should succeed: $out" + assert_contains "$(cat "$log")" $'tab\x1ffocus\x1fw1:t1' "the backstop did not restore the exact prior tab" + pass "herdr presentation cleanup: the exact-tab restore remains the backstop behind the pane-death close" +} + +test_projection_close_death_never_sigkills_a_reused_pid() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/close-death-pid-reuse"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + # The original shell survives SIGHUP; by SIGKILL time the pane's process + # information shows a DIFFERENT shell pid, modeling the original pid having + # been reused by an unrelated process the pane no longer owns. + bash -c 'trap "" HUP; sleep 300' & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + cp "$resp/3.out" "$resp/8.out" # SIGHUP poll 1: pane still present + cp "$resp/3.out" "$resp/9.out" # SIGHUP poll 2: pane still present + death_process_info_fixture w2:p2 99997 > "$resp/10.out" + : > "$resp/11.out" # fallback explicit close: pane close ok + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/12.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/13.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/14.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w2:p2' "$ROOT" 2>&1) + status=$? + if ! kill -0 "$bgpid" 2>/dev/null; then + wait "$bgpid" 2>/dev/null || true + fail "the SIGKILL escalation signaled a pid the exact pane no longer owns" + fi + kill -KILL "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -eq 0 ] || fail "the refused escalation should fall back to the plain close: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "the refused escalation did not fall back to the plain close" + pass "herdr presentation cleanup: SIGKILL never reaches a pid the exact pane no longer owns" +} + +assert_projection_close_failed_removal_rolls_back_the_reposition() { + local mode=$1 dir log resp fb out status bgpid + dir="$TMP_ROOT/close-move-rollback-$mode"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + # Doomed w1 sits BEFORE the focused w2 (not last): the plan repositions it + # to the end; then every removal path fails, so the exact original order + # must be restored under the same session lock and the close must fail. + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w1:p1","tab_id":"w1:t1","workspace_id":"w1"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","workspace_id":"w1"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w1:p1","tab_id":"w1:t1"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + printf '%s\n' '{"client":{"version":"0.7.5","protocol":16},"server":{"running":true}}' > "$resp/7.out" + # shellcheck disable=SC2016 # $defs is a literal JSON Schema key. + printf '%s\n' '{"schemas":{"request":{"oneOf":[{"properties":{"method":{"const":"workspace.move"}}}],"$defs":{"WorkspaceMoveParams":{"required":["workspace_id","insert_index"],"properties":{"insert_index":{"type":"integer"}}}}}}}' > "$resp/8.out" + printf '%s\n' '{"sessions":[{"name":"fmtest","running":true,"socket_path":"/tmp/fmtest.sock"}]}' > "$resp/9.out" + bash -c 'trap "" HUP; sleep 300' & bgpid=$! + death_process_info_fixture w1:p1 "$bgpid" > "$resp/10.out" + if [ "$mode" = pane-gone-workspace-present ]; then + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/11.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false},{"workspace_id":"w1","active_tab_id":"w1:t2","focused":false}]}}' > "$resp/12.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t2","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/13.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/14.out" + else + cp "$resp/3.out" "$resp/11.out" # SIGHUP poll 1: pane still present + cp "$resp/3.out" "$resp/12.out" # SIGHUP poll 2: pane still present + death_process_info_fixture w1:p1 "$bgpid" > "$resp/13.out" # escalation resample: same owner + cp "$resp/3.out" "$resp/14.out" # SIGKILL poll 1: pane still present + cp "$resp/3.out" "$resp/15.out" # SIGKILL poll 2: pane still present + fi + if [ "$mode" = command-fails ]; then + printf '9\n' > "$resp/16.exit" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/17.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/18.out" + else + : > "$resp/16.out" + cp "$resp/3.out" "$resp/17.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t1","focused":true},{"workspace_id":"w3","active_tab_id":"w3:t1","focused":false}]}}' > "$resp/18.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t1","focused":true}]}}' > "$resp/19.out" + fi + make_death_lab "$dir" "$bgpid" + printf '%s\n' '{"id":"fm-workspace-move","result":{"type":"workspace_list","workspaces":[{"workspace_id":"w2","focused":true},{"workspace_id":"w3","focused":false},{"workspace_id":"w1","focused":false}]}}' > "$dir/mover-response" + printf '%s\n' '{"id":"fm-workspace-move","result":{"type":"workspace_list","workspaces":[{"workspace_id":"w1","focused":false},{"workspace_id":"w2","focused":true},{"workspace_id":"w3","focused":false}]}}' > "$dir/mover-response-2" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" FM_HERDR_SCRIPT_STATUS=1 \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/mover-response" \ + FM_FAKE_MOVER_RESPONSE_2="$dir/mover-response-2" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_close_pane_focus_preserving fmtest w1:p1' "$ROOT" 2>&1) + status=$? + kill -KILL "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + [ "$status" -ne 0 ] || fail "an unconfirmed removal must report failure: $out" + [ "$(wc -l < "$dir/mover.log" | tr -d ' ')" = 2 ] \ + || fail "a failed removal did not roll the reposition back exactly once: $(cat "$dir/mover.log")" + [ "$(sed -n '1p' "$dir/mover.log")" = "$(cd /tmp && pwd -P)/fmtest.sock"$'\t'"w1"$'\t'"3" ] \ + || fail "the reposition did not move the doomed workspace to the end: $(sed -n '1p' "$dir/mover.log")" + [ "$(sed -n '2p' "$dir/mover.log")" = "$(cd /tmp && pwd -P)/fmtest.sock"$'\t'"w1"$'\t'"0" ] \ + || fail "the rollback did not restore the doomed workspace to its exact original position: $(sed -n '2p' "$dir/mover.log")" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "a failed rolled-back removal moved focus" +} + +test_projection_close_failed_removal_rolls_back_the_reposition() { + assert_projection_close_failed_removal_rolls_back_the_reposition command-fails + assert_projection_close_failed_removal_rolls_back_the_reposition command-succeeds-pane-present + assert_projection_close_failed_removal_rolls_back_the_reposition pane-gone-workspace-present + pass "herdr presentation cleanup: every unconfirmed removal restores the exact original workspace order and reports failure" +} + +test_kill_emptying_non_focused_uses_pane_death() { + local dir log resp fb out status bgpid lock_log lock_held + dir="$TMP_ROOT/kill-death"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; lock_log="$dir/lock.log"; lock_held="$dir/lock-held" + : > "$log"; : > "$lock_log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":false}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","workspace_id":"w2"}]}}' > "$resp/4.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/5.out" + cp "$resp/1.out" "$resp/6.out" + sleep 300 & bgpid=$! + death_process_info_fixture w2:p2 "$bgpid" > "$resp/7.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/8.out" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":true}]}}' > "$resp/9.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w1:t1","focused":true}]}}' > "$resp/10.out" + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 FM_FAKE_LOCK_LOG="$lock_log" \ + FM_FAKE_LOCK_HELD="$lock_held" \ + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_target_ready() { fm_backend_herdr_parse_target "$1"; } + fm_backend_herdr_presentation_session_lock_path() { printf "%s" "$FM_FAKE_LOCK_HELD.lock"; } + fm_lock_try_acquire() { + printf "acquire\n" >> "$FM_FAKE_LOCK_LOG" + : > "$FM_FAKE_LOCK_HELD" + } + fm_lock_release() { + [ -e "$FM_FAKE_LOCK_HELD" ] || return 1 + rm -f "$FM_FAKE_LOCK_HELD" + printf "release\n" >> "$FM_FAKE_LOCK_LOG" + } + eval "$(declare -f fm_backend_herdr_cli | sed "1s/fm_backend_herdr_cli/fm_backend_herdr_cli_locked/")" + fm_backend_herdr_cli() { + [ -e "$FM_FAKE_LOCK_HELD" ] || return 97 + fm_backend_herdr_cli_locked "$@" + } + fm_backend_herdr_kill fmtest:w2:p2 + ' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "an emptying non-focused kill should stay best-effort: $out" + [ "$(cat "$lock_log")" = "$(printf 'acquire\nrelease')" ] \ + || fail "the generic kill did not hold one presentation lock across its complete mutation: $(cat "$lock_log")" + [ ! -e "$lock_held" ] || fail "the generic kill retained its presentation lock" + assert_not_contains "$(cat "$log")" $'pane\x1fclose' "an emptying non-focused kill used the focus-unsafe explicit close" + assert_not_contains "$(cat "$log")" $'tab\x1ffocus' "an emptying non-focused kill moved focus" + pass "fm_backend_herdr_kill: one session lock covers the focus-safe emptying removal" +} + +test_kill_focused_workspace_stays_plain_close() { + local dir log resp fb out status bgpid + dir="$TMP_ROOT/kill-focused"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; : > "$log" + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"w1","active_tab_id":"w1:t1","focused":false},{"workspace_id":"w2","active_tab_id":"w2:t2","focused":true}]}}' > "$resp/1.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","focused":true}]}}' > "$resp/2.out" + printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/3.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/5.out" + sleep 300 & bgpid=$! + make_death_lab "$dir" "$bgpid" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_HERDR_PS_BIN="$dir/ps" FM_BACKEND_HERDR_WORKSPACE_MOVER="$dir/mover" \ + FM_FAKE_MOVER_LOG="$dir/mover.log" FM_FAKE_MOVER_RESPONSE="$dir/no-response" \ + FM_BACKEND_HERDR_DEATH_CLOSE_POLLS=2 \ + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_presentation_session_lock_path() { printf "/tmp/fm-herdr-test-lock"; } + fm_lock_try_acquire() { return 0; } + fm_lock_release() { return 0; } + fm_backend_herdr_kill fmtest:w2:p2 + ' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "a focused-workspace kill should stay best-effort: $out" + assert_contains "$(cat "$log")" $'pane\x1fclose\x1fw2:p2' "a focused-workspace kill did not use the plain close" + assert_not_contains "$(cat "$log")" $'pane\x1fprocess-info' "a focused-workspace kill ran the idle-shell proof" + kill -0 "$bgpid" 2>/dev/null || fail "a focused-workspace kill signaled the pane's shell" + kill "$bgpid" 2>/dev/null || true; wait "$bgpid" 2>/dev/null || true + pass "fm_backend_herdr_kill: killing the focused workspace's tab keeps the legitimate plain close" +} + +test_kill_refuses_when_presentation_lock_is_unavailable() { + local dir mode out status attempts + dir="$TMP_ROOT/kill-lock-refusal"; mkdir -p "$dir" + for mode in unresolved contended; do + : > "$dir/cli.log" + : > "$dir/attempts" + out=$(ROOT="$ROOT" MODE="$mode" CLI_LOG="$dir/cli.log" ATTEMPTS="$dir/attempts" bash -c ' + . "$ROOT/bin/backends/herdr.sh" + fm_backend_herdr_target_ready() { fm_backend_herdr_parse_target "$1"; } + fm_backend_herdr_presentation_session_lock_path() { + [ "$MODE" = contended ] || return 1 + printf "/tmp/fm-herdr-contended-test-lock" + } + fm_lock_try_acquire() { + printf "x\n" >> "$ATTEMPTS" + return 1 + } + fm_backend_herdr_cli() { + printf "%s\n" "$*" >> "$CLI_LOG" + return 0 + } + sleep() { :; } + fm_backend_herdr_kill fmtest:w2:p2 + ' 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "$mode presentation lock refusal changed best-effort kill status: $status" + [ ! -s "$dir/cli.log" ] || fail "$mode presentation lock refusal still mutated Herdr: $(cat "$dir/cli.log")" + assert_contains "$out" "refusing an unlocked pane close" \ + "$mode presentation lock refusal did not report the deferred close" + attempts=$(wc -l < "$dir/attempts" | tr -d ' ') + if [ "$mode" = contended ]; then + [ "$attempts" = 50 ] || fail "contended presentation lock did not use the bounded wait: $attempts attempts" + else + [ "$attempts" = 0 ] || fail "unresolved presentation lock path attempted acquisition: $attempts" + fi + done + pass "fm_backend_herdr_kill: unavailable session locks defer every pane close" +} + +test_endpoint_confirmed_gone_gates_on_structured_presence() { + local out + out=$(bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_cli() { printf "%s\n" "$FM_FAKE_PRESENCE_RESPONSE"; return "${FM_FAKE_PRESENCE_STATUS:-0}"; } + check() { # <label> <response> <status> <mode> <expected-rc> + FM_FAKE_PRESENCE_RESPONSE=$2 FM_FAKE_PRESENCE_STATUS=$3 + rc=0 + fm_backend_herdr_endpoint_confirmed_gone fmtest:w2:p2 "$4" || rc=$? + [ "$rc" = "$5" ] || printf "MISMATCH %s: rc=%s expected=%s\n" "$1" "$rc" "$5" + } + check present-default "{\"result\":{\"pane\":{\"pane_id\":\"w2:p2\"}}}" 0 "" 1 + check present-strict "{\"result\":{\"pane\":{\"pane_id\":\"w2:p2\"}}}" 0 strict 1 + check notfound-default "{\"error\":{\"code\":\"pane_not_found\"}}" 1 "" 0 + check notfound-strict "{\"error\":{\"code\":\"pane_not_found\"}}" 1 strict 0 + check unknown-default "" 1 "" 1 + check unknown-strict "" 1 strict 1 + check othererror-default "{\"error\":{\"code\":\"internal\"}}" 1 "" 1 + check othererror-strict "{\"error\":{\"code\":\"internal\"}}" 1 strict 1 + # Missing or malformed endpoint identity is ambiguity, never proof of a + # gone pane: it must refuse record removal. + rc=0 + fm_backend_herdr_endpoint_confirmed_gone malformed-target strict || rc=$? + [ "$rc" = 1 ] || printf "MISMATCH malformed-target: rc=%s expected=1\n" "$rc" + rc=0 + fm_backend_herdr_endpoint_confirmed_gone "" || rc=$? + [ "$rc" = 1 ] || printf "MISMATCH empty-target: rc=%s expected=1\n" "$rc" + ' "$ROOT" 2>&1) + [ -z "$out" ] || fail "endpoint confirmed-gone gate matrix mismatch: $out" + pass "endpoint confirmed-gone: only structured not-found permits record removal and ambiguous identity refuses" +} + test_projection_seeded_prune_refuses_active_tab() { local dir log resp fb out status dir="$TMP_ROOT/projection-seeded-focus-active-refusal"; mkdir -p "$dir/responses" @@ -1104,6 +2068,54 @@ SH pass "herdr presentation ordering: an ambiguous existing worker block is warning-only and read-only" } +test_projection_order_anchors_the_parent_by_exact_id() { + local dir log resp fb mover layout out status + layout='{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate","focused":false},{"workspace_id":"w7","label":"firstmate","focused":false},{"workspace_id":"wH","label":"human-notes","focused":false},{"workspace_id":"w8","label":"└ new · p:ZyXwVuTsRqPoNmLkJiHgFe","focused":false}]}}' + + # Without the exact parent id, two same-labeled parents make the whole layout + # ambiguous and ordering steps aside. + dir="$TMP_ROOT/projection-order-dup-label"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; mover="$dir/mover"; : > "$log" + printf '%s\n' "$layout" > "$resp/1.out" + cat > "$mover" <<'SH' +#!/usr/bin/env bash +echo called > "$FM_FAKE_MOVER_CALLED" +exit 0 +SH + chmod +x "$mover" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_BACKEND_HERDR_WORKSPACE_MOVER="$mover" FM_FAKE_MOVER_CALLED="$dir/called" \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_order_best_effort fmtest w8 firstmate' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "ambiguous projection ordering must not fail the spawn" + assert_contains "$out" "ambiguous workspace layout" "a duplicated parent label should make label-anchored ordering step aside" + [ ! -e "$dir/called" ] || fail "ambiguous parent label attempted workspace.move" + + # With the launcher's exact parent workspace id, the same layout is no longer + # ambiguous: ordering gets past parent selection and stops later, on this + # fake's protocol, having still moved nothing. + dir="$TMP_ROOT/projection-order-exact-parent"; mkdir -p "$dir/responses" + log="$dir/log"; resp="$dir/responses"; mover="$dir/mover"; : > "$log" + printf '%s\n' "$layout" > "$resp/1.out" + cat > "$mover" <<'SH' +#!/usr/bin/env bash +echo called > "$FM_FAKE_MOVER_CALLED" +exit 0 +SH + chmod +x "$mover" + fb=$(make_herdr_fakebin "$dir") + out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ + FM_BACKEND_HERDR_WORKSPACE_MOVER="$mover" FM_FAKE_MOVER_CALLED="$dir/called" \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_projection_order_best_effort fmtest w8 firstmate w7' "$ROOT" 2>&1) + status=$? + [ "$status" -eq 0 ] || fail "exact-parent projection ordering must not fail the spawn" + assert_not_contains "$out" "ambiguous workspace layout" "the exact parent id should have resolved the duplicated label" + assert_contains "$out" "protocol" "exact-parent ordering did not reach its protocol gate" + [ ! -e "$dir/called" ] || fail "exact-parent ordering attempted workspace.move below the required protocol" + pass "herdr presentation ordering: the launcher's exact parent workspace id disambiguates a duplicated home label without moving anything" +} + test_projection_order_foreign_new_child_before_parent_is_read_only() { local dir log resp fb mover out status dir="$TMP_ROOT/projection-order-foreign-new"; mkdir -p "$dir/responses" @@ -1309,7 +2321,7 @@ test_projection_reclaim_refusal_matrix_is_non_mutating() { } test_projection_reclaim_replaces_only_exact_husk_and_advances_binding() { - local dir state home home_real log resp fb journal token label out calls create_line close_line + local dir state home home_real log resp fb journal token label out calls create_line close_line agent_line boundary_mutations dir="$TMP_ROOT/projection-reclaim-exact"; state="$dir/state"; home="$dir/home" mkdir -p "$dir/responses" "$state" "$home" home_real=$(cd "$home" && pwd -P) @@ -1325,7 +2337,7 @@ test_projection_reclaim_replaces_only_exact_husk_and_advances_binding() { ' "$ROOT" "$state" "$home_real") || fail "could not create exact reclaim journal fixture" journal="$state/fm-hibit-r1.herdr-presentation" label="└ hibit-r1 · p:$token" - printf '%s\n' "{\"result\":{\"workspaces\":[{\"workspace_id\":\"w1\",\"label\":\"firstmate\",\"focused\":true,\"active_tab_id\":\"w1:t1\"},{\"workspace_id\":\"w2\",\"label\":\"$label\",\"focused\":false,\"active_tab_id\":\"w2:t2\"}]}}" > "$resp/1.out" + printf '%s\n' "{\"result\":{\"workspaces\":[{\"workspace_id\":\"w0\",\"label\":\"firstmate\",\"focused\":false,\"active_tab_id\":\"w0:t1\"},{\"workspace_id\":\"w1\",\"label\":\"firstmate\",\"focused\":true,\"active_tab_id\":\"w1:t1\"},{\"workspace_id\":\"w2\",\"label\":\"$label\",\"focused\":false,\"active_tab_id\":\"w2:t2\"}]}}" > "$resp/1.out" printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","label":"fm-fm-hibit-r1"}]}}' > "$resp/2.out" printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p2","tab_id":"w2:t2"}]}}' > "$resp/3.out" printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/4.out" @@ -1344,13 +2356,17 @@ test_projection_reclaim_replaces_only_exact_husk_and_advances_binding() { printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2","tab_id":"w2:t2","workspace_id":"w2"}}}' > "$resp/17.out" printf '%s\n' '{"result":{"pane":{"pane_id":"w2:p2"}}}' > "$resp/18.out" printf '%s\n' '{"error":{"code":"agent_not_found"}}' > "$resp/19.out" - : > "$resp/20.out" - cp "$resp/6.out" "$resp/21.out" - cp "$resp/7.out" "$resp/22.out" - printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/23.out" - cp "$resp/1.out" "$resp/24.out" - printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t3","label":"fm-fm-hibit-r1"}]}}' > "$resp/25.out" - printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p3","tab_id":"w2:t3"}]}}' > "$resp/26.out" + # The emptying-close plan sees the replacement tab alongside the old husk + # tab, so the husk close stays plain. + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t2","label":"fm-fm-hibit-r1"},{"tab_id":"w2:t3","label":"fm-fm-hibit-r1"}]}}' > "$resp/20.out" + : > "$resp/21.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/22.out" + cp "$resp/6.out" "$resp/23.out" + cp "$resp/7.out" "$resp/24.out" + printf '%s\n' '{"error":{"code":"pane_not_found"}}' > "$resp/25.out" + cp "$resp/1.out" "$resp/26.out" + printf '%s\n' '{"result":{"tabs":[{"tab_id":"w2:t3","label":"fm-fm-hibit-r1"}]}}' > "$resp/27.out" + printf '%s\n' '{"result":{"panes":[{"pane_id":"w2:p3","tab_id":"w2:t3"}]}}' > "$resp/28.out" fb=$(make_herdr_fakebin "$dir") out=$(PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ bash -c ' @@ -1368,12 +2384,18 @@ test_projection_reclaim_replaces_only_exact_husk_and_advances_binding() { close_line=$(grep -n $'pane\x1fclose\x1fw2:p2' "$log" | cut -d: -f1) [ -n "$create_line" ] && [ -n "$close_line" ] && [ "$create_line" -lt "$close_line" ] \ || fail "reclaim did not create the exact replacement before closing the old husk" - [ "$(sed -n "$((close_line - 1))p" "$log")" = $'HERDR_SESSION=fmtest\x1fagent\x1fget\x1fw2:p2\x1f--session\x1ffmtest' ] \ - || fail "reclaim did not recheck the old pane agent state at the exact close boundary" + agent_line=$(grep -n $'agent\x1fget\x1fw2:p2' "$log" | tail -1 | cut -d: -f1) + [ -n "$agent_line" ] && [ "$agent_line" -lt "$close_line" ] \ + || fail "reclaim did not recheck the old pane agent state before the close" + boundary_mutations=$(sed -n "$((agent_line + 1)),$((close_line - 1))p" "$log" \ + | grep -Ev $'\x1f(tab\x1flist|pane\x1flist|workspace\x1flist)' || true) + [ -z "$boundary_mutations" ] \ + || fail "reclaim mutated between the old pane agent recheck and the close: $boundary_mutations" assert_not_contains "$calls" $'workspace\x1fclose' "reclaim introduced workspace-close authority" assert_not_contains "$calls" $'workspace\x1frename' "reclaim renamed the projected workspace" assert_not_contains "$calls" $'tab\x1ffocus' "focus-preserving reclaim changed an already-stable focus snapshot" - pass "herdr presentation reclaim: exact agent-free husk is replaced in place and journal/focus identities advance" + assert_not_contains "$calls" $'\x1fw0' "reclaim touched the same-labeled sibling parent" + pass "herdr presentation reclaim: exact agent-free husk survives duplicate parent labels while its sibling stays untouched" } test_projection_recovery_is_read_only_and_refuses_live_duplicate_risk() { @@ -1544,7 +2566,14 @@ test_kill_is_best_effort() { printf '1\n' > "$resp/1.exit" fb=$(make_herdr_fakebin "$dir") PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ - bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_kill default:w1:p2' "$ROOT" + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_target_ready() { fm_backend_herdr_parse_target "$1"; } + fm_backend_herdr_presentation_session_lock_path() { printf "/tmp/fm-herdr-test-lock"; } + fm_lock_try_acquire() { return 0; } + fm_lock_release() { return 0; } + fm_backend_herdr_kill default:w1:p2 + ' "$ROOT" expect_code 0 $? "kill must be best-effort (never fail even when the pane close call itself fails)" assert_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''close'$'\x1f''w1:p2' "kill did not call pane close on the right pane" pass "fm_backend_herdr_kill: calls pane close and stays best-effort on failure" @@ -1552,13 +2581,23 @@ test_kill_is_best_effort() { test_kill_rechecks_exact_task_binding() { local dir log resp fb + # Binding recheck runs before the lock-gated focus-safe close. Stub the lock + # and focus snapshot so the unit test isolates the binding gate, matching + # test_kill_is_best_effort's lock stubs for the new kill path. dir="$TMP_ROOT/kill-bound"; mkdir -p "$dir/responses"; log="$dir/log"; resp="$dir/responses"; : > "$log" printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"firstmate"}]}}\n' > "$resp/1.out" printf '{"result":{"tabs":[{"tab_id":"w1:t2","label":"fm-task-a"}]}}\n' > "$resp/2.out" printf '{"result":{"panes":[{"pane_id":"w1:p2","tab_id":"w1:t2"}]}}\n' > "$resp/3.out" fb=$(make_herdr_fakebin "$dir") PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ - bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_kill default:w1:p2 w1:t2 fm-task-a w1' "$ROOT" + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_presentation_session_lock_path() { printf "/tmp/fm-herdr-test-lock"; } + fm_lock_try_acquire() { return 0; } + fm_lock_release() { return 0; } + fm_backend_herdr_projection_focus_snapshot() { return 1; } + fm_backend_herdr_kill default:w1:p2 w1:t2 fm-task-a w1 + ' "$ROOT" assert_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''close'$'\x1f''w1:p2' \ "bound kill did not close the exactly labeled pane" @@ -1566,7 +2605,14 @@ test_kill_rechecks_exact_task_binding() { printf '{"result":{"workspaces":[{"workspace_id":"w1","label":"other-home"}]}}\n' > "$resp/1.out" fb=$(make_herdr_fakebin "$dir") PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_HERDR_RESPONSES="$resp" \ - bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_kill default:w1:p2 w1:t2 fm-task-a w1' "$ROOT" + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_presentation_session_lock_path() { printf "/tmp/fm-herdr-test-lock"; } + fm_lock_try_acquire() { return 0; } + fm_lock_release() { return 0; } + fm_backend_herdr_projection_focus_snapshot() { return 1; } + fm_backend_herdr_kill default:w1:p2 w1:t2 fm-task-a w1 + ' "$ROOT" assert_not_contains "$(cat "$log")" $'\x1f''pane'$'\x1f''close' \ "label-swapped Herdr endpoint reached pane close" pass "fm_backend_herdr_kill: rechecks owning workspace, tab label, and pane binding at mutation time" @@ -2439,7 +3485,13 @@ $ids EOF [ -n "$pane" ] || fail "cycle $i: create_task returned no pane id" PATH="$fb:$PATH" FM_HERDR_LOG="$log" FM_FAKE_HERDR_STATE="$state" HERDR_SESSION=fmtest \ - bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_kill "$1"' "$ROOT" "fmtest:$pane" \ + bash -c ' + . "$0/bin/backends/herdr.sh" + fm_backend_herdr_presentation_session_lock_path() { printf "/tmp/fm-herdr-cycle-test-lock"; } + fm_lock_try_acquire() { return 0; } + fm_lock_release() { return 0; } + fm_backend_herdr_kill "$1" + ' "$ROOT" "fmtest:$pane" \ || fail "cycle $i: kill failed" done # exactly one firstmate workspace survives three spawn/teardown cycles @@ -2902,6 +3954,19 @@ test_workspace_label_secondmate_marker_trims_whitespace test_workspace_label_empty_marker_falls_back_to_primary test_workspace_label_different_secondmates_get_different_labels test_cli_helper_sets_env_and_appends_trailing_session_flag +test_launcher_identity_absent_without_a_herdr_pane +test_launcher_identity_absent_when_herdr_env_alone_is_set +test_launcher_identity_resolves_the_exact_pane_tab_and_workspace +test_launcher_identity_refuses_a_pane_from_another_session_name +test_launcher_identity_refuses_a_missing_server_socket +test_launcher_identity_refuses_a_pane_from_another_server_socket +test_launcher_identity_refuses_an_unreadable_pane +test_launcher_identity_refuses_a_pane_and_tab_that_disagree +test_launcher_identity_refuses_a_workspace_missing_from_the_session +test_workspace_ensure_prefers_the_launcher_over_the_first_label_match +test_workspace_ensure_refuses_an_ambiguous_label_with_no_launcher +test_workspace_ensure_other_home_ignores_the_launcher_identity +test_container_ensure_refuses_an_ambiguous_home_label test_container_ensure_starts_server_and_workspace test_container_ensure_reuses_existing_workspace test_container_ensure_creates_with_no_focus_flag @@ -2931,6 +3996,25 @@ test_projection_close_restores_exact_prior_focus test_projection_close_refuses_active_tab test_projection_close_reports_focus_restore_failure test_projection_close_rechecks_required_agent_state_at_boundary +test_projection_close_emptying_after_focus_uses_pane_death_without_move +test_projection_close_emptying_before_focus_repositions_then_uses_pane_death +test_projection_close_emptying_before_last_focus_needs_no_move +test_projection_close_emptying_last_workspace_needs_no_move +test_projection_close_non_emptying_stays_plain_without_proof_or_move +test_projection_close_plain_without_move_requires_structured_removal +test_projection_close_ambiguous_positions_fall_back_to_plain_close +test_projection_close_move_failure_falls_back_to_plain_close +test_projection_close_busy_pane_falls_back_to_plain_close +test_projection_close_transient_prompt_helper_settles_then_uses_pane_death +test_projection_close_death_escalates_sigkill_after_sighup_survival +test_projection_close_death_failure_falls_back_to_plain_close +test_projection_close_death_still_restores_a_stolen_focus +test_projection_close_death_never_sigkills_a_reused_pid +test_projection_close_failed_removal_rolls_back_the_reposition +test_kill_emptying_non_focused_uses_pane_death +test_kill_focused_workspace_stays_plain_close +test_endpoint_confirmed_gone_gates_on_structured_presence +test_kill_refuses_when_presentation_lock_is_unavailable test_projection_seeded_prune_refuses_active_tab test_projection_label_builder_uses_corner_and_strips_owner_prefixes test_projection_order_moves_only_exact_new_workspace_and_preserves_relative_order @@ -2940,6 +4024,7 @@ test_projection_order_allows_intervening_parent_child_block test_projection_order_human_spaces_never_move_targets test_projection_order_failure_warns_without_cleanup_or_spawn_failure test_projection_order_ambiguous_existing_block_is_read_only +test_projection_order_anchors_the_parent_by_exact_id test_projection_order_foreign_new_child_before_parent_is_read_only test_projection_order_missing_parent_is_read_only test_presentation_session_lock_path_is_shared_across_homes diff --git a/tests/fm-backend.test.sh b/tests/fm-backend.test.sh index ba9f19ce113..5ac3336bd25 100755 --- a/tests/fm-backend.test.sh +++ b/tests/fm-backend.test.sh @@ -141,9 +141,10 @@ resolve_permissive_tmux_kill_ref() { # hence the dispatcher is a copied sibling, while the tmux adapter is extracted # from BASE_REF so conformance tests retain the exact historical behavior even # when this branch changes tmux dispatch semantics. -# fm-delivery-lib.sh and fm-operational-input.sh are copied siblings because the -# fork's teardown and marker compatibility paths source them unconditionally. -OLD_BIN_UNCHANGED_SIBLINGS="fm-gate-refuse-lib.sh fm-guard.sh fm-lock-lib.sh fm-tasks-axi-lib.sh fm-pr-lib.sh fm-delivery-lib.sh fm-tangle-lib.sh fm-tmux-lib.sh fm-composer-lib.sh fm-wake-lib.sh fm-classify-lib.sh fm-supervision-lib.sh fm-ff-lib.sh fm-config-inherit-lib.sh fm-project-mode.sh fm-harness.sh fm-crew-state.sh fm-decision-hold.sh fm-backend.sh fm-operational-input.sh" +# fm-delivery-lib.sh is a fork sibling because teardown sources the delivery gate. +# fm-public-followup-lib.sh, fm-secondmate-registry-lib.sh, and fm-x-lib.sh are +# upstream siblings teardown now requires for public-followup and registry paths. +OLD_BIN_UNCHANGED_SIBLINGS="fm-gate-refuse-lib.sh fm-guard.sh fm-lock-lib.sh fm-tasks-axi-lib.sh fm-pr-lib.sh fm-delivery-lib.sh fm-tangle-lib.sh fm-tmux-lib.sh fm-composer-lib.sh fm-wake-lib.sh fm-classify-lib.sh fm-supervision-lib.sh fm-ff-lib.sh fm-config-inherit-lib.sh fm-project-mode.sh fm-harness.sh fm-crew-state.sh fm-decision-hold.sh fm-backend.sh fm-operational-input.sh fm-public-followup-lib.sh fm-secondmate-registry-lib.sh fm-x-lib.sh" # A pull-request merge may add a new main-only dependency that the branch's older baseline does not have yet. OLD_BIN_OPTIONAL_SIBLINGS="fm-pending-reply-lib.sh" OLD_BIN_REFACTORED="fm-send.sh fm-peek.sh fm-watch.sh fm-spawn.sh fm-teardown.sh fm-marker-lib.sh" diff --git a/tests/fm-backlog-handoff.test.sh b/tests/fm-backlog-handoff.test.sh index b0b931d71f6..2efd8dd3d5c 100755 --- a/tests/fm-backlog-handoff.test.sh +++ b/tests/fm-backlog-handoff.test.sh @@ -482,9 +482,11 @@ test_registry_home_with_pre_home_parentheses() { setup_homes "$home" "$sub" "$id" local sub_abs sub_abs=$(cd "$sub" && pwd -P) - # Prose parentheses before (home: ...), matching live registry shape. - printf -- '- %s - issue triage (id is legacy) (home: %s; scope: issue triage; projects: alpha; added 2026-07-09)\n' \ + # Prose parentheses before (home: ...) and punctuation inside scope match the live registry shape. + printf -- '- %s - issue triage (id is legacy) (home: %s; scope: issue triage (child); semicolon is meaningful; projects: alpha; added 2026-07-09)\n' \ "$id" "$sub_abs" > "$home/data/secondmates.md" + FM_HOME="$home" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null \ + || fail "home-seed validation rejected punctuation-bearing registry fields" cat > "$home/data/backlog.md" <<'EOF' ## Queued diff --git a/tests/fm-bearings-snapshot.test.sh b/tests/fm-bearings-snapshot.test.sh index 0e17d0b55f2..f071a49e69a 100755 --- a/tests/fm-bearings-snapshot.test.sh +++ b/tests/fm-bearings-snapshot.test.sh @@ -78,6 +78,18 @@ make_home() { # <name> printf '%s\n' "$home" } +record_claude_state() { # <state-dir> <id> <busy|idle> + local state=$1 id=$2 semantic_state=$3 gen event + case "$semantic_state" in + busy) event=user-prompt-submit ;; + idle) event=stop ;; + *) fail "unsupported semantic fixture state: $semantic_state" ;; + esac + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" "$id") + "$ROOT/bin/fm-busy-event.sh" apply "$state" "$id" "$semantic_state" --gen "$gen" \ + --source claude-hook --event "$event" +} + fixture_mate_home() { # <parent-home> printf '%s/%s-secondmate-home\n' "$TMP_ROOT" "$(basename "$1")" } @@ -111,18 +123,20 @@ EOF "window=firstmate:fm-ship-task" \ "worktree=$home/projects/ship-wt" \ "project=firstmate" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=no-mistakes" \ "pr=https://github.com/kunchenguid/firstmate/pull/9" + record_claude_state "$home/state" ship-task busy printf 'working: building the thing\n' > "$home/state/ship-task.status" fm_write_meta "$home/state/scout-x.meta" \ "window=firstmate:fm-scout-x" \ "worktree=$home/projects/ship-wt" \ "project=firstmate" \ - "harness=codex" \ + "harness=claude" \ "kind=scout" \ "mode=scout" + record_claude_state "$home/state" scout-x idle printf 'done: report ready\n' > "$home/state/scout-x.status" fm_write_meta "$home/state/mate.meta" \ "window=firstmate:fm-mate" \ @@ -139,9 +153,10 @@ EOF "window=firstmate:fm-external-wait" \ "worktree=$home/projects/ship-wt" \ "project=firstmate" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=no-mistakes" + record_claude_state "$home/state" external-wait idle printf 'paused: declared external-wait for upstream release\n' > "$home/state/external-wait.status" # The secondmate's OWN home backlog records a merge it managed. This lands in the # secondmate home, never the main backlog, so landed-work views only see it via the @@ -159,7 +174,8 @@ EOF mkdir -p "$mate/projects/mate" fm_write_meta "$mate/state/mate.meta" \ "window=firstmate:fm-mate" "worktree=$mate/projects/mate" "project=firstmate" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$mate/state" mate idle printf 'needs-decision [key=race]: pick subscribe order\n' > "$mate/state/mate.status" } @@ -370,7 +386,8 @@ test_structured_child_decision_reaches_captains_call() { EOF fm_write_meta "$mate/state/phase8.meta" \ "window=firstmate:fm-phase8" "worktree=$mate/projects/phase8" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$mate/state" phase8 idle printf 'needs-decision [key=release]: choose release A or B\n' > "$mate/state/phase8.status" fakebin=$(make_fakebin "$home") json=$(run "$home" "$fakebin" --json) @@ -530,7 +547,8 @@ test_secondmate_and_child_bounds_are_disclosed() { printf -- '- [ ] %s - Active %s (repo: sample) (kind: ship) (since 2026-07-13)\n' "$child" "$child" >> "$mate/data/backlog.md" fm_write_meta "$mate/state/$child.meta" \ "window=firstmate:fm-$child" "worktree=$mate/projects/$child" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$mate/state" "$child" busy printf 'working [key=%s]: active child %s\n' "$child" "$i" > "$mate/state/$child.status" i=$((i + 1)) done @@ -639,7 +657,8 @@ EOF EOF fm_write_meta "$decision/state/$child.meta" \ "window=firstmate:fm-$child" "worktree=$decision/projects/$child" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$decision/state" "$child" idle printf 'needs-decision [key=live-route]: choose the current route\n' > "$decision/state/$child.status" fakebin=$(make_fakebin "$home") canonical=$(PATH="$fakebin:$PATH" FM_HOME="$home" FM_SNAPSHOT_NOW=2026-07-11T18:00:00Z \ @@ -691,7 +710,8 @@ test_nonprogressing_child_states_are_explicit() { EOF fm_write_meta "$mate/state/parked.meta" \ "window=firstmate:fm-parked" "worktree=$mate/projects/parked" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$mate/state" parked idle printf 'needs-decision [key=parked]: choose a route\n' > "$mate/state/parked.status" fakebin=$(make_fakebin "$home") canonical=$(PATH="$fakebin:$PATH" FM_HOME="$home" FM_SNAPSHOT_NOW=2026-07-11T18:00:00Z \ @@ -728,10 +748,12 @@ EOF EOF fm_write_meta "$mate/state/done.meta" \ "window=firstmate:fm-done" "worktree=$mate/projects/done" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" fm_write_meta "$mate/state/failed.meta" \ "window=firstmate:fm-failed" "worktree=$mate/projects/failed" "project=sample" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$mate/state" "done" idle + record_claude_state "$mate/state" failed idle printf 'done: complete\n' > "$mate/state/done.status" printf 'failed: stopped\n' > "$mate/state/failed.status" rm "$mate/state/parked.meta" "$mate/state/parked.status" @@ -1368,6 +1390,7 @@ test_live_blocker_is_not_charted_queue_work() { local home fakebin json home=$(make_home live-blocker); write_fixture "$home" printf 'blocked [key=synthetic-dependency]: firstmate can refresh the synthetic token\n' > "$home/state/ship-task.status" + record_claude_state "$home/state" ship-task idle fakebin=$(make_fakebin "$home") json=$(run "$home" "$fakebin" --json) printf '%s' "$json" | jq -e ' @@ -1566,7 +1589,8 @@ test_mixed_secondmate_roles_partial_state_and_captain_readiness() { EOF fm_write_meta "$hibit/state/hibit-worker.meta" \ "window=firstmate:fm-hibit-worker" "worktree=$hibit/projects/worker" "project=hibit" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$hibit/state" hibit-worker busy printf 'working: finalizing progress\n' > "$hibit/state/hibit-worker.status" cat > "$wheel/data/backlog.md" <<'EOF' @@ -1580,7 +1604,8 @@ EOF EOF fm_write_meta "$wheel/state/wheel-worker.meta" \ "window=firstmate:fm-wheel-worker" "worktree=$wheel/projects/worker" "project=wheelhouse" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$wheel/state" wheel-worker busy printf 'working: active validation\n' > "$wheel/state/wheel-worker.status" cat > "$sshhip/data/backlog.md" <<'EOF' @@ -1609,7 +1634,8 @@ EOF EOF fm_write_meta "$ha/state/prep.meta" \ "window=firstmate:fm-prep" "worktree=$ha/projects/prep" "project=home-assistant" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$ha/state" prep busy printf 'working: preparing canary\n' > "$ha/state/prep.status" fakebin=$(make_fakebin "$home") @@ -1713,7 +1739,8 @@ EOF fm_write_meta "$wheel/state/production-observation.meta" \ "window=firstmate:fm-production-observation" "worktree=$wheel/projects/worker" "project=wheelhouse" \ - "harness=codex" "kind=scout" "mode=scout" + "harness=claude" "kind=scout" "mode=scout" + record_claude_state "$wheel/state" production-observation idle printf 'paused: observation is deliberately held\n' > "$wheel/state/production-observation.status" canonical=$(PATH="$fakebin:$PATH" FM_HOME="$home" FM_SNAPSHOT_NOW=2026-07-11T18:00:00Z \ "$ROOT/bin/fm-fleet-snapshot.sh" --json) @@ -1726,7 +1753,8 @@ EOF fm_write_meta "$sshhip/state/unreadable-child.meta" \ "window=firstmate:fm-unreadable-child" "worktree=$sshhip/projects/child" "project=sshhip" \ - "harness=codex" "kind=ship" "mode=no-mistakes" + "harness=claude" "kind=ship" "mode=no-mistakes" + record_claude_state "$sshhip/state" unreadable-child busy printf 'working: app store submission restored\n' > "$sshhip/state/unreadable-child.status" json=$(run "$home" "$fakebin" --json) printf '%s' "$json" | jq -e ' diff --git a/tests/fm-bootstrap.test.sh b/tests/fm-bootstrap.test.sh index 219d74de58a..6c72c0bbc45 100755 --- a/tests/fm-bootstrap.test.sh +++ b/tests/fm-bootstrap.test.sh @@ -78,6 +78,10 @@ add_quota_axi() { local fakebin=$1 cat > "$fakebin/quota-axi" <<'SH' #!/usr/bin/env bash +if [ "${1:-}" = --version ]; then + printf '%s\n' "${FM_FAKE_QUOTA_AXI_VERSION:-0.1.16}" + exit 0 +fi exit 0 SH chmod +x "$fakebin/quota-axi" @@ -322,6 +326,43 @@ ROWS pass "bootstrap enforces no-mistakes minimum version" } +# 0.1.16 is the first quota-axi that reports per-credential auth sources and Grok +# state.authStatus. Before it, a dispatch candidate could not be scoped to its own +# authentication surface, which is exactly how one harness's expired CLI token +# produced a captain-facing "log in" claim for a candidate that never read it. A +# stale install used to pass this check silently, so the fix stayed uninstalled. +test_quota_axi_min_version() { + local label version mode case_dir fakebin out missing n + missing='MISSING: quota-axi (install: npm install -g quota-axi)' + n=0 + while IFS='^' read -r label version mode; do + [ -n "$label" ] || continue + n=$((n + 1)) + case_dir="$TMP_ROOT/quota-axi-$n" + mkdir -p "$case_dir/home/config" + printf '%s\n' manual > "$case_dir/home/config/backlog-backend" + fakebin=$(make_fake_toolchain "$case_dir") + add_tasks_axi "$fakebin" "0.1.1" + out=$(PATH="$fakebin:$BASE_PATH" FM_HOME="$case_dir/home" FM_ROOT_OVERRIDE="$case_dir/home" \ + FM_FAKE_TREEHOUSE_LEASE_HELP=1 FM_FAKE_QUOTA_AXI_VERSION="$version" "$ROOT/bin/fm-bootstrap.sh") + case "$mode" in + empty) + [ -z "$out" ] || fail "$label: expected silence, got: $out" ;; + missing) + [ "$out" = "$missing" ] || fail "$label: expected '$missing', got: $out" ;; + esac + done <<'ROWS' +minimum quota-axi version is accepted^0.1.16^empty +newer quota-axi patch is accepted^0.1.17^empty +newer quota-axi minor is accepted^0.2.0^empty +newer quota-axi major is accepted^1.0.0^empty +older quota-axi patch reports an upgrade^0.1.15^missing +much older quota-axi minor reports an upgrade^0.0.9^missing +unparseable quota-axi version reports an upgrade^quota-axi development build^missing +ROWS + pass "bootstrap enforces quota-axi minimum version" +} + test_git_is_required_with_supported_install_instruction() { local case_dir fakebin bash_env out expected case_dir="$TMP_ROOT/git-required" @@ -655,6 +696,7 @@ make_routine_bootstrap_fixture() { printf '%s\n' '.fm-secondmate-home' printf '%s\n' 'config/crew-harness' printf '%s\n' 'config/crew-dispatch.json' + printf '%s\n' 'config/startup-memory-budget' } > "$root/.gitignore" printf '%s\n' 'instructions' > "$root/AGENTS.md" mkdir -p "$root/bin" "$root/.agents/skills" @@ -792,6 +834,7 @@ ROWS test_bootstrap_reporting test_no_mistakes_min_version +test_quota_axi_min_version test_git_is_required_with_supported_install_instruction test_orca_backend_gates_orca_tool_only_when_selected test_session_provider_backends_do_not_require_tmux diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh index 7a9eb329d0f..2012f61643c 100755 --- a/tests/fm-brief.test.sh +++ b/tests/fm-brief.test.sh @@ -234,6 +234,12 @@ test_faster_paths_use_configured_authority_without_stacked_review() { "local-only brief hard-coded captain-only authority" assert_no_grep "Firstmate then reviews your branch diff" "$brief" \ "local-only brief retained a personal review stacked on the selected delivery path" + assert_no_grep "make \`--intent\` preserve all relevant content from this brief" "$home/data/$id/brief.md" \ + "local-only brief must not include the no-mistakes --intent contract" + id="brief-direct-intent-a4" + FM_HOME="$home" "$ROOT/bin/fm-brief.sh" "$id" direct-proj >/dev/null 2>&1 + assert_no_grep "make \`--intent\` preserve all relevant content from this brief" "$home/data/$id/brief.md" \ + "direct-PR brief must not include the no-mistakes --intent contract" pass "fm-brief.sh: faster paths use configured authority without stacked review" } @@ -255,6 +261,14 @@ test_no_mistakes_dod_wording() { # shellcheck disable=SC2016 # single quotes are deliberate: the backticks must stay literal assert_grep '`help`' "$brief" \ "no-mistakes DOD must render literal backticks around help" + assert_grep "make \`--intent\` preserve all relevant content from this brief" "$brief" \ + "no-mistakes DOD must require --intent to retain the accepted task contract" + assert_grep "carrying only each requirement's current accepted form" "$brief" \ + "no-mistakes DOD must replace superseded requirements with their current accepted form" + assert_grep "retain direct requirements instead of substituting a diff summary" "$brief" \ + "no-mistakes DOD must keep direct requirements and exclude generic scaffold boilerplate from --intent" + assert_grep "exclude generic operational, status, delivery, and other scaffold boilerplate unless it is task-specific" "$brief" \ + "no-mistakes DOD must exclude non-task-specific scaffold boilerplate from --intent" # The apostrophe in "firstmate's authority check" is now structurally safe # (no `$(...)` wrapper around the heredoc), so it renders verbatim instead of # being reworded or escaped away. test_no_heredoc_in_command_substitution diff --git a/tests/fm-busy-adapter-wiring.test.sh b/tests/fm-busy-adapter-wiring.test.sh new file mode 100755 index 00000000000..4636da5f794 --- /dev/null +++ b/tests/fm-busy-adapter-wiring.test.sh @@ -0,0 +1,350 @@ +#!/usr/bin/env bash +# Behavior tests for the per-adapter semantic busy-state wiring that +# bin/fm-spawn.sh installs under the contract owned by bin/fm-busy-lib.sh. +# +# These tests run the REAL fm-spawn against a fake tmux pane and an isolated +# git worktree, then drive the generated adapter artifact (the Pi extension, +# the OpenCode plugin) in a plain Node host, so the artifact, the real +# bin/fm-busy-event.sh writer, and the real classifier are exercised together +# with no live harness session. +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +# shellcheck source=/dev/null +. "$ROOT/bin/fm-busy-lib.sh" + +SPAWN="$ROOT/bin/fm-spawn.sh" +TMP_ROOT=$(fm_test_tmproot fm-busy-adapter-wiring) + +make_spawn_fakebin() { + local dir=$1 fakebin + fakebin=$(fm_fakebin "$dir") + cat > "$fakebin/tmux" <<'SH' +#!/usr/bin/env bash +set -u +case "$*" in + *"#{pane_current_path}"*) printf '%s\n' "${FM_FAKE_PANE_PATH:-}"; exit 0 ;; +esac +case "${1:-}" in + display-message) printf 'firstmate\n'; exit 0 ;; + list-windows) exit 0 ;; + has-session|new-session|new-window|kill-window|send-keys) exit 0 ;; +esac +exit 0 +SH + chmod +x "$fakebin/tmux" + fm_fake_exit0 "$fakebin" treehouse pi opencode claude codex + printf '%s\n' "$fakebin" +} + +make_spawn_case() { # <name> <harness> <id> + local name=$1 harness=$2 id=$3 case_dir home proj wt fakebin + case_dir="$TMP_ROOT/$name" + home="$case_dir/home" + proj="$case_dir/project" + wt="$case_dir/wt" + fakebin=$(make_spawn_fakebin "$case_dir/fake") + mkdir -p "$home/data" "$home/projects" "$home/state" "$home/config" + printf '%s\n' "$harness" > "$home/config/crew-harness" + fm_git_worktree "$proj" "$wt" "wt-$name" + touch "$home/state/.last-watcher-beat" + mkdir -p "$home/data/$id" + printf 'brief for %s\n' "$id" > "$home/data/$id/brief.md" + printf '%s\n' "$case_dir|$home|$proj|$wt|$fakebin" +} + +run_spawn() { # <home> <wt> <fakebin> <spawn-args...> + local home=$1 wt=$2 fakebin=$3 + shift 3 + FM_ROOT_OVERRIDE='' FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \ + FM_PROJECTS_OVERRIDE="$home/projects" FM_CONFIG_OVERRIDE="$home/config" \ + FM_SPAWN_NO_GUARD=1 FM_FAKE_PANE_PATH="$wt" TMUX="fake,1,0" \ + GROK_HOME="$home/grok-home" PATH="$fakebin:$PATH" \ + "$SPAWN" "$@" 2>&1 +} + +read_case_record() { + # shellcheck disable=SC2034 # CASE_DIR is part of the shared record shape + IFS='|' read -r CASE_DIR HOME_DIR PROJ_DIR WT_DIR FAKEBIN_DIR <<EOF +$1 +EOF +} + +classify() { # <harness> <id> <state-dir> + fm_busy_classify tmux fake:w "$1" "$2" "$3" +} + +# drive_pi_ext <ext-path> <mode>: load the generated Pi extension in a plain +# Node host and fire one lifecycle handler. Modes: agent-start, settle-idle, +# settle-continuing, turn-end. +drive_pi_ext() { + EXT_PATH="$1" MODE="$2" node --input-type=module 2>&1 <<'EOF' +import { pathToFileURL } from "node:url"; +const mod = await import(pathToFileURL(process.env.EXT_PATH).href); +const handlers = {}; +mod.default({ on: (name, fn) => { handlers[name] = fn; } }); +const ctx = { isIdle: () => process.env.MODE !== "settle-continuing" }; +switch (process.env.MODE) { + case "agent-start": await handlers["agent_start"]({}, ctx); break; + case "settle-idle": await handlers["agent_settled"]({}, ctx); break; + case "settle-continuing": await handlers["agent_settled"]({}, ctx); break; + case "settle-then-start": + await handlers["agent_settled"]({}, ctx); + await handlers["agent_start"]({}, ctx); + break; + case "turn-end": await handlers["turn_end"]({}, ctx); break; + default: throw new Error("unknown mode " + process.env.MODE); +} +if (process.env.MODE === "turn-end") { + await new Promise((resolve) => setTimeout(resolve, 200)); +} +EOF +} + +test_pi_extension_semantic_lifecycle() { + local rec id=busy-pi-1 out state ext + rec=$(make_spawn_case pi-lifecycle pi "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "pi spawn should succeed: $out" + state="$HOME_DIR/state" + ext="$state/$id.pi-ext.ts" + assert_present "$ext" "pi spawn did not write the per-task extension" + + out=$(classify pi "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "seed after spawn must be 'busy fm-spawn', got '$out'" + + rm -f "$state/$id.turn-ended" + out=$(drive_pi_ext "$ext" turn-end) || fail "turn_end drive failed: $out" + [ -f "$state/$id.turn-ended" ] || fail "turn_end no longer touches the notification marker" + out=$(classify pi "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "turn_end must stay a notification, not a state edge, got '$out'" + + out=$(drive_pi_ext "$ext" settle-idle) || fail "agent_settled drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "idle pi-ext" ] || fail "agent_settled with isIdle must classify 'idle pi-ext', got '$out'" + + out=$(drive_pi_ext "$ext" agent-start) || fail "agent_start drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "busy pi-ext" ] || fail "agent_start must classify 'busy pi-ext', got '$out'" + + out=$(drive_pi_ext "$ext" settle-continuing) || fail "continuing settle drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "busy pi-ext" ] || fail "a settle while another run continues must stay busy, got '$out'" + + out=$(drive_pi_ext "$ext" settle-idle) || fail "final settle drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "idle pi-ext" ] || fail "the final settle must classify idle, got '$out'" + pass "pi extension reports agent_start busy, settles idle only via ctx.isIdle(), and keeps turn_end a notification" +} + +test_pi_extension_serializes_settle_before_next_start() { + local rec id=busy-pi-order out state ext + rec=$(make_spawn_case pi-order pi "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "pi spawn should succeed: $out" + state="$HOME_DIR/state" + ext="$state/$id.pi-ext.ts" + + out=$(drive_pi_ext "$ext" settle-then-start) || fail "settle/start drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "busy pi-ext" ] || fail "a fresh agent_start after agent_settled must win, got '$out'" + pass "pi extension awaits agent_settled before the next agent_start without a test delay" +} + +test_pi_extension_stale_incarnation_rejected() { + local rec id=busy-pi-2 out state ext + rec=$(make_spawn_case pi-stale pi "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "pi spawn should succeed: $out" + state="$HOME_DIR/state" + ext="$state/$id.pi-ext.ts" + # A re-arm (a rewired incarnation) supersedes the gen embedded in the old + # extension file: its late events must be rejected and never change state. + "$ROOT/bin/fm-busy-event.sh" arm "$state" "$id" >/dev/null + out=$(drive_pi_ext "$ext" settle-idle) || fail "stale settle drive failed: $out" + out=$(classify pi "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "a stale extension event must not change state, got '$out'" + pass "pi extension events from a superseded incarnation are rejected as stale" +} + +# drive_oc_plugin <plugin-path> <events-json-lines...>: load the generated +# OpenCode plugin in a plain Node host and feed it one event per argument, in +# order, through the same hooks.event entry OpenCode calls. +drive_oc_plugin() { + local plugin=$1 + shift + PLUGIN_PATH="$plugin" node --input-type=module - "$@" 2>&1 <<'EOF' +import { pathToFileURL } from "node:url"; +const mod = await import(pathToFileURL(process.env.PLUGIN_PATH).href); +const hooks = await mod.FmBusyState({}); +for (const arg of process.argv.slice(2)) { + await hooks.event({ event: JSON.parse(arg) }); +} +EOF +} + +oc_status() { # <sessionID> <type> + printf '{"type":"session.status","properties":{"sessionID":"%s","status":{"type":"%s"}}}' "$1" "$2" +} + +oc_idle() { # <sessionID> + printf '{"type":"session.idle","properties":{"sessionID":"%s"}}' "$1" +} + +test_opencode_plugin_semantic_lifecycle() { + local rec id=busy-oc-1 out state plugin + rec=$(make_spawn_case oc-lifecycle opencode "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "opencode spawn should succeed: $out" + state="$HOME_DIR/state" + plugin="$WT_DIR/.opencode/plugins/fm-busy-state.js" + assert_present "$plugin" "opencode spawn did not write the busy-state plugin" + + out=$(classify opencode "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "seed after spawn must be 'busy fm-spawn', got '$out'" + + out=$(drive_oc_plugin "$plugin" "$(oc_status ses_main busy)") || fail "busy drive failed: $out" + out=$(classify opencode "$id" "$state") + [ "$out" = "busy opencode-plugin" ] || fail "session busy must classify 'busy opencode-plugin', got '$out'" + + out=$(drive_oc_plugin "$plugin" \ + "$(oc_status ses_main busy)" \ + "$(oc_status ses_child busy)" \ + "$(oc_status ses_child idle)") || fail "child-session drive failed: $out" + out=$(classify opencode "$id" "$state") + [ "$out" = "busy opencode-plugin" ] || fail "a child session's idle must not clear the worker, got '$out'" + + out=$(drive_oc_plugin "$plugin" \ + "$(oc_status ses_main retry)" \ + "$(oc_status ses_main idle)") || fail "retry/idle drive failed: $out" + out=$(classify opencode "$id" "$state") + [ "$out" = "idle opencode-plugin" ] || fail "the latched session's idle must classify idle, got '$out'" + + rm -f "$state/$id.turn-ended" + out=$(drive_oc_plugin "$plugin" \ + "$(oc_status ses_main busy)" \ + "$(oc_idle ses_main)") || fail "session.idle drive failed: $out" + [ -f "$state/$id.turn-ended" ] || fail "session.idle no longer touches the notification marker" + out=$(classify opencode "$id" "$state") + [ "$out" = "idle opencode-plugin" ] || fail "session.idle for the latched session must classify idle, got '$out'" + + rm -f "$state/$id.turn-ended" + out=$(drive_oc_plugin "$plugin" \ + "$(oc_status ses2 busy)" \ + "$(oc_idle ses_other)") || fail "other-session idle drive failed: $out" + [ -f "$state/$id.turn-ended" ] || fail "the marker touch must stay a notification for every session.idle" + out=$(classify opencode "$id" "$state") + [ "$out" = "busy opencode-plugin" ] || fail "another session's idle must not clear the latched busy, got '$out'" + pass "opencode plugin classifies from session.status, scoped to the latched worker session" +} + +run_claude_hook() { # <settings.json> <hook-event> + local cmd + cmd=$(jq -r ".hooks[\"$2\"][0].hooks[0].command" "$1") + [ -n "$cmd" ] && [ "$cmd" != null ] || fail "no $2 hook command in $1" + sh -c "$cmd" +} + +test_claude_hooks_semantic_lifecycle() { + local rec id=busy-cl-1 out state settings + rec=$(make_spawn_case claude-lifecycle claude "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "claude spawn should succeed: $out" + state="$HOME_DIR/state" + settings="$WT_DIR/.claude/settings.local.json" + assert_present "$settings" "claude spawn did not write hook settings" + jq -e . "$settings" >/dev/null || fail "claude hook settings are not valid JSON" + for ev in UserPromptSubmit Stop StopFailure SessionEnd; do + jq -e ".hooks[\"$ev\"]" "$settings" >/dev/null || fail "claude hook settings lack $ev" + done + + out=$(classify claude "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "seed after spawn must be 'busy fm-spawn', got '$out'" + + rm -f "$state/$id.turn-ended" + run_claude_hook "$settings" Stop || fail "Stop hook command failed" + [ -f "$state/$id.turn-ended" ] || fail "Stop no longer touches the notification marker" + out=$(classify claude "$id" "$state") + [ "$out" = "idle claude-hook" ] || fail "Stop must classify 'idle claude-hook', got '$out'" + + run_claude_hook "$settings" UserPromptSubmit || fail "UserPromptSubmit hook command failed" + out=$(classify claude "$id" "$state") + [ "$out" = "busy claude-hook" ] || fail "UserPromptSubmit must classify 'busy claude-hook', got '$out'" + + run_claude_hook "$settings" StopFailure || fail "StopFailure hook command failed" + out=$(classify claude "$id" "$state") + [ "$out" = "idle claude-hook" ] || fail "StopFailure must classify idle so an API error cannot strand busy, got '$out'" + + run_claude_hook "$settings" UserPromptSubmit + run_claude_hook "$settings" SessionEnd || fail "SessionEnd hook command failed" + out=$(classify claude "$id" "$state") + [ "$out" = "idle claude-hook" ] || fail "SessionEnd must classify idle, got '$out'" + pass "claude hooks open on UserPromptSubmit and close on Stop, StopFailure, and SessionEnd" +} + +test_claude_hooks_stale_incarnation_harmless() { + local rec id=busy-cl-2 out state settings + rec=$(make_spawn_case claude-stale claude "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "claude spawn should succeed: $out" + state="$HOME_DIR/state" + settings="$WT_DIR/.claude/settings.local.json" + "$ROOT/bin/fm-busy-event.sh" arm "$state" "$id" >/dev/null + run_claude_hook "$settings" UserPromptSubmit \ + || fail "a stale-gen hook must still exit 0 so Claude's lifecycle is never broken" + out=$(classify claude "$id" "$state") + [ "$out" = "busy fm-spawn" ] || fail "a stale-gen hook event must not change state, got '$out'" + pass "claude hook events from a superseded incarnation are rejected without breaking the hook" +} + +test_codex_unverified_until_a_semantic_source_exists() { + local rec id=busy-cx-1 out state + rec=$(make_spawn_case codex-unverified codex "$id") + read_case_record "$rec" + out=$(run_spawn "$HOME_DIR" "$WT_DIR" "$FAKEBIN_DIR" "$id" "$PROJ_DIR") + expect_code 0 $? "codex spawn should succeed: $out" + state="$HOME_DIR/state" + assert_absent "$state/$id.busy-gen" "codex must not arm a busy contract with no verified semantic source" + assert_absent "$WT_DIR/.codex/hooks.json" "codex must not install unverified busy hooks" + assert_contains "$out" 'spawned '"$id"' harness=codex' "codex spawn did not complete normally" + out=$(classify codex "$id" "$state") + [ "$out" = "unknown codex-unverified" ] || fail "codex must classify 'unknown codex-unverified', got '$out'" + out=$(fm_busy_classify tmux fake:w codex "$id" "$state" '• Working (6s • esc to interrupt)') + [ "$out" = "unknown codex-unverified" ] || fail "codex must not fall back to footer text, got '$out'" + pass "codex classifies unknown until a semantic source is verified, never idle or footer-matched" +} + +test_kimi_and_grok_install_no_unverified_wiring() { + local state out + state="$TMP_ROOT/gates/state" + mkdir -p "$state" + [ -z "$(fm_busy_sources_for_harness kimi)" ] \ + || fail "standalone kimi must trust no semantic source until it is verified" + [ -z "$(fm_busy_sources_for_harness grok)" ] \ + || fail "grok must trust no semantic source while its structured path is unverified" + out=$(fm_busy_classify tmux fake:w kimi gate-k "$state" '🌒 · thinking') + [ "$out" = "unknown kimi-unverified" ] || fail "kimi must classify unknown, not from its spinner, got '$out'" + out=$(fm_busy_classify tmux fake:w grok gate-g "$state" 'Ctrl+c:cancel') + [ "$out" = "busy grok-regex" ] || fail "grok must classify through its isolated fallback, got '$out'" + pass "kimi and grok install no unverified semantic wiring and classify through their own gates" +} + +test_pi_extension_semantic_lifecycle +test_pi_extension_serializes_settle_before_next_start +test_pi_extension_stale_incarnation_rejected +test_kimi_and_grok_install_no_unverified_wiring +test_opencode_plugin_semantic_lifecycle +test_claude_hooks_semantic_lifecycle +test_claude_hooks_stale_incarnation_harmless +test_codex_unverified_until_a_semantic_source_exists + +echo "all fm-busy-adapter-wiring tests passed" diff --git a/tests/fm-busy-state.test.sh b/tests/fm-busy-state.test.sh new file mode 100755 index 00000000000..a6777a6b932 --- /dev/null +++ b/tests/fm-busy-state.test.sh @@ -0,0 +1,380 @@ +#!/usr/bin/env bash +# Behavior tests for the semantic busy-state contract (bin/fm-busy-lib.sh and +# its only writer bin/fm-busy-event.sh). +# +# Covers the captain-approved redesign invariants: busy/idle/unknown/dead with +# explicit source attribution; missing, malformed, stale (gen-mismatch), and +# untrusted (source-mismatch) semantic data classify unknown - never idle; +# adapter isolation (one adapter's writer or Grok's regex can never classify +# another adapter); endpoint death is the only process-level override and +# yields dead, never busy; converted adapters never classify from rendered +# footer text. All hermetic over temp dirs; no real agent session is invoked. +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +# shellcheck source=/dev/null +. "$ROOT/bin/fm-busy-lib.sh" + +TMP_ROOT=$(fm_test_tmproot fm-busy-state) +EV="$ROOT/bin/fm-busy-event.sh" + +new_state_dir() { # <name> + local d="$TMP_ROOT/$1/state" + mkdir -p "$d" + printf '%s' "$d" +} + +# --- writer: arm and apply --------------------------------------------------- + +test_arm_seeds_busy_spawn() { + local state gen out + state=$(new_state_dir arm-seed) + gen=$("$EV" arm "$state" t1) || fail "arm failed" + [ -f "$state/t1.busy-gen" ] || fail "arm did not write the gen sidecar" + [ "$(cat "$state/t1.busy-gen")" = "$gen" ] || fail "sidecar gen does not match printed gen" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "busy fm-spawn" ] || fail "seed should classify 'busy fm-spawn', got '$out'" + pass "arm mints a gen sidecar and seeds busy fm-spawn at seq=1" +} + +test_apply_advances_seq_and_source() { + local state gen out seq + state=$(new_state_dir apply-seq) + gen=$("$EV" arm "$state" t1) + "$EV" apply "$state" t1 idle --gen "$gen" --source claude-hook --event stop \ + || fail "apply idle failed" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "idle claude-hook" ] || fail "expected 'idle claude-hook', got '$out'" + "$EV" apply "$state" t1 busy --gen "$gen" --source claude-hook --event user-prompt-submit \ + || fail "apply busy failed" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "busy claude-hook" ] || fail "expected 'busy claude-hook', got '$out'" + seq=$(fm_busy_record_read "$state" t1 | awk '{print $4}') + [ "$seq" = 3 ] || fail "expected seq 3 after seed + two applies, got '$seq'" + pass "apply advances seq under the armed gen and attributes the writing source" +} + +test_apply_current_gen_reset() { + local state out + state=$(new_state_dir apply-current) + "$EV" arm "$state" t1 >/dev/null + "$EV" apply "$state" t1 idle --current-gen --source fm-interrupt --event interrupt \ + || fail "apply --current-gen failed" + out=$(fm_busy_classify tmux w1 pi t1 "$state") + [ "$out" = "idle fm-interrupt" ] || fail "expected 'idle fm-interrupt', got '$out'" + "$EV" apply "$state" t1 unknown --current-gen --source fm-recovery --event relaunch \ + || fail "apply unknown failed" + out=$(fm_busy_classify tmux w1 pi t1 "$state") + [ "$out" = "unknown fm-recovery" ] || fail "expected 'unknown fm-recovery', got '$out'" + pass "firstmate-owned interrupt and recovery events bind to the current gen" +} + +test_apply_unarmed_refused() { + local state + state=$(new_state_dir apply-unarmed) + if "$EV" apply "$state" t1 busy --gen g1.2.3 --source claude-hook --event x 2>/dev/null; then + fail "apply against an unarmed task must be refused" + fi + [ ! -f "$state/t1.busy-state" ] || fail "refused apply must not write a record" + pass "apply is refused for a task whose busy contract was never armed" +} + +test_retire_serializes_and_rejects_stale_gen() { + local state old_gen new_gen out retire_pid i=0 + state=$(new_state_dir retire) + old_gen=$("$EV" arm "$state" t1) + mkdir "$state/t1.busy-state.lock" + "$EV" retire "$state" t1 --gen "$old_gen" >/dev/null 2>&1 & + retire_pid=$! + while [ "$i" -lt 20 ] && ! kill -0 "$retire_pid" 2>/dev/null; do + i=$((i + 1)) + done + [ -e "$state/t1.busy-state" ] || fail "retire bypassed the writer lock" + rmdir "$state/t1.busy-state.lock" + wait "$retire_pid" || fail "retire failed after acquiring the writer lock" + [ ! -e "$state/t1.busy-state" ] || fail "retire left the record behind" + [ ! -e "$state/t1.busy-gen" ] || fail "retire left the gen sidecar behind" + + new_gen=$("$EV" arm "$state" t1) + if "$EV" retire "$state" t1 --gen "$old_gen" 2>/dev/null; then + fail "retire accepted a superseded incarnation" + fi + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "busy fm-spawn" ] || fail "stale retirement changed the new incarnation, got '$out'" + [ "$(cat "$state/t1.busy-gen")" = "$new_gen" ] || fail "stale retirement changed the new gen" + pass "retire waits for the writer lock and cannot remove a new incarnation" +} + +test_retire_missing_sidecar_is_idempotent() { + local state gen + state=$(new_state_dir retire-missing) + gen=$("$EV" arm "$state" t1) + rm -f "$state/t1.busy-gen" + + "$EV" retire "$state" t1 --gen "$gen" || fail "exact-gen retire rejected a missing sidecar" + [ ! -e "$state/t1.busy-state" ] || fail "retire left an orphan record behind" + "$EV" retire "$state" t1 --gen "$gen" || fail "repeated exact-gen retire was not idempotent" + "$EV" retire "$state" t1 --current-gen || fail "current-gen retire was not idempotent" + + printf 'malformed gen\n' > "$state/t1.busy-gen" + printf 'orphan\n' > "$state/t1.busy-state" + if "$EV" retire "$state" t1 --gen "$gen" 2>/dev/null; then + fail "retire accepted a malformed existing sidecar" + fi + [ -e "$state/t1.busy-state" ] || fail "retire removed the record for a malformed existing sidecar" + pass "retire treats only an absent sidecar as already retired" +} + +# --- stale event rejection ---------------------------------------------------- + +test_stale_gen_event_rejected() { + local state old_gen new_gen out + state=$(new_state_dir stale-event) + old_gen=$("$EV" arm "$state" t1) + new_gen=$("$EV" arm "$state" t1) + [ "$old_gen" != "$new_gen" ] || fail "re-arm must mint a fresh gen" + if "$EV" apply "$state" t1 idle --gen "$old_gen" --source claude-hook --event stop 2>/dev/null; then + fail "an event carrying a stale gen must be rejected" + fi + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "busy fm-spawn" ] || fail "stale event must not change the record, got '$out'" + pass "a late event from a previous incarnation is rejected, record unchanged" +} + +test_stale_gen_record_unknown() { + local state gen out + state=$(new_state_dir stale-record) + gen=$("$EV" arm "$state" t1) + # Simulate a record left behind by a superseded incarnation. + printf 'g-superseded.1.1\n' > "$state/t1.busy-gen.new" + mv "$state/t1.busy-gen.new" "$state/t1.busy-gen" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown gen-mismatch" ] || fail "stale record must classify 'unknown gen-mismatch', got '$out'" + pass "a record from a stale incarnation classifies unknown, never idle" +} + +# --- missing and malformed semantic data -------------------------------------- + +test_missing_record_unknown_not_idle() { + local state out h + state=$(new_state_dir missing) + for h in claude opencode pi pi-signed; do + out=$(fm_busy_classify tmux w1 "$h" t1 "$state") + [ "$out" = "unknown missing" ] || fail "$h with no record must be 'unknown missing', got '$out'" + done + out=$(fm_busy_classify tmux w1 codex t1 "$state") + [ "$out" = "unknown codex-unverified" ] || fail "codex with no verified source must be 'unknown codex-unverified', got '$out'" + pass "a converted adapter with no record classifies unknown, never idle" +} + +test_malformed_record_unknown() { + local state gen out + state=$(new_state_dir malformed) + gen=$("$EV" arm "$state" t1) + for bad in \ + 'garbage' \ + "v0 gen=$gen seq=1 state=busy source=claude-hook event=x ts=1" \ + "v1 gen=$gen seq=NaN state=busy source=claude-hook event=x ts=1" \ + "v1 gen=$gen seq=1 state=frobbing source=claude-hook event=x ts=1" \ + "v1 gen=$gen seq=1 state=busy source=bad source event=x ts=1" \ + "v1 gen=$gen seq=1 state=busy source=claude-hook event=x ts=1 rogue=1"; do + printf '%s\n' "$bad" > "$state/t1.busy-state" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown malformed" ] || fail "malformed record '$bad' must be 'unknown malformed', got '$out'" + done + printf 'v1 gen=%s seq=1 state=busy source=claude-hook event=x ts=1\nsecond line\n' "$gen" > "$state/t1.busy-state" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown malformed" ] || fail "multi-line record must be 'unknown malformed', got '$out'" + pass "malformed records classify unknown malformed, never busy or idle" +} + +test_record_without_sidecar_unknown() { + local state out + state=$(new_state_dir orphan-record) + printf 'v1 gen=g1.1.1 seq=1 state=busy source=claude-hook event=x ts=1\n' > "$state/t1.busy-state" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown malformed" ] || fail "record without an armed gen must be unknown, got '$out'" + pass "a record with no armed gen sidecar classifies unknown" +} + +# --- adapter isolation --------------------------------------------------------- + +test_source_mismatch_cross_adapter() { + local state gen out + state=$(new_state_dir cross-adapter) + gen=$("$EV" arm "$state" t1) + "$EV" apply "$state" t1 busy --gen "$gen" --source pi-ext --event agent-start + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown source-mismatch" ] || fail "pi-ext record on a claude task must be untrusted, got '$out'" + out=$(fm_busy_classify tmux w1 pi t1 "$state") + [ "$out" = "busy pi-ext" ] || fail "pi-ext record on a pi task must classify, got '$out'" + out=$(fm_busy_classify tmux w1 grok t1 "$state") + [ "$out" = "unknown source-mismatch" ] || fail "grok trusts no semantic source, got '$out'" + pass "a record is trusted only by the adapter whose source wrote it" +} + +test_converted_adapters_ignore_footer_text() { + local state out h + state=$(new_state_dir no-footer) + local tail='• Working (6s • esc to interrupt) + ■■■■⬝⬝⬝⬝ esc interrupt +Working... +Ctrl+c:cancel' + for h in claude opencode pi pi-signed; do + out=$(fm_busy_classify tmux w1 "$h" t1 "$state" "$tail") + [ "$out" = "unknown missing" ] || fail "$h must never classify from footer text, got '$out'" + done + out=$(fm_busy_classify tmux w1 codex t1 "$state" "$tail") + [ "$out" = "unknown codex-unverified" ] || fail "codex must never classify from footer text, got '$out'" + pass "converted adapters never classify busy from rendered footer text" +} + +test_grok_regex_isolated() { + local state out + state=$(new_state_dir grok-arm) + out=$(fm_busy_classify tmux w1 grok t1 "$state" 'thinking hard +Ctrl+c:cancel') + [ "$out" = "busy grok-regex" ] || fail "grok busy tail must classify 'busy grok-regex', got '$out'" + out=$(fm_busy_classify tmux w1 grok t1 "$state" 'done. +> ') + [ "$out" = "idle grok-regex" ] || fail "grok idle tail must classify 'idle grok-regex', got '$out'" + # Another adapter's footer never makes grok busy either. + out=$(fm_busy_classify tmux w1 grok t1 "$state" '• Working (6s • esc to interrupt)') + [ "$out" = "idle grok-regex" ] || fail "a claude footer must not classify grok busy, got '$out'" + pass "the grok fallback is regex-scoped to grok and classifies only grok tasks" +} + +# --- kimi verification gate ----------------------------------------------------- + +test_codex_unverified_gate() { + local state gen out + state=$(new_state_dir codex-gate) + gen=$("$EV" arm "$state" t1) + "$EV" apply "$state" t1 busy --gen "$gen" --source codex-hook --event user-prompt-submit + out=$(fm_busy_classify tmux w1 codex t1 "$state") + [ "$out" = "unknown codex-unverified" ] || fail "unverified codex must classify unknown, got '$out'" + [ -z "$(fm_busy_sources_for_harness codex)" ] \ + || fail "codex must trust no semantic source until one is verified" + pass "codex classifies unknown until a semantic source passes its verification gate" +} + +test_kimi_unverified_gate() { + local state gen out + state=$(new_state_dir kimi-gate) + gen=$("$EV" arm "$state" t1) + "$EV" apply "$state" t1 busy --gen "$gen" --source kimi-hook --event user-prompt-submit + out=$(fm_busy_classify tmux w1 kimi t1 "$state") + [ "$out" = "unknown kimi-unverified" ] || fail "unverified kimi must classify unknown, got '$out'" + out=$(fm_busy_classify tmux w1 kimi t1 "$state" '🌒 · thinking') + [ "$out" = "unknown kimi-unverified" ] || fail "kimi must not classify from footer text, got '$out'" + pass "standalone kimi classifies unknown until the live verification gate opens" +} + +# --- endpoint death and native fallbacks ---------------------------------------- + +test_dead_endpoint_overrides() { + local state gen out + state=$(new_state_dir dead) + gen=$("$EV" arm "$state" t1) + # shellcheck disable=SC2329 # invoked indirectly through fm_busy_classify_live + fm_backend_target_exists() { return 1; } + out=$(fm_busy_classify_live tmux w1 claude t1 "$state") + [ "$out" = "dead endpoint-gone" ] || fail "gone endpoint must classify dead, got '$out'" + # shellcheck disable=SC2329 # invoked indirectly through fm_busy_classify_live + fm_backend_target_exists() { return 0; } + out=$(fm_busy_classify_live tmux w1 claude t1 "$state") + [ "$out" = "busy fm-spawn" ] || fail "live endpoint must fall through to the record, got '$out'" + out=$(fm_busy_classify_live tmux '' claude t1 "$state") + [ "$out" = "unknown no-target" ] || fail "empty target must classify unknown, got '$out'" + unset -f fm_backend_target_exists + pass "endpoint death is the only process-level override and yields dead, never busy" +} + +test_herdr_native_busy_only() { + local state out + state=$(new_state_dir herdr-native) + # shellcheck disable=SC2329 # invoked indirectly through fm_busy_classify + fm_backend_busy_state() { printf '%s' "$FAKE_NATIVE"; } + FAKE_NATIVE=busy + out=$(fm_busy_classify herdr s:p claude t1 "$state") + [ "$out" = "busy herdr-native" ] || fail "native busy with no record must classify busy, got '$out'" + FAKE_NATIVE=idle + out=$(fm_busy_classify herdr s:p claude t1 "$state") + [ "$out" = "unknown missing" ] || fail "native idle must NOT classify idle, got '$out'" + # A valid record outranks the native verdict. + local gen + gen=$("$EV" arm "$state" t1) + "$EV" apply "$state" t1 idle --gen "$gen" --source claude-hook --event stop + FAKE_NATIVE=busy + out=$(fm_busy_classify herdr s:p claude t1 "$state") + [ "$out" = "idle claude-hook" ] || fail "the adapter record must outrank herdr's native verdict, got '$out'" + unset -f fm_backend_busy_state + pass "herdr's native verdict is trusted for busy only, and records outrank it" +} + +# The record parser runs inside sourcing callers (the watcher, the daemon, the +# crew-state reader), so it must not disturb their shell: no clobbered +# positional parameters and no changed glob setting. +test_record_read_leaves_caller_shell_intact() { + local state out + state=$(new_state_dir parser-isolation) + "$EV" arm "$state" t1 >/dev/null + out=$(bash -c ' + set -f + . "$1/bin/fm-busy-lib.sh" + set -- keepme second + fm_busy_record_read "$2" t1 >/dev/null + printf "%s|%s|%s" "$1" "$#" "$-" + ' _ "$ROOT" "$state") + case "$out" in + keepme\|2\|*f*) : ;; + *) fail "record parsing disturbed the caller's shell: $out" ;; + esac + # A glob-shaped field must survive parsing literally rather than expanding. + printf 'v1 gen=%s seq=1 state=busy source=* event=x ts=1\n' "$(cat "$state/t1.busy-gen")" \ + > "$state/t1.busy-state" + out=$(fm_busy_classify tmux w1 claude t1 "$state") + [ "$out" = "unknown malformed" ] || fail "a glob-shaped source must be rejected, not expanded, got '$out'" + pass "record parsing never clobbers the caller's positional parameters, glob setting, or fields" +} + +test_boolean_view_never_promotes_unknown() { + local state gen + state=$(new_state_dir boolean) + gen=$("$EV" arm "$state" t1) + fm_busy_is_busy tmux w1 claude t1 "$state" || fail "busy record must read busy" + "$EV" apply "$state" t1 idle --gen "$gen" --source claude-hook --event stop + if fm_busy_is_busy tmux w1 claude t1 "$state"; then + fail "idle record must not read busy" + fi + printf 'garbage\n' > "$state/t1.busy-state" + if fm_busy_is_busy tmux w1 claude t1 "$state"; then + fail "malformed record must not read busy" + fi + pass "the boolean view reports busy only on an exact busy verdict" +} + +test_arm_seeds_busy_spawn +test_apply_advances_seq_and_source +test_apply_current_gen_reset +test_apply_unarmed_refused +test_retire_serializes_and_rejects_stale_gen +test_retire_missing_sidecar_is_idempotent +test_stale_gen_event_rejected +test_stale_gen_record_unknown +test_missing_record_unknown_not_idle +test_malformed_record_unknown +test_record_without_sidecar_unknown +test_source_mismatch_cross_adapter +test_converted_adapters_ignore_footer_text +test_grok_regex_isolated +test_codex_unverified_gate +test_kimi_unverified_gate +test_dead_endpoint_overrides +test_herdr_native_busy_only +test_record_read_leaves_caller_shell_intact +test_boolean_view_never_promotes_unknown + +echo "all fm-busy-state tests passed" diff --git a/tests/fm-calm-pi-extension.test.sh b/tests/fm-calm-pi-extension.test.sh index a8e09be1456..f1109e787ec 100755 --- a/tests/fm-calm-pi-extension.test.sh +++ b/tests/fm-calm-pi-extension.test.sh @@ -10,6 +10,7 @@ EXT="$ROOT/.pi/extensions/fm-calm.ts" ASSISTANT_LAYOUT="$ROOT/.pi/extensions/lib/fm-calm-assistant-layout.ts" OPERATIONAL_USER_LAYOUT="$ROOT/.pi/extensions/lib/fm-calm-operational-user-layout.ts" VISIBILITY="$ROOT/.pi/extensions/lib/fm-calm-visibility.ts" +WORKING_SHIP="$ROOT/.pi/extensions/lib/fm-calm-working-ship.ts" WATCH_EXT="$ROOT/.pi/extensions/fm-primary-pi-watch.ts" OPERATIONAL_INPUT="$ROOT/bin/fm-operational-input.sh" PI_OPERATIONAL_INPUT="$ROOT/.pi/extensions/lib/fm-operational-input.ts" @@ -38,7 +39,10 @@ trap cleanup EXIT wait_for_text() { local file=$1 text=$2 i=0 while [ "$i" -lt 120 ]; do - tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" -S - >"$file" 2>/dev/null || true + # Include recent scrollback: expanding a long restored transcript can move + # the asserted tool output above the current viewport while the footer and + # editor remain visible. + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" -S -600 >"$file" 2>/dev/null || true grep -Fq "$text" "$file" 2>/dev/null && return 0 sleep 0.05 i=$((i + 1)) @@ -90,6 +94,7 @@ test_home_resolution() { cp "$ASSISTANT_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$fixture/project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$fixture/project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$PI_OPERATIONAL_INPUT" "$fixture/project/.pi/extensions/lib/fm-operational-input.ts" ln -s "$PI_PACKAGE_DIR" "$fixture/project/node_modules/@earendil-works/pi-coding-agent" ln -s "$PI_PACKAGE_DIR/node_modules/@earendil-works/pi-tui" "$fixture/project/node_modules/@earendil-works/pi-tui" @@ -207,6 +212,7 @@ test_pi_compat_degraded_adapter() { cp "$ASSISTANT_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$fixture/project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$fixture/project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$PI_OPERATIONAL_INPUT" "$fixture/project/.pi/extensions/lib/fm-operational-input.ts" ln -s "$PI_PACKAGE_DIR" "$fixture/project/node_modules/@earendil-works/pi-coding-agent" ln -s "$PI_PACKAGE_DIR/node_modules/@earendil-works/pi-tui" "$fixture/project/node_modules/@earendil-works/pi-tui" @@ -305,6 +311,7 @@ test_pi_compat_missing_adapter_exports() { cp "$ASSISTANT_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$fixture/project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$fixture/project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$fixture/project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$PI_OPERATIONAL_INPUT" "$fixture/project/.pi/extensions/lib/fm-operational-input.ts" printf '%s\n' '{"type":"module"}' >"$fixture/project/package.json" printf '%s\n' \ @@ -362,6 +369,7 @@ test_rendering_and_session_lifecycle() { cp "$ASSISTANT_LAYOUT" "$fixture/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$fixture/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$fixture/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$fixture/lib/fm-calm-working-ship.ts" cp "$ROOT/.pi/extensions/lib/fm-operational-input.ts" "$fixture/lib/fm-operational-input.ts" cp "$WATCH_EXT" "$fixture/fm-primary-pi-watch.ts" ln -s "$PI_PACKAGE_DIR" "$fixture/node_modules/@earendil-works/pi-coding-agent" @@ -995,7 +1003,7 @@ JS status=$? [ "$status" -eq 0 ] || fail "Pi calm renderer and lifecycle contract failed: $out" [ -z "$out" ] || fail "Pi calm renderer test printed output: $out" - pass "Pi calm centralizes transcript visibility, preserves execution/export data, keeps native working visible, and persists its choice across session starts" + pass "Pi calm centralizes transcript visibility, preserves execution/export data, keeps Pi's stock working row visible while no run is active, and persists its choice across session starts" } test_operational_followup_turn_e2e() { @@ -1017,6 +1025,7 @@ test_operational_followup_turn_e2e() { cp "$ASSISTANT_LAYOUT" "$project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$PI_OPERATIONAL_INPUT" "$project/.pi/extensions/lib/fm-operational-input.ts" printf '%s\n' '{"followUpMode":"all"}' >"$config/settings.json" @@ -1379,6 +1388,7 @@ test_hidden_block_geometry_e2e() { cp "$ASSISTANT_LAYOUT" "$project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$PI_OPERATIONAL_INPUT" "$project/.pi/extensions/lib/fm-operational-input.ts" printf '%s\n' on >"$home/config/calm" printf '%s\n' '{"hideThinkingBlock":true,"terminal":{"clearOnShrink":false}}' >"$config/settings.json" @@ -1591,8 +1601,871 @@ TS pass "Pi Calm native /skill:ahoy geometry keeps every collapsed thinking and tool block at zero height while preserving expansion, history, restart, and Calm-off rendering" } +test_working_ship_geometry_and_lifecycle() { + local fixture out status version + if ! command -v node >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1; then + echo "skip: node or npm not found for Pi Calm working-ship test" + return 0 + fi + if [ ! -f "$PI_PACKAGE_DIR/package.json" ]; then + echo "skip: installed @earendil-works/pi-coding-agent package not found" + return 0 + fi + version=$(node -p "require('$PI_PACKAGE_DIR/package.json').version") + record_pi_version_evidence "$version" "Pi Calm working-ship assumptions" + + fixture="$TMP_ROOT/working-ship" + mkdir -p "$fixture/home" "$fixture/lib" "$fixture/node_modules/@earendil-works" + cp "$EXT" "$fixture/fm-calm.ts" + cp "$ASSISTANT_LAYOUT" "$fixture/lib/fm-calm-assistant-layout.ts" + cp "$OPERATIONAL_USER_LAYOUT" "$fixture/lib/fm-calm-operational-user-layout.ts" + cp "$VISIBILITY" "$fixture/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$fixture/lib/fm-calm-working-ship.ts" + cp "$PI_OPERATIONAL_INPUT" "$fixture/lib/fm-operational-input.ts" + ln -s "$PI_PACKAGE_DIR" "$fixture/node_modules/@earendil-works/pi-coding-agent" + ln -s "$PI_PACKAGE_DIR/node_modules/@earendil-works/pi-tui" "$fixture/node_modules/@earendil-works/pi-tui" + ln -s "$PI_PACKAGE_DIR/node_modules/typebox" "$fixture/node_modules/typebox" + printf '%s\n' '{"type":"module"}' >"$fixture/package.json" + + out=$(cd "$fixture" && EXT="$fixture/fm-calm.ts" FM_HOME="$fixture/home" PI_PACKAGE_DIR="$PI_PACKAGE_DIR" node --input-type=module 2>&1 <<'JS' +import { pathToFileURL } from "node:url"; + +const packageRoot = process.env.PI_PACKAGE_DIR; +const [{ initTheme, theme }, { visibleWidth, setCapabilities }] = await Promise.all([ + import(pathToFileURL(`${packageRoot}/dist/modes/interactive/theme/theme.js`).href), + import(pathToFileURL(`${packageRoot}/node_modules/@earendil-works/pi-tui/dist/index.js`).href), +]); +initTheme("dark"); +setCapabilities({ images: null, trueColor: true, hyperlinks: false }); + +const ship = await import( + `${pathToFileURL(`${process.cwd()}/lib/fm-calm-working-ship.ts`).href}?ship=${Date.now()}` +); +const { + CALM_WORKING_SHIP_WIDGET_KEY, + CALM_WORKING_SHIP_TICK_MS, + CALM_WORKING_SHIP_TICKS_PER_MOVE, + createCalmWorkingShipAnimation, + createCalmWorkingShipWidget, +} = ship; + +const ESC = "\u001b"; +const BLUE = `${ESC}[34m`; +const YELLOW = `${ESC}[33m`; +const RESET = `${ESC}[39m`; +const strip = (text) => text.replace(new RegExp(`${ESC}\\[[0-9;]*m`, "g"), ""); +const check = (condition, message) => { + if (!condition) throw new Error(message); +}; +const sailOf = (frame) => { + const row = strip(frame[0]); + if (row.includes("<|")) return "<|"; + if (row.includes("|>")) return "|>"; + return "none"; +}; + +// --- Calm cadence: the boat is materially slower than the water ------------------ +{ + // The pre-revision boat moved one column every 140ms. The revised boat must be + // plainly slower in real use while the water keeps rippling between its steps. + const msPerColumn = CALM_WORKING_SHIP_TICK_MS * CALM_WORKING_SHIP_TICKS_PER_MOVE; + check(msPerColumn >= 700, `boat cadence ${msPerColumn}ms per column is not materially slower`); + check( + CALM_WORKING_SHIP_TICKS_PER_MOVE >= 2, + "the water cadence is not independent of and faster than the boat cadence", + ); + check( + CALM_WORKING_SHIP_TICK_MS < msPerColumn, + "the water does not animate faster than the boat moves", + ); +} + +// --- Water phases loop independently while the boat stays put -------------------- +{ + const width = 40; + const animation = createCalmWorkingShipAnimation(); + animation.render(width); + const startPosition = animation.position(); + const waterRows = new Set(); + const phases = new Set(); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE - 1; step += 1) { + animation.tick(); + check( + animation.position() === startPosition, + `the boat moved on tick ${step + 1} instead of waiting for its own cadence`, + ); + waterRows.add(strip(animation.render(width)[1])); + phases.add(animation.waterPhase()); + } + check(waterRows.size > 1, "the water did not animate while the boat was stationary"); + check(phases.size > 1, "the water phase did not advance between boat movements"); + // The boat then moves on its own cadence tick. + animation.tick(); + check( + animation.position() !== startPosition, + "the boat never moved on its own cadence tick", + ); + // Water motion alone must not change the hull column. + const beforeHull = strip(animation.render(width)[1]).indexOf("\\__/"); + animation.tick(); + const afterHull = strip(animation.render(width)[1]).indexOf("\\__/"); + check(beforeHull === afterHull, "advancing only the water appeared to move the boat"); +} + +// --- Water phases are bounded, fixed-cell, and never change geometry ------------- +{ + const width = 30; + const animation = createCalmWorkingShipAnimation(); + const seenPhases = new Set(); + for (let step = 0; step < 64; step += 1) { + const frame = animation.render(width); + seenPhases.add(animation.waterPhase()); + check(frame.length === 2, `water phase ${animation.waterPhase()} changed the row count`); + check( + visibleWidth(frame[1]) === width, + `water phase ${animation.waterPhase()} changed the visible width`, + ); + animation.tick(); + } + check(seenPhases.size > 1 && seenPhases.size <= 8, `water phase set is not bounded: ${seenPhases.size}`); +} + +// --- Standard ANSI colors, with resets that prevent bleed ------------------------ +{ + const width = 24; + const animation = createCalmWorkingShipAnimation(); + for (let step = 0; step < 12; step += 1) { + const [sailRow, waterRow] = animation.render(width); + + // Standard codes only: no bright variants, no 256-color, no RGB. + for (const row of [sailRow, waterRow]) { + const codes = row.match(new RegExp(`${ESC}\\[[0-9;]*m`, "g")) ?? []; + for (const code of codes) { + check( + code === BLUE || code === YELLOW || code === RESET, + `non-standard ANSI escape ${JSON.stringify(code)} in ${JSON.stringify(row)}`, + ); + } + check(codes.length > 0, "a rendered row carried no color at all"); + // Every colored run is closed, so nothing bleeds into padding or later frames. + check( + codes.filter((c) => c !== RESET).length === codes.filter((c) => c === RESET).length, + `unbalanced color/reset pairs in ${JSON.stringify(row)}`, + ); + check(codes[codes.length - 1] === RESET, `row does not end color-reset: ${JSON.stringify(row)}`); + } + + // Sail-row padding must be plain spaces outside any color run. + const leading = sailRow.slice(0, sailRow.indexOf(ESC)); + check(/^ *$/.test(leading), `sail row padding was colored: ${JSON.stringify(leading)}`); + + // The complete boat is yellow; every water cell is blue. + for (const piece of [`${YELLOW}<|${RESET}`, `${YELLOW}|>${RESET}`]) { + if (sailRow.includes(piece.slice(0, -RESET.length))) { + check(sailRow.includes(piece), `sail was not a closed yellow run: ${JSON.stringify(sailRow)}`); + } + } + check( + waterRow.includes(`${YELLOW}\\__/${RESET}`), + `hull was not a closed yellow run: ${JSON.stringify(waterRow)}`, + ); + for (const run of waterRow.split(YELLOW)) { + const blueRuns = run.split(BLUE).slice(1); + for (const blueRun of blueRuns) { + const cells = blueRun.slice(0, blueRun.indexOf(RESET)); + check(cells.length > 0, "an empty blue run emitted a bare color escape"); + check( + /^[~-]+$/.test(cells), + `blue run contained a non-water cell: ${JSON.stringify(cells)}`, + ); + } + } + animation.tick(); + } +} + +// --- ANSI-stripped visible width is exact at every width and phase --------------- +for (let width = 1; width <= 120; width += 1) { + const animation = createCalmWorkingShipAnimation(); + animation.render(width); + for (let step = 0; step <= width + 8; step += 1) { + const frame = animation.render(width); + const expectedRows = width >= 4 ? 2 : 1; + check(frame.length === expectedRows, `width ${width} rendered ${frame.length} rows`); + for (const line of frame) { + check( + visibleWidth(line) <= width, + `width ${width} rendered a ${visibleWidth(line)}-cell line and would wrap`, + ); + check( + visibleWidth(line) === strip(line).length, + `width ${width} let ANSI bytes affect the measured geometry`, + ); + } + // The water row always fills the complete usable width. + const waterRow = frame[frame.length - 1]; + check( + visibleWidth(waterRow) === width, + `width ${width} water row was ${visibleWidth(waterRow)} cells instead of full width`, + ); + animation.tick(); + } +} + +// --- Directional sail and exact bounce, including tiny spans --------------------- +for (const width of [40, 16, 8, 6, 5, 4, 3, 2]) { + const animation = createCalmWorkingShipAnimation(); + animation.render(width); + const span = width >= 4 ? width - 4 : Math.max(0, width - 2); + const frames = []; + for (let step = 0; step < span * CALM_WORKING_SHIP_TICKS_PER_MOVE * 3 + 16; step += 1) { + const frame = animation.render(width); + frames.push({ position: animation.position(), sail: sailOf(frame) }); + animation.tick(); + } + for (const frame of frames) { + check( + frame.position >= 0 && frame.position <= span, + `width ${width} left the track at column ${frame.position}`, + ); + } + if (width >= 2) { + // Every frame must already show the heading it is about to travel, so no frame + // at or after a reversal shows the old sail. + for (let index = 1; index < frames.length; index += 1) { + const previous = frames[index - 1]; + const current = frames[index]; + if (current.position > previous.position) { + check( + previous.sail === "<|", + `width ${width} moved right showing ${previous.sail} at column ${previous.position}`, + ); + } + if (current.position < previous.position) { + check( + previous.sail === "|>", + `width ${width} moved left showing ${previous.sail} at column ${previous.position}`, + ); + } + } + } + if (span > 0) { + const sails = new Set(frames.map((frame) => frame.sail)); + check(sails.has("<|") && sails.has("|>"), `width ${width} never showed both headings`); + const positions = frames.map((frame) => frame.position); + check(Math.min(...positions) === 0, `width ${width} never reached the left edge`); + check(Math.max(...positions) === span, `width ${width} never reached the right edge`); + // Both reversals must be covered. + let rightToLeft = false; + let leftToRight = false; + for (let index = 1; index < frames.length; index += 1) { + if (frames[index - 1].sail === "<|" && frames[index].sail === "|>") rightToLeft = true; + if (frames[index - 1].sail === "|>" && frames[index].sail === "<|") leftToRight = true; + } + check(rightToLeft, `width ${width} never reversed from right to left`); + check(leftToRight, `width ${width} never reversed from left to right`); + } +} + +// --- Shrink and grow resize clamping ---------------------------------------------- +{ + const animation = createCalmWorkingShipAnimation(); + animation.render(80); + while (animation.position() < 76) animation.tick(); + check(animation.position() === 76, `boat did not reach the wide right edge: ${animation.position()}`); + + const shrunk = animation.render(20); + check(animation.position() === 16, `shrink did not clamp the track immediately: ${animation.position()}`); + check(visibleWidth(shrunk[1]) === 20, `shrunk water row was ${visibleWidth(shrunk[1])} cells instead of 20`); + check(visibleWidth(shrunk[0]) <= 20, "shrunk sail row would wrap"); + check(sailOf(shrunk) === "|>", "the boat did not turn around after being clamped to the right edge"); + + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) animation.tick(); + const afterShrink = animation.render(20); + check(animation.position() < 16, "the boat stalled at the edge after a shrink"); + check(visibleWidth(afterShrink[1]) === 20, "motion after a shrink broke the water row width"); + + const grown = animation.render(60); + check(visibleWidth(grown[1]) === 60, `grown water row was ${visibleWidth(grown[1])} cells`); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) animation.tick(); + const afterGrow = animation.render(60); + check( + animation.position() >= 0 && animation.position() <= 56, + `motion left the grown track: ${animation.position()}`, + ); + check(visibleWidth(afterGrow[1]) === 60, "motion after a grow broke the water row width"); +} + +// --- Deterministic narrow fallbacks ------------------------------------------------ +{ + const animation = createCalmWorkingShipAnimation(); + check(JSON.stringify(animation.render(0)) === "[]", "zero width rendered a line"); + for (const width of [1, 2, 3]) { + const fallback = createCalmWorkingShipAnimation(); + for (let step = 0; step < 12; step += 1) { + const frame = fallback.render(width); + check(frame.length === 1, `width ${width} fallback was not a single row`); + check(visibleWidth(frame[0]) === width, `width ${width} fallback was not exactly ${width} cells`); + const bare = strip(frame[0]); + if (width === 1) { + check(/^[~-]$/.test(bare), `width 1 fallback was not a single water cell: ${bare}`); + } else { + check( + bare.includes("<|") || bare.includes("|>"), + `width ${width} fallback lost the sail: ${bare}`, + ); + } + fallback.tick(); + } + } +} + +// --- Freeze/resume continuity on one shared animation instance --------------------- +// Hiding the working presentation must freeze column and direction. The next widget +// bound to the same animation resumes exactly there; hidden wall time must not jump. +{ + const animation = createCalmWorkingShipAnimation(); + const tui = { requestRender() {} }; + animation.render(40); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE * 7; step += 1) animation.tick(); + animation.render(40); + const frozenColumn = animation.position(); + const frozenDirection = animation.direction(); + const frozenPhase = animation.waterPhase(); + check(frozenColumn > 0, `continuity setup never left the left edge: ${frozenColumn}`); + + const first = createCalmWorkingShipWidget(tui, animation); + check(first.render(40) && animation.position() === frozenColumn, "binding a widget moved the frozen boat"); + first.dispose(); + // Dispose freezes; further wall time without ticks must not change logical state. + check(animation.position() === frozenColumn, "dispose changed the frozen column"); + check(animation.direction() === frozenDirection, "dispose changed the frozen direction"); + check(animation.waterPhase() === frozenPhase, "dispose changed the frozen water phase"); + + const resumed = createCalmWorkingShipWidget(tui, animation); + const firstFrame = resumed.render(40); + check( + animation.position() === frozenColumn && animation.direction() === frozenDirection, + `resume first frame left frozen state: col=${animation.position()} dir=${animation.direction()}`, + ); + check(sailOf(firstFrame) === (frozenDirection >= 0 ? "<|" : "|>"), "resume first frame lost sail heading"); + check(animation.waterPhase() === frozenPhase, "resume advanced water phase without a tick"); + // After resume, motion continues from the frozen state rather than restarting. + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) animation.tick(); + check( + animation.position() === frozenColumn + frozenDirection, + `post-resume motion did not continue from frozen column: ${animation.position()}`, + ); + resumed.dispose(); + + // Hidden resize clamps without needing a live widget, and preserves a valid heading. + animation.render(80); + while (animation.position() < 76) animation.tick(); + animation.render(80); + check(animation.position() === 76 && animation.direction() === -1, "endpoint setup failed before hidden resize"); + const beforeHiddenResize = { column: animation.position(), direction: animation.direction(), phase: animation.waterPhase() }; + animation.clampToWidth(20); + check(animation.position() === 16, `hidden shrink did not clamp: ${animation.position()}`); + check(animation.direction() === -1, "hidden shrink lost the leftward heading at the right edge"); + check(animation.waterPhase() === beforeHiddenResize.phase, "hidden clamp advanced water phase"); + // Growing while hidden must not invent motion either. + animation.clampToWidth(60); + check(animation.position() === 16, `hidden grow moved the boat: ${animation.position()}`); + check(animation.direction() === -1, "hidden grow changed direction without cause"); + + // Endpoint and bounce continuity: pause immediately before, at, and after each edge. + for (const scenario of [ + { label: "before-right", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 7) anim.tick(); + check(anim.position() === 7 && anim.direction() === 1, "before-right setup"); + }}, + { label: "at-right", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 8) anim.tick(); + check(anim.position() === 8 && anim.direction() === -1, "at-right setup"); + }}, + { label: "after-right", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 8) anim.tick(); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) anim.tick(); + check(anim.position() === 7 && anim.direction() === -1, "after-right setup"); + }}, + { label: "before-left", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 8) anim.tick(); + while (!(anim.position() === 1 && anim.direction() === -1)) anim.tick(); + }}, + { label: "at-left", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 8) anim.tick(); + while (!(anim.position() === 0 && anim.direction() === 1)) anim.tick(); + }}, + { label: "after-left", setup(anim) { + anim.reset(); anim.render(12); + while (anim.position() < 8) anim.tick(); + while (!(anim.position() === 0 && anim.direction() === 1)) anim.tick(); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) anim.tick(); + check(anim.position() === 1 && anim.direction() === 1, "after-left setup"); + }}, + ]) { + const edge = createCalmWorkingShipAnimation(); + scenario.setup(edge); + edge.render(12); + const frozen = { column: edge.position(), direction: edge.direction(), phase: edge.waterPhase() }; + const paused = createCalmWorkingShipWidget(tui, edge); + paused.dispose(); + const again = createCalmWorkingShipWidget(tui, edge); + again.render(12); + check( + edge.position() === frozen.column && edge.direction() === frozen.direction && edge.waterPhase() === frozen.phase, + `${scenario.label} resume changed frozen edge state`, + ); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) edge.tick(); + const expectedColumn = Math.min(8, Math.max(0, frozen.column + frozen.direction)); + let expectedDirection = frozen.direction; + if (expectedColumn >= 8) expectedDirection = -1; + else if (expectedColumn <= 0) expectedDirection = 1; + check( + edge.position() === expectedColumn && edge.direction() === expectedDirection, + `${scenario.label} post-resume bounce drifted: col=${edge.position()} dir=${edge.direction()}`, + ); + again.dispose(); + } + + // reset() returns a genuine fresh-session initial state. + animation.reset(); + check( + animation.position() === 0 && animation.direction() === 1 && animation.waterPhase() === 0, + "reset() did not restore the normal initial boat state", + ); + animation.render(40); + check(sailOf(animation.render(40)) === "<|", "reset() first frame was not the initial rightward sail"); + + // Two controller instances never share motion state. + const left = createCalmWorkingShipAnimation(); + const right = createCalmWorkingShipAnimation(); + left.render(40); + right.render(40); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE * 3; step += 1) left.tick(); + check(left.position() === 3 && right.position() === 0, "separate animations leaked motion state"); +} + +{ + const realSetInterval = globalThis.setInterval; + const realClearInterval = globalThis.clearInterval; + const callbacks = []; + const handles = new Set(); + globalThis.setInterval = (callback) => { + callbacks.push(callback); + const handle = { unref() {} }; + handles.add(handle); + return handle; + }; + globalThis.clearInterval = (handle) => { + handles.delete(handle); + }; + + try { + const tui = { renderRequests: 0, requestRender() { this.renderRequests += 1; } }; + const animation = createCalmWorkingShipAnimation(); + const first = createCalmWorkingShipWidget(tui, animation); + first.render(40); + callbacks[callbacks.length - 1](); + callbacks[callbacks.length - 1](); + check(tui.renderRequests === 2, "unpainted timer ticks did not request renders"); + first.dispose(); + check(handles.size === 0, "disposing the unpainted widget left its timer scheduled"); + check( + animation.position() === 0 && animation.direction() === 1 && animation.waterPhase() === 0, + "dispose retained state from unpainted timer ticks", + ); + + const resumed = createCalmWorkingShipWidget(tui, animation); + resumed.render(40); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) { + callbacks[callbacks.length - 1](); + } + resumed.render(40); + check(animation.position() === 1, "unpainted ticks leaked into the resumed cadence"); + check(animation.waterPhase() === 0, "resumed cadence did not restore the rendered water phase"); + resumed.dispose(); + + const committed = createCalmWorkingShipAnimation(); + const progressing = createCalmWorkingShipWidget(tui, committed); + progressing.render(40); + callbacks[callbacks.length - 1](); + progressing.render(40); + const renderedPhase = committed.waterPhase(); + callbacks[callbacks.length - 1](); + progressing.dispose(); + check(committed.position() === 0, "dispose changed the committed column after an unpainted tick"); + check(committed.waterPhase() === renderedPhase, "dispose changed the committed phase after an unpainted tick"); + + const committedResume = createCalmWorkingShipWidget(tui, committed); + committedResume.render(40); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE - 2; step += 1) { + callbacks[callbacks.length - 1](); + } + check(committed.position() === 0, "serviced render did not preserve the committed cadence"); + callbacks[callbacks.length - 1](); + committedResume.render(40); + check(committed.position() === 1, "serviced render did not commit progress for the next cadence"); + committedResume.dispose(); + + const boundaryCases = [ + [7, 1], [8, -1], [7, -1], [1, -1], [0, 1], [1, 1], + ]; + for (const [targetPosition, targetDirection] of boundaryCases) { + const edge = createCalmWorkingShipAnimation(); + edge.render(12); + let reached = false; + for (let step = 0; step < 160; step += 1) { + if (edge.position() === targetPosition && edge.direction() === targetDirection) { + edge.render(12); + reached = true; + break; + } + edge.tick(); + edge.render(12); + } + check(reached, `could not prepare bounce state ${targetPosition}/${targetDirection}`); + const before = { position: edge.position(), direction: edge.direction(), phase: edge.waterPhase() }; + const paused = createCalmWorkingShipWidget(tui, edge); + paused.render(12); + for (let step = 0; step < CALM_WORKING_SHIP_TICKS_PER_MOVE; step += 1) { + callbacks[callbacks.length - 1](); + } + paused.dispose(); + check( + edge.position() === before.position && + edge.direction() === before.direction && + edge.waterPhase() === before.phase, + `unpainted bounce tick escaped ${targetPosition}/${targetDirection}`, + ); + const resumedEdge = createCalmWorkingShipWidget(tui, edge); + resumedEdge.render(12); + check( + edge.position() === before.position && edge.direction() === before.direction, + `bounce state ${targetPosition}/${targetDirection} changed on resume`, + ); + resumedEdge.dispose(); + } + } finally { + globalThis.setInterval = realSetInterval; + globalThis.clearInterval = realClearInterval; + } +} + +// --- Lifecycle through the Calm extension's registered handlers -------------------- +let liveTimers = 0; +const realSetInterval = globalThis.setInterval; +const realClearInterval = globalThis.clearInterval; +globalThis.setInterval = (...args) => { + liveTimers += 1; + return realSetInterval(...args); +}; +globalThis.clearInterval = (timer) => { + if (timer !== undefined) liveTimers -= 1; + return realClearInterval(timer); +}; + +const sessionWrites = []; +const handlers = new Map(); +let calmCommand; +const pi = { + events: { emit() {}, on() {} }, + on(event, handler) { + const existing = handlers.get(event) ?? []; + existing.push(handler); + handlers.set(event, existing); + }, + registerCommand(name, command) { + if (name === "calm") calmCommand = command; + }, + registerEntryRenderer() {}, + registerTool() {}, + appendEntry: (...args) => sessionWrites.push(["appendEntry", ...args]), + sendMessage: (...args) => sessionWrites.push(["sendMessage", ...args]), + sendUserMessage: (...args) => sessionWrites.push(["sendUserMessage", ...args]), + setSessionName: (...args) => sessionWrites.push(["setSessionName", ...args]), +}; +const extension = await import(`${pathToFileURL(process.env.EXT).href}?ship=${Date.now()}`); +extension.default(pi); +check(!!calmCommand, "Calm command was not registered"); +for (const event of ["session_start", "agent_start", "agent_settled", "session_shutdown"]) { + check(handlers.has(event), `Calm did not register a ${event} handler`); +} + +let renderRequests = 0; +const tui = { requestRender: () => { renderRequests += 1; } }; +const ui = { + workingVisible: [], + visibilityCalls: 0, + widgetOps: [], + widgets: new Map(), + setWorkingVisible(visible) { + this.visibilityCalls += 1; + this.workingVisible.push(visible); + }, + // Mirrors Pi's documented widget contract: the previous component under a key is + // disposed before a replacement is installed, and clearing disposes it too. + setWidget(key, content, options) { + const existing = this.widgets.get(key); + if (existing?.dispose) existing.dispose(); + this.widgets.delete(key); + this.widgetOps.push({ + key, + action: content === undefined ? "clear" : "set", + placement: options?.placement, + }); + if (content === undefined) return; + this.widgets.set(key, typeof content === "function" ? content(tui, theme) : content); + }, + getEditorText: () => "", + getToolsExpanded: () => false, + onTerminalInput: () => () => {}, + setHiddenThinkingLabel() {}, + setStatus() {}, + setToolsExpanded() {}, + theme, +}; +const ctx = { ui }; +const fire = async (event, payload = {}) => { + for (const handler of handlers.get(event) ?? []) await handler(payload, ctx); +}; +const reset = () => { + ui.workingVisible.length = 0; + ui.widgetOps.length = 0; + ui.visibilityCalls = 0; +}; +const shipWidget = () => ui.widgets.get(CALM_WORKING_SHIP_WIDGET_KEY); + +// --- Calm off leaves Pi's stock working behavior completely untouched ------------- +await fire("session_start", { reason: "startup" }); +reset(); +for (const event of ["agent_start", "agent_settled", "session_shutdown"]) { + await fire(event, { reason: "quit" }); +} +check( + ui.visibilityCalls === 0, + `Calm off called setWorkingVisible ${ui.visibilityCalls} times from the run lifecycle`, +); +check(ui.widgetOps.length === 0, `Calm off registered a working widget: ${JSON.stringify(ui.widgetOps)}`); +check(liveTimers === 0, `Calm off started ${liveTimers} animation timers`); + +// --- Turning Calm on while idle shows no boat until a run starts ------------------- +reset(); +await calmCommand.handler("", ctx); +check(ui.widgetOps.length === 0, "toggling Calm on while idle installed a working widget"); +check(liveTimers === 0, "toggling Calm on while idle started an animation timer"); + +// --- Calm on plus an active run shows the boat instead of the stock row ----------- +reset(); +await fire("agent_start"); +check( + ui.widgetOps.length === 1 && + ui.widgetOps[0].key === CALM_WORKING_SHIP_WIDGET_KEY && + ui.widgetOps[0].action === "set", + `Calm on did not install exactly one working widget: ${JSON.stringify(ui.widgetOps)}`, +); +check(ui.widgetOps[0].placement === undefined, "Calm working widget asked for a non-default placement"); +check( + ui.workingVisible[ui.workingVisible.length - 1] === false, + "Calm on did not hide Pi's stock working row", +); +check(liveTimers === 1, `Calm on kept ${liveTimers} animation timers instead of one`); + +const widget = shipWidget(); +check(!!widget, "Calm on did not install the working-ship widget"); +check(typeof widget.render === "function", "working widget has no render(width)"); +check(typeof widget.invalidate === "function", "working widget has no invalidate()"); +check(typeof widget.dispose === "function", "working widget has no dispose()"); +// A focusable widget could steal input or swallow Escape; this one takes no keys. +check(widget.handleInput === undefined, "working widget accepts keyboard input"); +check(widget.wantsKeyRelease === undefined, "working widget asked for key release events"); +check(widget.render(60).length === 2, "installed working widget did not render the two-row sprite"); +check( + widget.render(60).every((line) => visibleWidth(line) <= 60), + "installed working widget rendered a line wider than its viewport", +); + +// --- Repeated low-level starts inside one logical run never duplicate anything ----- +reset(); +for (let repeat = 0; repeat < 5; repeat += 1) await fire("agent_start"); +check(ui.widgetOps.length === 0, `repeated starts churned the working widget: ${JSON.stringify(ui.widgetOps)}`); +check(liveTimers === 1, `repeated starts left ${liveTimers} animation timers`); +check(ui.widgets.size === 1, `repeated starts left ${ui.widgets.size} widgets`); +check(shipWidget() === widget, "repeated starts replaced the running widget"); + +// --- The animation drives Pi's renderer ------------------------------------------- +{ + const before = renderRequests; + await new Promise((resolve) => setTimeout(resolve, CALM_WORKING_SHIP_TICK_MS * 3)); + check(renderRequests > before, "the working animation never requested a TUI render"); +} + +// --- Settling removes the boat, stops the animation, and restores the stock row ---- +// Drive the live widget far enough that a left-edge reset would be observable. +{ + const moving = shipWidget(); + check(!!moving, "continuity setup lost the live working widget"); + moving.render(40); + await new Promise((resolve) => setTimeout(resolve, CALM_WORKING_SHIP_TICK_MS * CALM_WORKING_SHIP_TICKS_PER_MOVE * 5 + 40)); + moving.render(40); +} +const hullColumn = (widget) => strip(widget.render(40)[1]).indexOf("\\__/"); +const freezeColumn = hullColumn(shipWidget()); +const freezeSail = sailOf(shipWidget().render(40)); +check(freezeColumn > 0, `lifecycle continuity setup never left the left edge: ${freezeColumn}`); + +reset(); +await fire("agent_settled"); +check( + ui.widgetOps.length === 1 && + ui.widgetOps[0].key === CALM_WORKING_SHIP_WIDGET_KEY && + ui.widgetOps[0].action === "clear", + `settling did not clear the working widget: ${JSON.stringify(ui.widgetOps)}`, +); +check(liveTimers === 0, `settling left ${liveTimers} animation timers`); +check(ui.widgets.size === 0, "settling left a residual widget"); +check( + ui.workingVisible[ui.workingVisible.length - 1] === true, + "settling did not restore Pi's stock working row", +); +{ + // No stale rows survive the removal: the widget renders nothing once disposed. + const renderRequestsAfterDispose = renderRequests; + await new Promise((resolve) => setTimeout(resolve, CALM_WORKING_SHIP_TICK_MS * CALM_WORKING_SHIP_TICKS_PER_MOVE * 3)); + check( + renderRequests === renderRequestsAfterDispose, + "the animation kept running after the widget was removed", + ); +} + +// --- Later working period resumes the frozen column and direction ----------------- +reset(); +await fire("agent_start"); +check(liveTimers === 1, `resume start left ${liveTimers} animation timers instead of one`); +check(ui.widgets.size === 1, "resume start did not install exactly one working widget"); +const resumedWidget = shipWidget(); +const resumeColumn = hullColumn(resumedWidget); +const resumeSail = sailOf(resumedWidget.render(40)); +check( + resumeColumn === freezeColumn && resumeSail === freezeSail, + `resume reset the boat instead of continuing: froze ${freezeColumn}/${freezeSail}, resumed ${resumeColumn}/${resumeSail}`, +); +// Repeated start/settle cycles must not duplicate scheduler or widget ownership. +for (let cycle = 0; cycle < 3; cycle += 1) { + await fire("agent_settled"); + check(liveTimers === 0, `cycle ${cycle} settle left ${liveTimers} timers`); + check(ui.widgets.size === 0, `cycle ${cycle} settle left a residual widget`); + await fire("agent_start"); + check(liveTimers === 1, `cycle ${cycle} start left ${liveTimers} timers`); + check(ui.widgets.size === 1, `cycle ${cycle} start left ${ui.widgets.size} widgets`); + check( + hullColumn(shipWidget()) >= freezeColumn, + `cycle ${cycle} lost continuity after repeated settle/start`, + ); +} +await fire("agent_settled"); +check(liveTimers === 0 && ui.widgets.size === 0, "repeated continuity cycles did not finish clean"); + +// A genuine fresh session resets to the normal initial position. +reset(); +await fire("session_start", { reason: "new" }); +check(liveTimers === 0 && ui.widgets.size === 0, "fresh session left a stale boat"); +await fire("agent_start"); +check(hullColumn(shipWidget()) === 0, "fresh session did not restart at the left edge"); +check(sailOf(shipWidget().render(40)) === "<|", "fresh session lost the initial rightward sail"); +await fire("agent_settled"); + +// --- Abort and failure share Pi's agent_settled path ------------------------------ +// Pi emits agent_settled from a finally block, so an aborted or failed run reaches +// exactly this handler; the real-TUI regression covers the Escape abort path. +for (const outcome of ["abort", "failure"]) { + reset(); + await fire("agent_start"); + check(liveTimers === 1, `${outcome} setup did not start the animation`); + await fire("agent_settled"); + check(liveTimers === 0, `${outcome} left ${liveTimers} animation timers`); + check(ui.widgets.size === 0, `${outcome} left a residual widget`); + check( + ui.workingVisible[ui.workingVisible.length - 1] === true, + `${outcome} did not restore Pi's stock working row`, + ); +} + +// --- Shutdown, reload, and session replacement all clean up ----------------------- +for (const reason of ["quit", "reload", "new", "resume", "fork"]) { + reset(); + await fire("agent_start"); + check(liveTimers === 1, `${reason} setup did not start the animation`); + await fire("session_shutdown", { reason }); + check(liveTimers === 0, `session_shutdown(${reason}) left ${liveTimers} animation timers`); + check(ui.widgets.size === 0, `session_shutdown(${reason}) left a residual widget`); + check( + ui.workingVisible[ui.workingVisible.length - 1] === true, + `session_shutdown(${reason}) did not restore Pi's stock working row`, + ); + if (reason === "quit") continue; + reset(); + await fire("session_start", { reason }); + check(ui.widgets.size === 0, `session_start(${reason}) installed a stale widget`); + check(liveTimers === 0, `session_start(${reason}) left ${liveTimers} animation timers`); +} + +// --- Toggling Calm off during an active run restores the stock row immediately ----- +await fire("session_start", { reason: "startup" }); +reset(); +await fire("agent_start"); +check(liveTimers === 1, "active-run setup did not start the animation"); +await calmCommand.handler("", ctx); +check(liveTimers === 0, "toggling Calm off during a run left the animation running"); +check(ui.widgets.size === 0, "toggling Calm off during a run left the boat on screen"); +check( + ui.workingVisible[ui.workingVisible.length - 1] === true, + "toggling Calm off during a run did not restore Pi's stock working row", +); + +// Toggling Calm back on during the same run returns the boat. +reset(); +await calmCommand.handler("", ctx); +check(liveTimers === 1, "toggling Calm on during a run did not return the boat"); +check( + ui.workingVisible[ui.workingVisible.length - 1] === false, + "toggling Calm on during a run did not hide Pi's stock working row", +); +await fire("agent_settled"); +check(liveTimers === 0, "the toggled-on run did not clean up"); + +// A run started after toggling Calm on while idle uses the boat. +reset(); +await calmCommand.handler("", ctx); +await calmCommand.handler("", ctx); +await fire("agent_start"); +check(liveTimers === 1, "a later run did not use the boat after an idle Calm toggle"); +await fire("agent_settled"); +check(liveTimers === 0, "the later run did not clean up"); + +// --- The visual-only widget never touches session, transcript, or export data ------ +check( + sessionWrites.length === 0, + `the working presentation wrote session or transcript data: ${JSON.stringify(sessionWrites)}`, +); + +globalThis.setInterval = realSetInterval; +globalThis.clearInterval = realClearInterval; +JS +) + status=$? + [ "$status" -eq 0 ] || fail "Pi Calm working-ship checks failed: $out" + [ -z "$out" ] || fail "Pi Calm working-ship test printed output: $out" + pass "Pi Calm working ship moves on a slow independent cadence over faster fixed-cell blue water, paints the complete boat standard yellow with balanced resets, keeps ANSI-stripped width exact, flips the directional sail on the exact bounce at both edges and every width, clamps visible and hidden resizes, falls back deterministically when narrow, freezes and resumes column/direction across settle/start without hidden-time jumps or duplicate timers, resets only on a fresh session, and installs and removes one scheduler-owning widget across starts, settle, abort, failure, shutdown, reload, replacement, and Calm toggles while leaving Calm-off visibility untouched" +} + test_interactive_terminal_e2e() { - local project config home session_file export_file export_dom default_snapshot expanded_snapshot hidden_snapshot active_before_snapshot active_hidden_snapshot export_snapshot restored_snapshot working_snapshot working_response_snapshot restarted_snapshot resumed_restored_snapshot hash_before hash_after now version chrome chrome_pid chrome_wait active_wait active_screen_wait + local project config home session_file export_file export_dom default_snapshot expanded_snapshot hidden_snapshot active_before_snapshot active_hidden_snapshot export_snapshot restored_snapshot working_snapshot working_response_snapshot restarted_snapshot resumed_restored_snapshot hash_before hash_after now version chrome chrome_pid chrome_wait active_wait active_screen_wait boat_frame_one boat_frame_two boat_resized_snapshot boat_focus_snapshot boat_cleared_snapshot boat_hull_line boat_sail_line boat_column_one boat_column_two boat_line boat_color_snapshot boat_color_line boat_water_snapshot boat_water_line boat_water_first boat_water_changed boat_narrow_snapshot boat_narrow_sails boat_freeze_snapshot boat_resume_snapshot boat_freeze_column boat_freeze_sail boat_resume_column boat_resume_sail if ! command -v pi >/dev/null 2>&1 || ! command -v tmux >/dev/null 2>&1; then echo "skip: pi or tmux not found for Pi calm interactive E2E" return 0 @@ -1615,6 +2488,16 @@ test_interactive_terminal_e2e() { restored_snapshot="$TMP_ROOT/restored.txt" working_snapshot="$TMP_ROOT/working.txt" working_response_snapshot="$TMP_ROOT/working-response.txt" + boat_frame_one="$TMP_ROOT/boat-frame-one.txt" + boat_frame_two="$TMP_ROOT/boat-frame-two.txt" + boat_resized_snapshot="$TMP_ROOT/boat-resized.txt" + boat_focus_snapshot="$TMP_ROOT/boat-focus.txt" + boat_cleared_snapshot="$TMP_ROOT/boat-cleared.txt" + boat_color_snapshot="$TMP_ROOT/boat-color.txt" + boat_water_snapshot="$TMP_ROOT/boat-water.txt" + boat_narrow_snapshot="$TMP_ROOT/boat-narrow.txt" + boat_freeze_snapshot="$TMP_ROOT/boat-freeze.txt" + boat_resume_snapshot="$TMP_ROOT/boat-resume.txt" restarted_snapshot="$TMP_ROOT/restarted.txt" resumed_restored_snapshot="$TMP_ROOT/resumed-restored.txt" mkdir -p "$project/.pi/extensions/lib" "$project/bin" "$project/state" "$config" "$home/config" @@ -1624,6 +2507,7 @@ test_interactive_terminal_e2e() { cp "$ASSISTANT_LAYOUT" "$project/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$OPERATIONAL_USER_LAYOUT" "$project/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$VISIBILITY" "$project/.pi/extensions/lib/fm-calm-visibility.ts" + cp "$WORKING_SHIP" "$project/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$ROOT/.pi/extensions/lib/fm-operational-input.ts" "$project/.pi/extensions/lib/fm-operational-input.ts" cp "$WATCH_EXT" "$project/.pi/extensions/fm-primary-pi-watch.ts" cp "$ROOT/.pi/extensions/fm-primary-turnend-guard.ts" "$project/.pi/extensions/fm-primary-turnend-guard.ts" @@ -1657,6 +2541,15 @@ export default function (pi: ExtensionAPI): void { contextWindow: 4096, maxTokens: 128, }, + { + id: "delayed-boat", + name: "Long-delay Calm working-ship fixture", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 4096, + maxTokens: 128, + }, { id: "operational-error", name: "Calm gapless operational-row fixture", @@ -1695,7 +2588,18 @@ export default function (pi: ExtensionAPI): void { stream.end(); return; } - await new Promise((resolve) => setTimeout(resolve, 1500)); + // Wake as soon as the run is aborted so Escape settles the turn promptly. + await new Promise<void>((resolve) => { + const timer = setTimeout(resolve, model.id === "delayed-boat" ? 90000 : 1500); + options?.signal?.addEventListener( + "abort", + () => { + clearTimeout(timer); + resolve(); + }, + { once: true }, + ); + }); if (options?.signal?.aborted) { output.stopReason = "aborted"; stream.push({ type: "error", reason: "aborted", error: output }); @@ -1744,6 +2648,16 @@ export default function (pi: ExtensionAPI): void { }); }, }); + pi.registerCommand("calm-boat-e2e", { + description: "Start the long-delay working-ship fixture.", + handler: async (_args, ctx) => { + const model = ctx.modelRegistry.find("calm-e2e", "delayed-boat"); + if (!model || !(await pi.setModel(model))) { + throw new Error("could not select the long-delay Calm E2E model"); + } + await pi.sendUserMessage("CALM_BOAT_E2E_PROMPT"); + }, + }); pi.registerCommand("calm-working-e2e", { description: "Start the delayed native Working-row fixture.", handler: async (_args, ctx) => { @@ -1794,6 +2708,10 @@ JSON tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" C-o wait_for_text "$expanded_snapshot" "escape to interrupt" \ || fail "Ctrl+O did not retain Pi's ordinary startup and tool expansion behavior" + # The expansion redraw lands a frame or two after the footer hint, so wait for the + # tool output this block actually asserts instead of assuming one implies the other. + wait_for_text "$expanded_snapshot" "CALM_E2E_OUTPUT" \ + || fail "ordinary Ctrl+O expansion hid tool activity while calm mode was off" assert_contains "$(cat "$expanded_snapshot")" "CALM_E2E_OUTPUT" "ordinary Ctrl+O expansion hid tool activity while calm mode was off" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm" @@ -1801,8 +2719,13 @@ JSON active_screen_wait=0 while [ "$active_screen_wait" -lt 120 ]; do tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$hidden_snapshot" + # Wait for the redraw this block actually asserts: hidden rows gone AND the + # retained genuine rows back on screen. Breaking on the hidden rows alone can + # observe a half-redrawn transcript. if ! grep -Fq "CALM_E2E_OUTPUT" "$hidden_snapshot" && - ! grep -Fq "/calm" "$hidden_snapshot"; then + ! grep -Fq "/calm" "$hidden_snapshot" && + grep -Fq "FIRSTMATE WATCHER WAKE: can you explain this phrase?" "$hidden_snapshot" && + grep -Fq "The deterministic tool example is complete." "$hidden_snapshot"; then break fi sleep 0.05 @@ -2031,10 +2954,258 @@ JS done [ "$(cat "$home/config/calm")" = on ] || fail "third /calm did not persist the active choice" + # Calm on plus a genuinely active run replaces Pi's stock working row with the boat. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm-boat-e2e" + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$working_snapshot" + if grep -Fq '\__/' "$working_snapshot"; then + break + fi + sleep 0.025 + active_screen_wait=$((active_screen_wait + 1)) + done + cp "$working_snapshot" "$boat_frame_one" + assert_contains "$(cat "$boat_frame_one")" '\__/' "Calm did not show the working ship during a real provider wait" + assert_not_contains "$(cat "$boat_frame_one")" "Working..." "Calm left Pi's stock working row visible while the ship was shown" + assert_not_contains "$(cat "$boat_frame_one")" "calm transcript" "the real provider wait showed a persistent Calm status row" + assert_not_contains "$(cat "$boat_frame_one")" "FIRSTMATE WATCHER WAKE: signal: /tmp/probe.status" "the real provider wait restored a hidden operational row" + boat_hull_line=$(grep -F '\__/' "$boat_frame_one" | head -1) + boat_sail_line=$(grep -E '<\||\|>' "$boat_frame_one" | tail -1) + case "$boat_sail_line" in + *'<|'*|*'|>'*) : ;; + *) fail "the working ship lost its directional mainsail" ;; + esac + assert_not_contains "$boat_hull_line" "Working" "the ship row carried extra status copy" + case "$boat_hull_line" in + *~*) : ;; + *) fail "the working ship rendered no waves" ;; + esac + # Standard ANSI colors: blue water, yellow boat, no theme/bright/256/RGB escapes. + tmux -L "$TMUX_SOCKET" capture-pane -p -e -t "$TMUX_SESSION" >"$boat_color_snapshot" + boat_color_line=$(grep -F '\__/' "$boat_color_snapshot" | head -1) + [ -n "$boat_color_line" ] || fail "could not capture a colored working-ship row" + case "$boat_color_line" in + *'[34m'*) : ;; + *) fail "the water was not rendered with standard ANSI blue" ;; + esac + case "$boat_color_line" in + *'[33m'*) : ;; + *) fail "the boat was not rendered with standard ANSI yellow" ;; + esac + case "$boat_color_line" in + *'[38;2;'*|*'[38;5;'*|*'[9'[0-9]'m'*) fail "the working ship used a non-standard color escape" ;; + *) : ;; + esac + + # The water animates on its own faster cadence while the boat holds its column. + boat_column_one=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_frame_one") + boat_water_changed=0 + boat_water_first=$(grep -F '\__/' "$boat_frame_one" | head -1) + active_screen_wait=0 + while [ "$active_screen_wait" -lt 60 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_water_snapshot" + boat_water_line=$(grep -F '\__/' "$boat_water_snapshot" | head -1) + boat_column_two=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_water_snapshot") + if [ -n "$boat_water_line" ] && [ "$boat_column_two" = "$boat_column_one" ] && + [ "$boat_water_line" != "$boat_water_first" ]; then + boat_water_changed=1 + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + [ "$boat_water_changed" -eq 1 ] \ + || fail "the water never animated while the working ship held its column" + + # Two frames at different hull columns prove genuine horizontal motion. + boat_column_two="" + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_frame_two" + boat_column_two=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_frame_two") + if [ -n "$boat_column_two" ] && [ "$boat_column_two" != "$boat_column_one" ]; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + [ -n "$boat_column_two" ] || fail "the working ship disappeared between animation frames" + [ "$boat_column_two" != "$boat_column_one" ] \ + || fail "the working ship never moved horizontally (stuck at column $boat_column_one)" + + # The widget owns its own geometry, so resizing the same running TUI must reflow it. + tmux -L "$TMUX_SOCKET" set-option -t "$TMUX_SESSION" window-size manual + tmux -L "$TMUX_SOCKET" resize-window -t "$TMUX_SESSION" -x 100 -y 30 + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_resized_snapshot" + boat_hull_line=$(grep -F '\__/' "$boat_resized_snapshot" | head -1) + if [ -n "$boat_hull_line" ] && [ "${#boat_hull_line}" -eq 100 ]; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + assert_contains "$(cat "$boat_resized_snapshot")" '\__/' "the working ship left the screen after a resize" + boat_hull_line=$(grep -F '\__/' "$boat_resized_snapshot" | head -1) + [ "${#boat_hull_line}" -eq 100 ] \ + || fail "after resizing to 100 columns the ship row was ${#boat_hull_line} cells instead of exactly 100" + # Exactly one wave row means the sprite reflowed rather than wrapping onto extra rows. + [ "$(grep -c -F '\__/' "$boat_resized_snapshot")" -eq 1 ] \ + || fail "the working ship wrapped onto more than one water row after the resize" + while IFS= read -r boat_line; do + [ "${#boat_line}" -le 100 ] \ + || fail "a rendered line was ${#boat_line} cells after resizing to 100 columns" + done <"$boat_resized_snapshot" + boat_column_one=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_resized_snapshot") + [ "$boat_column_one" -le 97 ] \ + || fail "the working ship hull started at column $boat_column_one and cannot fit in 100 columns" + + # Motion continues on-screen after the resize instead of jumping offscreen. + boat_column_two="" + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_resized_snapshot" + boat_column_two=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_resized_snapshot") + if [ -n "$boat_column_two" ] && [ "$boat_column_two" != "$boat_column_one" ]; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + [ -n "$boat_column_two" ] && [ "$boat_column_two" != "$boat_column_one" ] \ + || fail "the working ship stopped moving after the resize" + [ "$boat_column_two" -le 97 ] \ + || fail "the working ship moved offscreen after the resize" + + # A narrow terminal shortens the track enough to observe both bounce directions. + # The sail must show the heading it is about to travel, so a full traverse shows both. + tmux -L "$TMUX_SOCKET" resize-window -t "$TMUX_SESSION" -x 12 -y 20 + boat_narrow_sails="" + active_screen_wait=0 + while [ "$active_screen_wait" -lt 400 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_narrow_snapshot" + if grep -Fq '<|' "$boat_narrow_snapshot"; then + case "$boat_narrow_sails" in *R*) : ;; *) boat_narrow_sails="${boat_narrow_sails}R" ;; esac + fi + if grep -Fq '|>' "$boat_narrow_snapshot"; then + case "$boat_narrow_sails" in *L*) : ;; *) boat_narrow_sails="${boat_narrow_sails}L" ;; esac + fi + case "$boat_narrow_sails" in + *R*L*|*L*R*) break ;; + esac + sleep 0.1 + active_screen_wait=$((active_screen_wait + 1)) + done + case "$boat_narrow_sails" in + *R*L*|*L*R*) : ;; + *) fail "the working ship never showed both sail headings on a narrow track (saw '$boat_narrow_sails')" ;; + esac + boat_hull_line=$(grep -F '\__/' "$boat_narrow_snapshot" | head -1) + [ "${#boat_hull_line}" -eq 12 ] \ + || fail "the narrow working-ship row was ${#boat_hull_line} cells instead of exactly 12" + tmux -L "$TMUX_SOCKET" resize-window -t "$TMUX_SESSION" -x 100 -y 30 + + # Typing still reaches the editor while the animation runs. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "FOCUSPROBE" + wait_for_text "$boat_focus_snapshot" "FOCUSPROBE" \ + || fail "keyboard input did not reach the editor while the working ship animated" + i=0 + while [ "$i" -lt 10 ]; do + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" BSpace + i=$((i + 1)) + done + + # Capture the last on-screen column and sail before settling so the next working + # period in this same Pi session can prove freeze/resume continuity. + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_freeze_snapshot" + boat_freeze_column=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_freeze_snapshot") + boat_freeze_sail=$(grep -E '<\||\|>' "$boat_freeze_snapshot" | tail -1 || true) + case "$boat_freeze_sail" in + *'<|'*) boat_freeze_sail='<|' ;; + *'|>'*) boat_freeze_sail='|>' ;; + *) fail "could not read the freeze-frame sail heading" ;; + esac + [ -n "$boat_freeze_column" ] && [ "$boat_freeze_column" -gt 1 ] \ + || fail "freeze frame never left the left edge (column '${boat_freeze_column:-empty}')" + + # Escape aborts the run, and the abort path removes the ship with no residue. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" Escape + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_cleared_snapshot" + if ! grep -Fq '\__/' "$boat_cleared_snapshot"; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + assert_not_contains "$(cat "$boat_cleared_snapshot")" '\__/' "Escape did not remove the working ship" + assert_not_contains "$(cat "$boat_cleared_snapshot")" "CALM_WORKING_E2E_RESPONSE" "the long-delay fixture settled instead of aborting on Escape" + assert_not_contains "$(cat "$boat_cleared_snapshot")" "FOCUSPROBE" "the editor kept the focus probe text after Escape" + + # A later working period in the same Pi process must resume the frozen column and + # sail rather than recreating the boat at the left edge. Capture the first resumed + # frames quickly so the slow boat cadence cannot advance before the assertion. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm-boat-e2e" + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s + boat_resume_column="" + boat_resume_sail="" + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_resume_snapshot" + if grep -Fq '\__/' "$boat_resume_snapshot"; then + boat_resume_column=$(awk 'index($0,"\\__/"){print index($0,"\\__/"); exit}' "$boat_resume_snapshot") + boat_resume_sail=$(grep -E '<\||\|>' "$boat_resume_snapshot" | tail -1 || true) + case "$boat_resume_sail" in + *'<|'*) boat_resume_sail='<|' ;; + *'|>'*) boat_resume_sail='|>' ;; + esac + break + fi + sleep 0.025 + active_screen_wait=$((active_screen_wait + 1)) + done + [ -n "$boat_resume_column" ] \ + || fail "the second working period never showed the working ship" + [ "$boat_resume_column" -eq "$boat_freeze_column" ] \ + || fail "the second working period reset the boat from column $boat_freeze_column to $boat_resume_column instead of resuming" + [ "$boat_resume_sail" = "$boat_freeze_sail" ] \ + || fail "the second working period changed sail from $boat_freeze_sail to $boat_resume_sail" + assert_not_contains "$(cat "$boat_resume_snapshot")" "Working..." \ + "the second working period left Pi's stock working row visible" + + # Clear the resumed run before the Calm-off stock-row probe. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" Escape + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_cleared_snapshot" + if ! grep -Fq '\__/' "$boat_cleared_snapshot"; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + assert_not_contains "$(cat "$boat_cleared_snapshot")" '\__/' "Escape did not remove the resumed working ship" + + # Calm off restores Pi's stock working row and never shows the ship. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm" + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + if [ "$(cat "$home/config/calm")" = off ]; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + [ "$(cat "$home/config/calm")" = off ] || fail "the Calm-off working-row probe did not turn Calm off" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm-working-e2e" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s active_screen_wait=0 - while [ "$active_screen_wait" -lt 120 ]; do + while [ "$active_screen_wait" -lt 200 ]; do tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$working_snapshot" if grep -Fq "Working..." "$working_snapshot"; then break @@ -2042,11 +3213,28 @@ JS sleep 0.025 active_screen_wait=$((active_screen_wait + 1)) done - assert_contains "$(cat "$working_snapshot")" "Working..." "Calm hid Pi's built-in Working row during a real provider wait" - assert_not_contains "$(cat "$working_snapshot")" "calm transcript" "the real provider wait showed a persistent Calm status row" - assert_not_contains "$(cat "$working_snapshot")" "FIRSTMATE WATCHER WAKE: signal: /tmp/probe.status" "the real provider wait restored a hidden operational row" + assert_contains "$(cat "$working_snapshot")" "Working..." "Calm off did not keep Pi's stock working row" + assert_not_contains "$(cat "$working_snapshot")" '\__/' "Calm off showed the working ship" wait_for_text "$working_response_snapshot" "CALM_WORKING_E2E_RESPONSE" \ - || fail "the deterministic provider did not settle after proving Pi's Working row" + || fail "the deterministic provider did not settle after proving Pi's stock working row" + + # No blank-row residue: settling returns to the same layout Calm off started from. + tmux -L "$TMUX_SOCKET" capture-pane -p -t "$TMUX_SESSION" >"$boat_cleared_snapshot" + assert_not_contains "$(cat "$boat_cleared_snapshot")" '\__/' "a settled run left the working ship on screen" + + # Restore Calm for the persistence restart below. + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/calm" + tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s + active_screen_wait=0 + while [ "$active_screen_wait" -lt 200 ]; do + if [ "$(cat "$home/config/calm")" = on ]; then + break + fi + sleep 0.05 + active_screen_wait=$((active_screen_wait + 1)) + done + [ "$(cat "$home/config/calm")" = on ] || fail "Calm was not restored before the persistence restart" + tmux -L "$TMUX_SOCKET" resize-window -t "$TMUX_SESSION" -x 180 -y 44 tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/quit" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s @@ -2082,7 +3270,7 @@ JS [ "$(cat "$home/config/calm")" = off ] || fail "/calm after restart did not persist the inactive choice" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" -l "/quit" tmux -L "$TMUX_SOCKET" send-keys -t "$TMUX_SESSION" M-s - pass "Pi calm native E2E keeps Working and captain turns visible, hides exact operational user rows without changing persistence, restores them Calm-off, survives restart, and preserves export plus Ctrl+O behavior" + pass "Pi calm native E2E replaces the stock working row with a moving, resize-clamped working ship that freezes and resumes across two working periods in one Pi session, clears on abort, keeps captain turns visible, hides exact operational user rows without changing persistence, restores stock rendering Calm-off, survives restart, and preserves export plus Ctrl+O behavior" } test_home_resolution @@ -2092,4 +3280,5 @@ test_pi_compat_missing_adapter_exports test_rendering_and_session_lifecycle test_operational_followup_turn_e2e test_hidden_block_geometry_e2e +test_working_ship_geometry_and_lifecycle test_interactive_terminal_e2e diff --git a/tests/fm-crew-state.test.sh b/tests/fm-crew-state.test.sh index bc0161d624f..8f986b6139e 100755 --- a/tests/fm-crew-state.test.sh +++ b/tests/fm-crew-state.test.sh @@ -5,7 +5,7 @@ # The status file (state/<id>.status) is a best-effort append-only EVENT LOG, so # `tail -1` of it reports the last event, not the current state. fm-crew-state # reads the AUTHORITATIVE source (a matching no-mistakes run-step, else the -# pane busy-signature) and reconciles the possibly-stale log against it. These +# semantic busy-state contract) and reconciles the possibly-stale log against it. These # cases pin every branch of that logic, hermetically, over real throwaway git # repos with a fake `no-mistakes` (run-step source) and a fake `tmux` (pane # source): @@ -14,8 +14,8 @@ # (c) genuine parked run + needs-decision log = NOT superseded -> run-step # (d) terminal run-step (passed/failed) is authoritative -> run-step # (e) cross-branch attribution: this branch's own run found via list lookup -# (f) no run + busy pane -> pane -# (g) no run + idle pane falls to the status-log verb -> status-log +# (f) no run + semantic busy -> pane +# (g) no run + semantic idle falls to the status-log verb -> status-log # (h) dead pane: no run -> unknown/none; with a run -> run-step (not the shell) # (i) kind=scout skips the run lookup -> pane/status-log # (j) torn-down worktree / missing meta -> unknown/none @@ -88,7 +88,7 @@ case "${1:-}" in printf '%%1\n' ;; capture-pane) [ "${FM_FAKE_TMUX_MISSING:-0}" = 1 ] && exit 1 - if [ "${FM_FAKE_BUSY:-0}" = 1 ]; then printf 'work in progress\nesc to interrupt\n' + if [ "${FM_FAKE_BUSY:-0}" = 1 ]; then printf 'work in progress\n%s\n' "${FM_FAKE_BUSY_TEXT:-esc to interrupt}" else printf 'all quiet\n> \n'; fi ;; esac exit 0 @@ -149,6 +149,13 @@ new_case() { # <name> -> echoes case dir with an empty state/ printf '%s\n' "$d" } +arm_idle_record() { # <state-dir> <id> + local state=$1 id=$2 gen + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" "$id") + "$ROOT/bin/fm-busy-event.sh" apply "$state" "$id" idle --gen "$gen" \ + --source claude-hook --event stop +} + # Clear the fake-driver vars and (re-)mark them exported, so the per-test plain # assignments below stay exported into the fakes without an `export VAR=$(...)` # command-substitution assignment (SC2155). @@ -157,12 +164,13 @@ reset_fakes() { FM_FAKE_AXI_STATUS_RUN="" FM_FAKE_RUNS_LIST="" FM_FAKE_BUSY=0 + FM_FAKE_BUSY_TEXT= FM_FAKE_TMUX_MISSING=0 FM_FAKE_HERDR_BUSY=0 FM_FAKE_HERDR_MISSING=0 FM_FAKE_HERDR_AGENT_STATUS="" FM_FAKE_CI_LOGS="" - export FM_FAKE_AXI_STATUS FM_FAKE_AXI_STATUS_RUN FM_FAKE_RUNS_LIST FM_FAKE_BUSY FM_FAKE_TMUX_MISSING + export FM_FAKE_AXI_STATUS FM_FAKE_AXI_STATUS_RUN FM_FAKE_RUNS_LIST FM_FAKE_BUSY FM_FAKE_BUSY_TEXT FM_FAKE_TMUX_MISSING export FM_FAKE_HERDR_BUSY FM_FAKE_HERDR_MISSING FM_FAKE_HERDR_AGENT_STATUS FM_FAKE_CI_LOGS } @@ -759,7 +767,7 @@ test_other_branch_run_ignored() { local d; d=$(new_case otherbranch) make_repo_on_branch "$d/wt" fm/feat-g make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-g.meta" "window=fm:fm-feat-g" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-g.meta" "window=fm:fm-feat-g" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'done: implemented, ready to validate\n' > "$d/state/feat-g.status" FM_FAKE_AXI_STATUS="$(run_running fm/some-other)" FM_FAKE_RUNS_LIST="$(cat <<'EOF' @@ -767,6 +775,7 @@ test_other_branch_run_ignored() { EOF )" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" feat-g local out; out=$(run_crew_state "$d" feat-g) assert_not_contains "$out" "source: run-step" "another branch's run not misattributed" assert_contains "$out" "source: status-log" "no own run -> falls back to status-log" @@ -780,15 +789,60 @@ test_no_run_busy_pane() { local d; d=$(new_case busy) make_repo_on_branch "$d/wt" fm/feat-h make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-h.meta" "window=fm:fm-feat-h" "worktree=$d/wt" "kind=ship" - # No matching run anywhere. + fm_write_meta "$d/state/feat-h.meta" "window=fm:fm-feat-h" "worktree=$d/wt" "kind=ship" "harness=claude" + # No matching run anywhere. The busy verdict comes from the crew's own + # semantic lifecycle record (bin/fm-busy-lib.sh), not from rendered text. FM_FAKE_AXI_STATUS="" FM_FAKE_RUNS_LIST="" FM_FAKE_BUSY=1 + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$d/state" feat-h) + "$ROOT/bin/fm-busy-event.sh" apply "$d/state" feat-h busy --gen "$gen" \ + --source claude-hook --event user-prompt-submit local out; out=$(run_crew_state "$d" feat-h) - assert_contains "$out" "state: working" "busy pane -> working" - assert_contains "$out" "source: pane" "busy pane -> pane source" - pass "no run + busy pane reads working from the pane" + assert_contains "$out" "state: working" "busy record -> working" + assert_contains "$out" "source: pane" "busy record -> pane source" + assert_contains "$out" "claude-hook" "the working verdict names its semantic source" + pass "no run + a busy semantic record reads working, attributed to its source" +} + +# A converted adapter must NOT read working from rendered footer text: the +# redesign removed that dependency, so a pane painting "esc to interrupt" with +# no semantic record is unknown, never working and never silently idle. +test_no_run_footer_text_alone_is_not_working() { + reset_fakes + local d; d=$(new_case busy-footer-only) + make_repo_on_branch "$d/wt" fm/feat-h2 + make_fakebin "$d" >/dev/null + fm_write_meta "$d/state/feat-h2.meta" "window=fm:fm-feat-h2" "worktree=$d/wt" "kind=ship" "harness=claude" + FM_FAKE_AXI_STATUS="" + FM_FAKE_RUNS_LIST="" + FM_FAKE_BUSY=1 + printf 'done: stale completion event\n' > "$d/state/feat-h2.status" + local out; out=$(run_crew_state "$d" feat-h2) + assert_not_contains "$out" "state: working" "a footer alone must not read working for a converted adapter" + assert_contains "$out" "state: unknown" "no semantic record -> unknown" + assert_not_contains "$out" "source: status-log" "unknown semantic state must not fall through to a stale log" + pass "a converted adapter never reads working from rendered footer text" +} + +# Grok keeps its isolated temporary rendered-tail fallback until its structured +# lifecycle is live-verified, so a grok crew still reads working from its own +# verified signature. +test_no_run_grok_uses_isolated_fallback() { + reset_fakes + local d; d=$(new_case busy-grok) + make_repo_on_branch "$d/wt" fm/feat-h3 + make_fakebin "$d" >/dev/null + fm_write_meta "$d/state/feat-h3.meta" "window=fm:fm-feat-h3" "worktree=$d/wt" "kind=ship" "harness=grok" + FM_FAKE_AXI_STATUS="" + FM_FAKE_RUNS_LIST="" + FM_FAKE_BUSY=1 + FM_FAKE_BUSY_TEXT='Ctrl+c:cancel' + export FM_FAKE_BUSY_TEXT + local out; out=$(run_crew_state "$d" feat-h3) + assert_contains "$out" "state: working" "grok busy tail -> working" + assert_contains "$out" "grok-regex" "the grok verdict names its isolated fallback source" + pass "grok still reads working through its isolated rendered-tail fallback" } test_no_run_herdr_unknown_uses_backend_capture() { @@ -797,68 +851,76 @@ test_no_run_herdr_unknown_uses_backend_capture() { local d; d=$(new_case herdr-busy) make_repo_on_branch "$d/wt" fm/feat-herdr make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-herdr.meta" "window=default:w1:p2" "worktree=$d/wt" "kind=ship" "backend=herdr" + fm_write_meta "$d/state/feat-herdr.meta" "window=default:w1:p2" "worktree=$d/wt" "kind=ship" \ + "backend=herdr" "harness=claude" FM_FAKE_AXI_STATUS="" FM_FAKE_RUNS_LIST="" FM_FAKE_TMUX_MISSING=1 FM_FAKE_HERDR_BUSY=1 - FM_FAKE_HERDR_AGENT_STATUS="" + FM_FAKE_HERDR_AGENT_STATUS=working local out; out=$(run_crew_state "$d" feat-herdr) - assert_contains "$out" "state: working" "herdr busy pane -> working" - assert_contains "$out" "source: pane" "herdr busy pane -> pane source" - pass "herdr unknown native state falls back to backend capture busy regex" -} - -# Regression: herdr's agent.get reports generation state ("working" only while -# the model is actively streaming a turn - docs/herdr-backend.md "Busy state"), -# not "this crew's tool call is still in progress". A crew blocked on its own -# long-running foreground `no-mistakes axi run` (no --yes; blocks until a gate -# or outcome) is not generating for that whole span, so agent.get can read -# idle while the pane's own rendered text still shows the busy banner -# (BUSY_REGEX) for the entire call. `idle` must be corroborated with that text -# exactly like `unknown` already is, not trusted outright - the bug this -# regression pins: crew_pane_is_busy previously returned "not busy" on a bare -# `idle` verdict without ever looking at the pane. -test_no_run_herdr_idle_agent_status_corroborated_by_busy_pane() { + assert_contains "$out" "state: working" "herdr native busy -> working" + assert_contains "$out" "source: pane" "herdr native busy -> pane source" + assert_contains "$out" "herdr-native" "the herdr verdict names its native source" + pass "herdr's native busy verdict reads working with no record present" +} + +# Regression (2026-07 herdr false-surface incident, now solved semantically): +# herdr's agent.get reports generation state ("working" only while the model is +# actively streaming - docs/herdr-backend.md "Busy state"), not "this crew's +# turn is still in progress". A crew blocked on its own long-running foreground +# `no-mistakes axi run` (no --yes; blocks until a gate or outcome) is not +# generating for that whole span, so agent.get reads idle. The crew's own +# semantic lifecycle record still says busy for the whole turn, and it outranks +# the narrower native verdict - so the crew is no longer misread as not-working. +test_no_run_herdr_idle_agent_status_outranked_by_record() { command -v jq >/dev/null 2>&1 || { pass "herdr idle corroboration skipped without jq"; return; } reset_fakes - local d; d=$(new_case herdr-idle-busy-pane) + local d; d=$(new_case herdr-idle-busy-record) make_repo_on_branch "$d/wt" fm/feat-herdr-idle make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-herdr-idle.meta" "window=default:w1:p3" "worktree=$d/wt" "kind=ship" "backend=herdr" + fm_write_meta "$d/state/feat-herdr-idle.meta" "window=default:w1:p3" "worktree=$d/wt" "kind=ship" \ + "backend=herdr" "harness=claude" # No run attributable (mirrors a no-mistakes run-step lookup that found no - # matching row within the configured runs-list window): the pane fallback is - # the only remaining signal. + # matching row within the configured runs-list window): the crew's semantic + # busy state is the only remaining signal. FM_FAKE_AXI_STATUS="" FM_FAKE_RUNS_LIST="" FM_FAKE_TMUX_MISSING=1 FM_FAKE_HERDR_AGENT_STATUS=idle - FM_FAKE_HERDR_BUSY=1 + FM_FAKE_HERDR_BUSY=0 + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$d/state" feat-herdr-idle) + "$ROOT/bin/fm-busy-event.sh" apply "$d/state" feat-herdr-idle busy --gen "$gen" \ + --source claude-hook --event user-prompt-submit local out; out=$(run_crew_state "$d" feat-herdr-idle) - assert_contains "$out" "state: working" "herdr idle agent_status with a busy-banner pane -> working" - assert_contains "$out" "source: pane" "herdr idle agent_status with a busy-banner pane -> pane source" - pass "herdr idle agent_status is corroborated by the pane text, not trusted outright" + assert_contains "$out" "state: working" "a busy record with herdr idle agent_status -> working" + assert_contains "$out" "claude-hook" "the record's source outranks herdr's narrower native verdict" + pass "a mid-tool-call crew stays working because its record outranks herdr's generation state" } -# The corroboration must not mask a genuinely idle/human-blocked agent: idle -# agent_status AND an idle-looking pane (no busy banner) still reads not-busy. -test_no_run_herdr_idle_agent_status_and_idle_pane_stays_idle() { - command -v jq >/dev/null 2>&1 || { pass "herdr idle+idle-pane skipped without jq"; return; } +# The record must not mask a genuinely idle or human-blocked agent: an idle +# record with idle agent_status still reads not-busy. +test_no_run_herdr_idle_agent_status_and_idle_record_stays_idle() { + command -v jq >/dev/null 2>&1 || { pass "herdr idle+idle-record skipped without jq"; return; } reset_fakes - local d; d=$(new_case herdr-idle-idle-pane) + local d; d=$(new_case herdr-idle-idle-record) make_repo_on_branch "$d/wt" fm/feat-herdr-stopped make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-herdr-stopped.meta" "window=default:w1:p4" "worktree=$d/wt" "kind=ship" "backend=herdr" + fm_write_meta "$d/state/feat-herdr-stopped.meta" "window=default:w1:p4" "worktree=$d/wt" "kind=ship" \ + "backend=herdr" "harness=claude" printf 'working: implementing\n' > "$d/state/feat-herdr-stopped.status" FM_FAKE_AXI_STATUS="" FM_FAKE_RUNS_LIST="" FM_FAKE_TMUX_MISSING=1 FM_FAKE_HERDR_AGENT_STATUS=idle FM_FAKE_HERDR_BUSY=0 + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$d/state" feat-herdr-stopped) + "$ROOT/bin/fm-busy-event.sh" apply "$d/state" feat-herdr-stopped idle --gen "$gen" \ + --source claude-hook --event stop local out; out=$(run_crew_state "$d" feat-herdr-stopped) - assert_not_contains "$out" "source: pane" "herdr idle agent_status with an idle pane must not read as busy from the pane" - assert_contains "$out" "source: status-log" "herdr idle agent_status with an idle pane falls to the status log" - pass "herdr idle agent_status with a genuinely idle pane stays not-busy (no regression for a human-blocked agent)" + assert_not_contains "$out" "source: pane" "an idle record must not read as busy" + assert_contains "$out" "source: status-log" "an idle record falls to the status log" + pass "an idle record with idle agent_status stays not-busy (no regression for a human-blocked agent)" } # (g) no run + idle pane -> the status-log verb, as-is @@ -867,10 +929,11 @@ test_no_run_idle_pane_uses_log() { local d; d=$(new_case idle) make_repo_on_branch "$d/wt" fm/feat-i make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-i.meta" "window=fm:fm-feat-i" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-i.meta" "window=fm:fm-feat-i" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'needs-decision: which database?\n' > "$d/state/feat-i.status" FM_FAKE_AXI_STATUS="" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" feat-i local out; out=$(run_crew_state "$d" feat-i) assert_contains "$out" "state: parked" "needs-decision log -> parked" assert_contains "$out" "source: status-log" "idle pane -> status-log source" @@ -882,10 +945,11 @@ test_no_run_idle_pane_uses_keyed_log() { local d; d=$(new_case keyed-idle) make_repo_on_branch "$d/wt" fm/feat-keyed make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-keyed.meta" "window=fm:fm-feat-keyed" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-keyed.meta" "window=fm:fm-feat-keyed" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'needs-decision [key=q1]: which database?\n' > "$d/state/feat-keyed.status" FM_FAKE_AXI_STATUS="" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" feat-keyed local out; out=$(run_crew_state "$d" feat-keyed) assert_contains "$out" "state: parked" "keyed needs-decision log -> parked" assert_contains "$out" "which database?" "key token is excluded from status detail" @@ -900,10 +964,11 @@ test_no_run_idle_pane_paused() { local d; d=$(new_case paused) make_repo_on_branch "$d/wt" fm/feat-pause make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-pause.meta" "window=fm:fm-feat-pause" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-pause.meta" "window=fm:fm-feat-pause" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'paused: holding for the upstream tool release\n' > "$d/state/feat-pause.status" FM_FAKE_AXI_STATUS="" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" feat-pause local out; out=$(run_crew_state "$d" feat-pause) assert_contains "$out" "state: paused" "paused log -> paused" assert_contains "$out" "source: status-log" "idle pause -> status-log source" @@ -916,10 +981,11 @@ test_no_run_idle_pane_custom_paused_verb() { local d; d=$(new_case custom-paused) make_repo_on_branch "$d/wt" fm/feat-custom-pause make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/feat-custom-pause.meta" "window=fm:fm-feat-custom-pause" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-custom-pause.meta" "window=fm:fm-feat-custom-pause" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'awaiting: vendor maintenance window\n' > "$d/state/feat-custom-pause.status" FM_FAKE_AXI_STATUS="" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" feat-custom-pause local out; out=$(FM_CLASSIFY_PAUSED_VERB=awaiting run_crew_state "$d" feat-custom-pause) assert_contains "$out" "state: paused" "custom paused verb -> paused" assert_contains "$out" "source: status-log" "custom paused verb -> status-log source" @@ -1033,8 +1099,12 @@ while :; do :; done SH chmod +x "$d/fakebin/no-mistakes" toolbin=$(make_no_timeout_toolbin "$d") - fm_write_meta "$d/state/feat-timeout.meta" "window=fm:fm-feat-timeout" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/feat-timeout.meta" "window=fm:fm-feat-timeout" "worktree=$d/wt" "kind=ship" \ + "harness=claude" FM_FAKE_BUSY=1 + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$d/state" feat-timeout) + "$ROOT/bin/fm-busy-event.sh" apply "$d/state" feat-timeout busy --gen "$gen" \ + --source claude-hook --event user-prompt-submit start=$SECONDS out=$(FM_FAKE_NM_CALLS="$calls_file" PATH="$d/fakebin:$toolbin" FM_STATE_OVERRIDE="$d/state" FM_CREW_STATE_NM_TIMEOUT=1 "$CREW_STATE" feat-timeout) elapsed=$((SECONDS - start)) @@ -1052,13 +1122,17 @@ test_scout_skips_run_lookup() { local d; d=$(new_case scout) make_repo_on_branch "$d/wt" fm/scout-j make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/scout-j.meta" "window=fm:fm-scout-j" "worktree=$d/wt" "kind=scout" + fm_write_meta "$d/state/scout-j.meta" "window=fm:fm-scout-j" "worktree=$d/wt" "kind=scout" \ + "harness=claude" # Even if a run existed on this branch, a scout must not read it. FM_FAKE_AXI_STATUS="$(run_running fm/scout-j)" FM_FAKE_BUSY=1 + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$d/state" scout-j) + "$ROOT/bin/fm-busy-event.sh" apply "$d/state" scout-j busy --gen "$gen" \ + --source claude-hook --event user-prompt-submit local out; out=$(run_crew_state "$d" scout-j) assert_not_contains "$out" "source: run-step" "scout ignores no-mistakes run-step" - assert_contains "$out" "source: pane" "scout reads pane busy-signature" + assert_contains "$out" "source: pane" "scout reads its semantic busy state" pass "scout skips the run lookup" } @@ -1157,12 +1231,13 @@ test_historical_same_branch_rewritten_head_not_current() { new_head=$(git -C "$d/wt" rev-parse HEAD) [ "$old_head" != "$new_head" ] || fail "rewrite did not produce a new head" make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/wishlist.meta" "window=fm:fm-wishlist" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/wishlist.meta" "window=fm:fm-wishlist" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'working: stage 2 setup complete rebased onto merged #76\n' > "$d/state/wishlist.status" # Historical run still reports the pre-rewrite head on the reused branch. FM_FAKE_RUN_HEAD="$old_head" FM_FAKE_AXI_STATUS="$(run_parked fm/todo-flag)" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" wishlist out=$(run_crew_state "$d" wishlist) assert_not_contains "$out" "source: run-step" "historical rewritten head must not use run-step" assert_not_contains "$out" "parked at" "historical parked run must not mask current state" @@ -1202,11 +1277,12 @@ test_local_advanced_past_run_head_invalidates() { run_head=$(git -C "$d/wt" rev-parse HEAD) git -C "$d/wt" commit -q --allow-empty -m 'local stage-2 work after prior run' make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/adv.meta" "window=fm:fm-adv" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/adv.meta" "window=fm:fm-adv" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'working: stage 2 implementation in progress\n' > "$d/state/adv.status" FM_FAKE_RUN_HEAD="$run_head" FM_FAKE_AXI_STATUS="$(run_parked fm/feat-adv)" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" adv out=$(run_crew_state "$d" adv) assert_not_contains "$out" "source: run-step" "local-advanced tip must not use historical run" assert_contains "$out" "source: status-log" "falls back after local advanced past run" @@ -1220,11 +1296,12 @@ test_missing_run_head_falls_back_to_current_state() { d=$(new_case missing-run-head) make_repo_on_branch "$d/wt" fm/feat-no-head make_fakebin "$d" >/dev/null - fm_write_meta "$d/state/no-head.meta" "window=fm:fm-no-head" "worktree=$d/wt" "kind=ship" + fm_write_meta "$d/state/no-head.meta" "window=fm:fm-no-head" "worktree=$d/wt" "kind=ship" "harness=claude" printf 'working: current stage still in progress\n' > "$d/state/no-head.status" FM_FAKE_AXI_STATUS=$(run_parked fm/feat-no-head | grep -v '^ head:') FM_FAKE_RUNS_LIST="" FM_FAKE_BUSY=0 + arm_idle_record "$d/state" no-head out=$(run_crew_state "$d" no-head) assert_not_contains "$out" "source: run-step" "missing run head must not permit branch-only attribution" assert_contains "$out" "source: status-log" "missing run head falls back to current state sources" @@ -1257,9 +1334,11 @@ test_cross_branch_attribution_picks_most_recent_row test_coarse_run_does_not_probe_other_branch_ci_log_for_ready_status test_other_branch_run_ignored test_no_run_busy_pane +test_no_run_footer_text_alone_is_not_working +test_no_run_grok_uses_isolated_fallback test_no_run_herdr_unknown_uses_backend_capture -test_no_run_herdr_idle_agent_status_corroborated_by_busy_pane -test_no_run_herdr_idle_agent_status_and_idle_pane_stays_idle +test_no_run_herdr_idle_agent_status_outranked_by_record +test_no_run_herdr_idle_agent_status_and_idle_record_stays_idle test_no_run_idle_pane_uses_log test_no_run_idle_pane_uses_keyed_log test_no_run_idle_pane_paused diff --git a/tests/fm-daemon.test.sh b/tests/fm-daemon.test.sh index a1fbd7f5fea..0cadb5af1f6 100755 --- a/tests/fm-daemon.test.sh +++ b/tests/fm-daemon.test.sh @@ -22,6 +22,8 @@ if [ -z "${FM_TEST_DAEMON_SOURCED:-}" ]; then fi TMP_ROOT=$(fm_test_tmproot fm-daemon-tests) +FM_DAEMON_PRIMARY_HARNESS=claude +export FM_DAEMON_PRIMARY_HARNESS test_afk_start_refuses_when_flag_cannot_be_written() { local dir state out status @@ -356,6 +358,10 @@ test_housekeeping_paused_resumed_cleared() { win="sess:fm-held-w12"; pane="$dir/pane.txt" printf 'paused: holding for the upstream tool release\n' > "$state/held-w12.status" printf 'Working...\n' > "$pane" + fm_write_meta "$state/held-w12.meta" "window=$win" "worktree=$dir/wt" "kind=ship" "harness=pi" + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" held-w12) + "$ROOT/bin/fm-busy-event.sh" apply "$state" held-w12 busy --gen "$gen" \ + --source pi-ext --event agent-start key=$(printf '%s' "held-w12" | tr ':/.' '___') echo $(( $(date +%s) - 5000 )) > "$state/.subsuper-paused-$key" PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$pane" \ @@ -443,6 +449,12 @@ test_housekeeping_resumed_stale_cleared() { pane="$dir/pane.txt" printf 'working\n' > "$state/res-w6.status" printf 'Working...\n' > "$pane" + # A resumed crew proves it is working through its own semantic busy-state + # record (bin/fm-busy-lib.sh), not through the pane's rendered footer. + fm_write_meta "$state/res-w6.meta" "window=$win" "worktree=$dir/wt" "kind=ship" "harness=pi" + local gen; gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" res-w6) + "$ROOT/bin/fm-busy-event.sh" apply "$state" res-w6 busy --gen "$gen" \ + --source pi-ext --event agent-start key=$(printf '%s' "res-w6" | tr ':/.' '___') echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key" PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$pane" \ @@ -480,19 +492,26 @@ test_housekeeping_herdr_persistent_stale_resolves_meta() { pass "persistent herdr stale resolves the target from metadata and escalates" } -test_housekeeping_herdr_idle_busy_footer_clears_stale() { - local dir state key - dir=$(make_supercase stale-herdr-idle-busy-footer) +# A herdr crew whose native agent.get reads idle (generation state) but whose +# own semantic busy-state record says busy is still working, so its stale +# marker clears without escalating. The record - not the pane's rendered +# footer - is what proves it. +test_housekeeping_herdr_idle_busy_record_clears_stale() { + local dir state key gen + dir=$(make_supercase stale-herdr-idle-busy-record) state="$dir/state" - fm_write_meta "$state/herdr-footer.meta" "window=default:w1:p4" "backend=herdr" + fm_write_meta "$state/herdr-footer.meta" "window=default:w1:p4" "backend=herdr" "harness=claude" printf 'working\n' > "$state/herdr-footer.status" + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" herdr-footer) + "$ROOT/bin/fm-busy-event.sh" apply "$state" herdr-footer busy --gen "$gen" \ + --source claude-hook --event user-prompt-submit key=$(printf '%s' "herdr-footer" | tr ':/.' '___') echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key" ( fm_backend_capture() { [ "$1" = herdr ] || fail "expected herdr capture backend, got $1" [ "$2" = "default:w1:p4" ] || fail "expected herdr window target, got $2" - printf 'esc to interrupt\n' + printf 'quiet\n' } fm_backend_busy_state() { [ "$1" = herdr ] || fail "expected herdr busy backend, got $1" @@ -503,8 +522,8 @@ test_housekeeping_herdr_idle_busy_footer_clears_stale() { [ "$(fm_backend_busy_state herdr default:w1:p4)" = idle ] || fail "herdr busy stub did not report idle" FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state" ) || fail "herdr idle busy-footer housekeeping failed" - [ ! -e "$state/.subsuper-stale-$key" ] || fail "idle+busy-footer herdr stale marker was not cleared" - [ ! -s "$state/.subsuper-escalations" ] || fail "idle+busy-footer herdr stale was escalated" + [ ! -e "$state/.subsuper-stale-$key" ] || fail "idle-native busy-record herdr stale marker was not cleared" + [ ! -s "$state/.subsuper-escalations" ] || fail "idle-native busy-record herdr stale was escalated" pass "herdr idle busy-footer stale clears through capture corroboration" } @@ -732,7 +751,6 @@ test_busy_guard_defers_when_supervisor_busy() { fakebin="$dir/fakebin" sent="$dir/sent.log"; : > "$sent" capture="$dir/pane.txt" - # pane shows a busy signature (firstmate mid-turn) printf 'esc to interrupt\n' > "$capture" escalate_add "$state" "done: PR 1" afk_enter "$state" @@ -1647,40 +1665,38 @@ test_discover_supervisor_target_herdr() { } test_pane_is_busy_herdr_native_busy_state() { + local dir + dir=$(make_supercase primary-herdr-busy) ( fm_backend_busy_state() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected busy_state args: $1 $2"; printf 'busy'; } fm_backend_capture() { fail "capture should not be consulted when busy_state is conclusive"; } - pane_is_busy "default:w1:p2" herdr || fail "pane_is_busy should report busy from herdr's native busy_state" + FM_STATE_OVERRIDE="$dir/state" FM_DAEMON_PRIMARY_HARNESS=claude pane_is_busy "default:w1:p2" herdr \ + || fail "pane_is_busy should report busy from herdr's native busy_state" ) || fail "herdr native-busy pane_is_busy subshell failed" pass "pane_is_busy: herdr native busy_state='busy' short-circuits without a capture fallback" } -test_pane_is_busy_herdr_falls_back_to_capture_regex() { +test_primary_busy_guard_is_harness_scoped() { ( fm_backend_busy_state() { printf 'unknown'; } - fm_backend_capture() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected capture args: $1 $2"; printf 'esc to interrupt\n'; } - pane_is_busy "default:w1:p2" herdr || fail "pane_is_busy should fall back to the regex-over-capture reader when busy_state is unknown" - ) || fail "herdr capture-fallback pane_is_busy subshell failed" - pass "pane_is_busy: herdr falls back to the shared regex-over-capture reader when native busy_state is unknown" -} - -test_pane_is_busy_herdr_idle_falls_back_to_capture_regex() { - ( - fm_backend_busy_state() { printf 'idle'; } - fm_backend_capture() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected capture args: $1 $2"; printf 'esc to interrupt\n'; } - pane_is_busy "default:w1:p2" herdr || fail "pane_is_busy should fall back to the regex-over-capture reader when busy_state is idle" - ) || fail "herdr idle capture-fallback pane_is_busy subshell failed" - pass "pane_is_busy: herdr corroborates native idle with the shared regex-over-capture reader" + fm_backend_capture() { printf 'esc interrupt\n'; } + if FM_DAEMON_PRIMARY_HARNESS=claude pane_is_busy "default:w1:p2" herdr; then + fail "OpenCode's rendered signature must not classify a Claude primary busy" + fi + FM_DAEMON_PRIMARY_HARNESS=opencode pane_is_busy "default:w1:p2" herdr \ + || fail "OpenCode's rendered signature should classify an OpenCode primary busy" + ) || fail "harness-scoped primary busy guard subshell failed" + pass "primary busy guard isolates rendered signatures by detected harness" } test_pane_is_busy_defaults_to_tmux_when_backend_omitted() { local dir fakebin capture dir=$(make_supercase busy-default-backend) fakebin="$dir/fakebin"; capture="$dir/pane.txt" - printf 'esc to interrupt\n' > "$capture" - PATH="$fakebin:$PATH" FM_FAKE_TMUX_CAPTURE="$capture" pane_is_busy "fakepane" \ + printf 'Ctrl+c:cancel\n' > "$capture" + PATH="$fakebin:$PATH" FM_FAKE_TMUX_CAPTURE="$capture" FM_STATE_OVERRIDE="$dir/state" FM_DAEMON_PRIMARY_HARNESS=grok pane_is_busy "fakepane" \ || fail "pane_is_busy with no backend arg should still default to tmux" - pass "pane_is_busy: omitted backend arg defaults to tmux (pre-existing callers unaffected)" + pass "pane_is_busy: omitted backend defaults to tmux for Grok's isolated fallback" } test_pane_input_pending_herdr_dispatch() { @@ -1709,8 +1725,7 @@ test_inject_msg_herdr_busy_guard_defers() { afk_enter "$state" ( fm_backend_target_exists() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected target_exists args: $1 $2"; return 0; } - fm_backend_busy_state() { printf 'busy'; } - fm_backend_capture() { fail "capture should not run when busy_state is conclusive"; } + pane_is_busy() { return 0; } fm_backend_composer_state() { fail "composer_state should not be consulted once the busy-guard already deferred"; } fm_backend_send_text_submit() { fail "send_text_submit should not run when the busy-guard defers"; } if FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="default:w1:p2" inject_msg "hello" "$state"; then @@ -1727,8 +1742,7 @@ test_inject_msg_herdr_composer_guard_defers() { afk_enter "$state" ( fm_backend_target_exists() { return 0; } - fm_backend_busy_state() { printf 'idle'; } - fm_backend_capture() { printf 'idle prompt\n'; } + pane_is_busy() { return 1; } fm_backend_composer_state() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected composer_state args: $1 $2"; printf 'pending'; } fm_backend_send_text_submit() { fail "send_text_submit should not run when the composer-guard defers"; } if FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="default:w1:p2" inject_msg "hello" "$state"; then @@ -1745,7 +1759,7 @@ test_inject_msg_herdr_pane_gone_defers() { afk_enter "$state" ( fm_backend_target_exists() { return 1; } - fm_backend_busy_state() { fail "busy_state should not be consulted once the pane-exists check already failed"; } + pane_is_busy() { fail "busy guard should not be consulted once the pane-exists check already failed"; } fm_backend_send_text_submit() { fail "send_text_submit should not run when the pane does not exist"; } if FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="default:w1:gone" inject_msg "hello" "$state"; then fail "inject_msg should defer when the herdr target does not exist" @@ -1761,8 +1775,7 @@ test_inject_msg_herdr_submits_through_backend_dispatch() { afk_enter "$state" ( fm_backend_target_exists() { return 0; } - fm_backend_busy_state() { printf 'idle'; } - fm_backend_capture() { printf 'idle prompt\n'; } + pane_is_busy() { return 1; } fm_backend_composer_state() { printf 'empty'; } fm_backend_send_text_submit() { [ "$1" = herdr ] && [ "$2" = "default:w1:p2" ] || fail "unexpected send_text_submit args: $1 $2" @@ -1787,8 +1800,7 @@ test_inject_msg_defers_on_dead_shell_unknown() { afk_enter "$state" ( fm_backend_target_exists() { return 0; } - fm_backend_busy_state() { printf 'idle'; } - fm_backend_capture() { printf '$ \n'; } + pane_is_busy() { return 1; } fm_backend_composer_state() { printf 'unknown'; } fm_backend_send_text_submit() { fail "send_text_submit must NOT run when the composer is a dead shell (unknown)"; } if FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="default:w1:p2" inject_msg "hello" "$state"; then @@ -1805,8 +1817,7 @@ test_inject_msg_defers_on_unrecognized_composer_state() { afk_enter "$state" ( fm_backend_target_exists() { return 0; } - fm_backend_busy_state() { printf 'idle'; } - fm_backend_capture() { printf 'idle prompt\n'; } + pane_is_busy() { return 1; } fm_backend_composer_state() { printf 'future-state'; } fm_backend_send_text_submit() { fail "send_text_submit must not run for an unrecognized composer state"; } if FM_SUPERVISOR_BACKEND=herdr FM_SUPERVISOR_TARGET="default:w1:p2" inject_msg "hello" "$state"; then @@ -1841,7 +1852,7 @@ test_housekeeping_paused_unpaused_cleared test_housekeeping_stale_marker_transitions_to_pause test_housekeeping_pause_marker_transitions_to_clear test_housekeeping_herdr_persistent_stale_resolves_meta -test_housekeeping_herdr_idle_busy_footer_clears_stale +test_housekeeping_herdr_idle_busy_record_clears_stale test_housekeeping_herdr_resumed_stale_cleared test_housekeeping_orca_persistent_stale_resolves_terminal test_escalate_batches_into_one_digest @@ -1906,8 +1917,7 @@ test_fm_send_exits_nonzero_on_unproven_submit test_discover_supervisor_backend_precedence test_discover_supervisor_target_herdr test_pane_is_busy_herdr_native_busy_state -test_pane_is_busy_herdr_falls_back_to_capture_regex -test_pane_is_busy_herdr_idle_falls_back_to_capture_regex +test_primary_busy_guard_is_harness_scoped test_pane_is_busy_defaults_to_tmux_when_backend_omitted test_pane_input_pending_herdr_dispatch test_inject_msg_herdr_busy_guard_defers diff --git a/tests/fm-fleet-snapshot-view.test.sh b/tests/fm-fleet-snapshot-view.test.sh index 56af41e11c1..f47c70f2fa8 100755 --- a/tests/fm-fleet-snapshot-view.test.sh +++ b/tests/fm-fleet-snapshot-view.test.sh @@ -62,8 +62,15 @@ make_home() { # <name> printf '%s\n' "$home" } +record_claude_idle() { # <state-dir> <id> + local state=$1 id=$2 gen + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" "$id") + "$ROOT/bin/fm-busy-event.sh" apply "$state" "$id" idle --gen "$gen" \ + --source claude-hook --event stop +} + write_fixture() { # <home> - local home=$1 + local home=$1 fixture_gen mkdir -p "$home/projects/alpha-worktree" "$home/projects/scout-worktree" "$home/secondmate-home" cat > "$home/data/backlog.md" <<EOF ## In flight @@ -84,12 +91,18 @@ EOF "window=firstmate:fm-ship-task" \ "worktree=$home/projects/alpha-worktree" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=ship" \ "yolo=off" \ "pr=https://github.com/kunchenguid/firstmate/pull/9" printf 'needs-decision: choose an API shape\n' > "$home/state/ship-task.status" + # A working ship task proves it through its own semantic busy-state record + # (bin/fm-busy-lib.sh), which is what the snapshot's current-state read + # consults; rendered pane text is no longer a state source. + fixture_gen=$("$ROOT/bin/fm-busy-event.sh" arm "$home/state" ship-task) + "$ROOT/bin/fm-busy-event.sh" apply "$home/state" ship-task busy --gen "$fixture_gen" \ + --source claude-hook --event user-prompt-submit fm_write_meta "$home/state/scout-task.meta" \ "window=firstmate:fm-scout-task" \ "worktree=$home/projects/scout-worktree" \ @@ -343,7 +356,7 @@ EOF } test_event_hints_follow_reconciled_current_state() { - local home fakebin out + local home fakebin out hint_gen home=$(make_home event-hints) mkdir -p \ "$home/projects/active-decision" \ @@ -354,33 +367,41 @@ test_event_hints_follow_reconciled_current_state() { "window=firstmate:fm-active-decision" \ "worktree=$home/projects/active-decision" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=ship" + record_claude_idle "$home/state" active-decision printf 'needs-decision: choose an API shape\n' > "$home/state/active-decision.status" fm_write_meta "$home/state/active-blocked.meta" \ "window=firstmate:fm-active-blocked" \ "worktree=$home/projects/active-blocked" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=ship" + record_claude_idle "$home/state" active-blocked printf 'blocked: waiting on access\n' > "$home/state/active-blocked.status" fm_write_meta "$home/state/stale-decision.meta" \ "window=firstmate:fm-stale-decision-ship-task" \ "worktree=$home/projects/stale-decision" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=ship" + hint_gen=$("$ROOT/bin/fm-busy-event.sh" arm "$home/state" stale-decision) + "$ROOT/bin/fm-busy-event.sh" apply "$home/state" stale-decision busy --gen "$hint_gen" \ + --source claude-hook --event user-prompt-submit printf 'needs-decision: already answered\n' > "$home/state/stale-decision.status" fm_write_meta "$home/state/stale-blocked.meta" \ "window=firstmate:fm-stale-blocked-ship-task" \ "worktree=$home/projects/stale-blocked" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=ship" \ "mode=ship" + hint_gen=$("$ROOT/bin/fm-busy-event.sh" arm "$home/state" stale-blocked) + "$ROOT/bin/fm-busy-event.sh" apply "$home/state" stale-blocked busy --gen "$hint_gen" \ + --source claude-hook --event user-prompt-submit printf 'blocked: old failure\n' > "$home/state/stale-blocked.status" fakebin=$(make_fakebin "$home") out=$(PATH="$fakebin:$PATH" FM_HOME="$home" "$SNAPSHOT" --json) @@ -447,9 +468,10 @@ EOF "window=firstmate:fm-bold-task" \ "worktree=$projects/bold-worktree" \ "project=alpha" \ - "harness=codex" \ + "harness=claude" \ "kind=scout" \ "mode=scout" + record_claude_idle "$home/state" bold-task printf 'done: report ready\n' > "$home/state/bold-task.status" fakebin=$(make_fakebin "$home") out=$(PATH="$fakebin:$PATH" FM_HOME="$home" FM_DATA_OVERRIDE="$data" FM_PROJECTS_OVERRIDE="$projects" "$SNAPSHOT" --json) @@ -709,9 +731,10 @@ test_completed_scout_report_is_pointer_not_pending() { "window=firstmate:fm-lavish-103" \ "worktree=$home/projects/scout-wt" \ "project=firstmate" \ - "harness=codex" \ + "harness=claude" \ "kind=scout" \ "mode=scout" + record_claude_idle "$home/state" lavish-103 # Stale needs-decision, then the scout finished (done). No keyed resolution. printf 'needs-decision: adopt approach A or B for Lavish issue 103\n' > "$home/state/lavish-103.status" printf 'done: report ready at data/lavish-103/report.md\n' >> "$home/state/lavish-103.status" @@ -740,9 +763,10 @@ test_parked_scout_decision_stays_pending() { "window=firstmate:fm-parked-scout" \ "worktree=$home/projects/scout-wt2" \ "project=firstmate" \ - "harness=codex" \ + "harness=claude" \ "kind=scout" \ "mode=scout" + record_claude_idle "$home/state" parked-scout printf 'needs-decision [key=q1]: adopt approach A or B\n' > "$home/state/parked-scout.status" fakebin=$(make_fakebin "$home") out=$(PATH="$fakebin:$PATH" FM_HOME="$home" "$SNAPSHOT" --json) diff --git a/tests/fm-gitignore-config.test.sh b/tests/fm-gitignore-config.test.sh index d64e362880a..5b864dd6466 100755 --- a/tests/fm-gitignore-config.test.sh +++ b/tests/fm-gitignore-config.test.sh @@ -18,22 +18,30 @@ pass() { printf 'ok - %s\n' "$1" } +random_leaf() { + printf '%s-%s' "$1" "$$-$RANDOM-$RANDOM" +} + test_config_dir_ignored_as_category() { - local sample - for sample in config/anything config/nested/dir/file config/some-new-key.admin; do + local direct nested sample + direct="$(random_leaf config/unlisted-key)" + nested="config/$(random_leaf nested-dir)/$(random_leaf deep-file)" + for sample in "$direct" "$nested" config/some-new-key.admin; do git -C "$ROOT" check-ignore -q "$sample" \ || fail "git does not ignore $sample (config/ must be ignored as a directory)" done - pass "config/ is ignored as a directory, covering unlisted paths" + pass "config/ is ignored as a directory, covering unlisted and nested paths" } -test_config_not_ignored_by_name_by_name_list() { - # Regression guard: .gitignore must not go back to enumerating config/ entries - # by exact filename, since that reintroduces the same silent-drift failure. - grep -qE '^config/[^/]+$' "$ROOT/.gitignore" \ - && fail ".gitignore lists config/ entries by exact filename instead of ignoring the directory" - pass "no name-by-name config/ entries remain in .gitignore" +test_unrelated_path_stays_visible() { + # Control: a path outside config/ must remain visible to Git, so the + # coverage above is proven by contrast rather than an always-ignoring rule. + local sibling + sibling="$(random_leaf not-config)" + git -C "$ROOT" check-ignore -q "$sibling" \ + && fail "git unexpectedly ignores $sibling (outside config/)" + pass "an unrelated path outside config/ remains visible to git" } test_config_dir_ignored_as_category -test_config_not_ignored_by_name_by_name_list +test_unrelated_path_stays_visible diff --git a/tests/fm-gotmp.test.sh b/tests/fm-gotmp.test.sh index 2bd2feeed2f..549afd2fcb2 100755 --- a/tests/fm-gotmp.test.sh +++ b/tests/fm-gotmp.test.sh @@ -67,6 +67,13 @@ make_fake_root() { # fm-delivery-lib.sh: teardown sources the delivery gate; the nonexistent # worktree keeps the gate itself skipped, exactly like the dirty/treehouse blocks. ln -s "$ROOT/bin/fm-delivery-lib.sh" "$fake/bin/fm-delivery-lib.sh" + # fm-public-followup-lib.sh (and the fm-x-lib.sh it sources): teardown sources + # it for the relay-activation gate on the promised-public-reply check. Neither + # does anything in this fixture, which has no .env, but both are real siblings + # teardown now requires. + ln -s "$ROOT/bin/fm-public-followup-lib.sh" "$fake/bin/fm-public-followup-lib.sh" + ln -s "$ROOT/bin/fm-x-lib.sh" "$fake/bin/fm-x-lib.sh" + ln -s "$ROOT/bin/fm-secondmate-registry-lib.sh" "$fake/bin/fm-secondmate-registry-lib.sh" # fm-guard.sh: stub (teardown calls it with `|| true`). cat > "$fake/bin/fm-guard.sh" <<'SH' #!/usr/bin/env bash @@ -136,6 +143,13 @@ test_teardown_skips_gracefully_without_tasktmp() { # fm-delivery-lib.sh: teardown sources the delivery gate; the nonexistent # worktree keeps the gate itself skipped, exactly like the dirty/treehouse blocks. ln -s "$ROOT/bin/fm-delivery-lib.sh" "$fake/bin/fm-delivery-lib.sh" + # fm-public-followup-lib.sh (and the fm-x-lib.sh it sources): teardown sources + # it for the relay-activation gate on the promised-public-reply check. Neither + # does anything in this fixture, which has no .env, but both are real siblings + # teardown now requires. + ln -s "$ROOT/bin/fm-public-followup-lib.sh" "$fake/bin/fm-public-followup-lib.sh" + ln -s "$ROOT/bin/fm-x-lib.sh" "$fake/bin/fm-x-lib.sh" + ln -s "$ROOT/bin/fm-secondmate-registry-lib.sh" "$fake/bin/fm-secondmate-registry-lib.sh" cat > "$fake/bin/fm-guard.sh" <<'SH' #!/usr/bin/env bash exit 0 diff --git a/tests/fm-herdr-session-cleanup-e2e.test.sh b/tests/fm-herdr-session-cleanup-e2e.test.sh index 7a4a49aa008..e45c1018342 100755 --- a/tests/fm-herdr-session-cleanup-e2e.test.sh +++ b/tests/fm-herdr-session-cleanup-e2e.test.sh @@ -64,7 +64,7 @@ lab() { env PATH="$HERDR_ORIGINAL_PATH" "$HERDR_LAB_HELPER" run "$HERDR_LAB_SESS production_process_proof() { FM_HOME="$HOME_DIR" FM_BACKEND=herdr HERDR_SESSION="$HERDR_LAB_SESSION" \ FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY=1 PATH="$FAKEBIN:$HERDR_ORIGINAL_PATH" \ - bash -c '. "$1"; fm_herdr_cleanup_process_is_idle_shell "$2" "$3"' \ + bash -c '. "$1"; fm_backend_herdr_pane_idle_shell_pid "$2" "$3" >/dev/null' \ _ "$ROOT/bin/fm-herdr-session-cleanup.sh" "$HERDR_LAB_SESSION" "$PANE" } focus_snapshot() { diff --git a/tests/fm-herdr-session-cleanup.test.sh b/tests/fm-herdr-session-cleanup.test.sh index f4c1df153b4..99cf4b49a1c 100755 --- a/tests/fm-herdr-session-cleanup.test.sh +++ b/tests/fm-herdr-session-cleanup.test.sh @@ -25,12 +25,32 @@ export FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY=1 . "$ROOT/bin/fm-herdr-session-cleanup.sh" unset FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY -LINUX_PROCESS_INFO='{"result":{"process_info":{"foreground_processes":[{"argv":["/bin/sh"],"name":"sh","pid":67}]}}}' -[ "$(fm_herdr_cleanup_process_argv0 "$LINUX_PROCESS_INFO")" = /bin/sh ] \ - || fail "Linux Herdr process argv array was not accepted" -if fm_herdr_cleanup_process_argv0 \ - '{"result":{"process_info":{"foreground_processes":[{"argv":[67],"name":"sh","pid":67}]}}}' \ - >/dev/null 2>&1; then +# The idle-shell proof now lives in the backend as +# fm_backend_herdr_pane_idle_shell_pid; prove it still reads Linux argv +# arrays (no argv0 field) and rejects malformed executable identities. +FAKE_PS="$TMP_ROOT/fake-ps" +cat > "$FAKE_PS" <<'SH' +#!/usr/bin/env bash +case "$*" in + "-axo pid=,ppid=") printf '1 0\n67 1\n' ;; + "-p 67 -o stat=") printf 'Ss\n' ;; + *) exit 1 ;; +esac +SH +chmod +x "$FAKE_PS" +LINUX_PROCESS_INFO='{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p1","shell_pid":67,"foreground_process_group_id":67,"foreground_processes":[{"argv":["/bin/sh"],"name":"sh","pid":67}]}}}' +argv_pid=$( + # shellcheck disable=SC2329 # invoked indirectly by the idle-shell proof. + fm_backend_herdr_cli() { printf '%s\n' "$LINUX_PROCESS_INFO"; } + FM_HERDR_PS_BIN="$FAKE_PS" fm_backend_herdr_pane_idle_shell_pid test w2:p1 +) || fail "Linux Herdr process argv array was not accepted" +[ "$argv_pid" = 67 ] || fail "idle-shell proof printed the wrong shell pid: $argv_pid" +if ( + # shellcheck disable=SC2329 # invoked indirectly by the idle-shell proof. + fm_backend_herdr_cli() { printf '%s\n' '{"result":{"type":"pane_process_info","process_info":{"pane_id":"w2:p1","shell_pid":67,"foreground_process_group_id":67,"foreground_processes":[{"argv":[67],"name":"sh","pid":67}]}}}'; } + FM_HERDR_PS_BIN="$FAKE_PS" FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=1 \ + fm_backend_herdr_pane_idle_shell_pid test w2:p1 +) >/dev/null 2>&1; then fail "non-string Herdr process argv was accepted" fi pass "process proof reads Linux Herdr argv arrays and rejects malformed executable identities" @@ -54,7 +74,7 @@ fm_lock_try_acquire() { mkdir "$1" 2>/dev/null } fm_lock_release() { rm -rf -- "$1"; } -fm_herdr_cleanup_process_is_idle_shell() { [ ! -e "$FIXTURE_DIR/process-unsafe" ]; } +fm_backend_herdr_pane_idle_shell_pid() { [ ! -e "$FIXTURE_DIR/process-unsafe" ] && printf '67\n'; } fm_backend_herdr_projection_focus_snapshot() { [ ! -e "$FIXTURE_DIR/focus-unreadable" ] || return 1 printf 'w1\t%s' "$(cat "$FIXTURE_DIR/active-tab")" diff --git a/tests/fm-kimi-harness.test.sh b/tests/fm-kimi-harness.test.sh index 0d68210be46..7c5175c40fa 100755 --- a/tests/fm-kimi-harness.test.sh +++ b/tests/fm-kimi-harness.test.sh @@ -613,7 +613,7 @@ test_kimi_busy_signature_is_scoped_to_spinner_lines() { pass "busy detection: real Kimi moon-plus-middot captures require its harness while idle labels stay idle" } -test_watcher_scopes_moon_spinner_to_recorded_kimi_task() ( +test_watcher_never_classifies_kimi_from_its_spinner() ( local state="$TMP_ROOT/watch-state" busy_capture=' 🌑 · Tip: ask Kimi to schedule tasks, e.g. "remind me at 5pm"' mkdir -p "$state" printf 'window=fake\nharness=kimi\n' > "$state/kimi-watch.meta" @@ -625,26 +625,26 @@ test_watcher_scopes_moon_spinner_to_recorded_kimi_task() ( . "$ROOT/bin/fm-watch.sh" # shellcheck disable=SC2329 # Runtime override called by the sourced watcher. fm_backend_busy_state() { printf 'unknown'; } - window_is_busy fake "$busy_capture" \ - || fail "fm-watch did not recognize the real Kimi spinner-line shape" - printf 'window=fake\nharness=codex\n' > "$state/kimi-watch.meta" + # Standalone Kimi has no verified semantic busy source, so it classifies + # unknown - and unknown is never working. Its moon-phase spinner is + # deliberately not a state source: the approved redesign forbids inventing a + # Kimi UI signature, and that glyph set is locale- and emoji-font-sensitive. if window_is_busy fake "$busy_capture"; then - fail "fm-watch applied Kimi's real spinner signature to a recorded Codex task" - fi - printf 'window=fake\nharness=kimi\n' > "$state/kimi-watch.meta" - if window_is_busy fake 'ordinary response ending with 🌕'; then - fail "fm-watch treated an ordinary Kimi moon as a spinner line" - fi - if window_is_busy fake '🌕 Full moon details'; then - fail "fm-watch treated moon-led Kimi output without the middot separator as busy" + fail "fm-watch classified a Kimi task busy from its spinner instead of unknown" fi - if window_is_busy fake 'auto K2.7 Coding thinking /some/path'; then - fail "fm-watch treated Kimi's idle thinking-effort status label as busy" + [ "$(fm_busy_classify tmux fake kimi kimi-watch "$state" "$busy_capture")" = "unknown kimi-unverified" ] \ + || fail "a Kimi task must classify unknown kimi-unverified" + printf 'window=fake\nharness=codex\n' > "$state/kimi-watch.meta" + if window_is_busy fake "$busy_capture"; then + fail "fm-watch applied Kimi's spinner to a recorded Codex task" fi - if window_is_busy fake 'Ctrl+c:cancel'; then - fail "fm-watch let Grok's exact busy token classify a recorded Kimi task busy" + printf 'window=fake\nharness=grok\n' > "$state/kimi-watch.meta" + if window_is_busy fake "$busy_capture"; then + fail "Kimi's spinner classified a recorded Grok task through its isolated fallback" fi - pass "fm-watch: Kimi spinner matching is metadata-scoped and ignores Grok's busy token" + window_is_busy fake 'Ctrl+c:cancel' \ + || fail "Grok's own verified token must still classify a recorded Grok task busy" + pass "fm-watch classifies Kimi as unknown rather than from its spinner, and Grok's fallback stays isolated" ) test_kimi_bordered_prompt_needs_no_override() { @@ -673,5 +673,5 @@ test_kimi_readiness_gate_precedes_pointer test_kimi_detection_uses_ancestry_after_markers test_kimi_session_lock_identity test_kimi_busy_signature_is_scoped_to_spinner_lines -test_watcher_scopes_moon_spinner_to_recorded_kimi_task +test_watcher_never_classifies_kimi_from_its_spinner test_kimi_bordered_prompt_needs_no_override diff --git a/tests/fm-pi-primary-live-e2e.test.sh b/tests/fm-pi-primary-live-e2e.test.sh index 30b6942606e..aba84459cee 100755 --- a/tests/fm-pi-primary-live-e2e.test.sh +++ b/tests/fm-pi-primary-live-e2e.test.sh @@ -254,6 +254,7 @@ cp "$ROOT/.pi/extensions/fm-primary-pi-watch.ts" "$PROJECT/.pi/extensions/fm-pri cp "$ROOT/.pi/extensions/lib/fm-calm-assistant-layout.ts" "$PROJECT/.pi/extensions/lib/fm-calm-assistant-layout.ts" cp "$ROOT/.pi/extensions/lib/fm-calm-operational-user-layout.ts" "$PROJECT/.pi/extensions/lib/fm-calm-operational-user-layout.ts" cp "$ROOT/.pi/extensions/lib/fm-calm-visibility.ts" "$PROJECT/.pi/extensions/lib/fm-calm-visibility.ts" +cp "$ROOT/.pi/extensions/lib/fm-calm-working-ship.ts" "$PROJECT/.pi/extensions/lib/fm-calm-working-ship.ts" cp "$ROOT/.pi/extensions/lib/fm-operational-input.ts" "$PROJECT/.pi/extensions/lib/fm-operational-input.ts" cp "$ROOT/.pi/extensions/fm-primary-turnend-guard.ts" "$PROJECT/.pi/extensions/fm-primary-turnend-guard.ts" cp "$ROOT/bin/fm-watch-arm.sh" "$PROJECT/bin/fm-watch-arm.sh" @@ -284,17 +285,21 @@ send_prompt "Reply exactly CALM_LIVE_WORKING_VISIBLE" i=0 while [ "$i" -lt 240 ]; do pane=$(capture) - if printf '%s\n' "$pane" | grep -Fq "Working..."; then + if printf '%s\n' "$pane" | grep -Fq '\__/'; then break fi sleep 0.05 i=$((i + 1)) done +printf '%s\n' "$pane" | grep -Fq '\__/' \ + || fail "Calm did not show the working ship on the credentialed provider path" printf '%s\n' "$pane" | grep -Fq "Working..." \ - || fail "Calm hid Pi's built-in Working row on the credentialed provider path" + && fail "Calm left Pi's stock working row visible on the credentialed provider path" wait_for_exact_line "CALM_LIVE_WORKING_VISIBLE" 120 \ - || fail "Pi did not settle the Calm Working-row provider probe" + || fail "Pi did not settle the Calm working-ship provider probe" pane=$(capture) +printf '%s\n' "$pane" | grep -Fq '\__/' \ + && fail "Calm left the working ship on screen after the run settled" printf '%s\n' "$pane" | grep -Fq "calm transcript" \ && fail "Calm added a persistent Calm status row on the credentialed provider path" send_prompt "/calm" @@ -346,4 +351,4 @@ wait_for_text "PI_EXIT=0" 60 || fail "Pi did not exit cleanly" wait_pid_dead "$watcher_pid" || fail "watcher child survived clean Pi exit" wait_pid_dead "$arm_pid" || fail "arm child survived clean Pi exit" -printf 'ok - Pi %s live E2E covered native Calm Working visibility, Ahoy boundaries, visible escalation relay, triggered handling, drain, legacy transcripts, near misses, and watcher continuity\n' "$PI_VERSION" +printf 'ok - Pi %s live E2E covered native Calm Working visibility and working ship, Ahoy first/later messages and boundaries, visible escalation relay, triggered handling, drain, legacy transcripts, near misses, and watcher continuity\n' "$PI_VERSION" diff --git a/tests/fm-pi-primary-types.test.sh b/tests/fm-pi-primary-types.test.sh index 3ff81f63ef8..68d20afd498 100755 --- a/tests/fm-pi-primary-types.test.sh +++ b/tests/fm-pi-primary-types.test.sh @@ -32,6 +32,7 @@ cp "$ROOT/.pi/extensions/fm-primary-turnend-guard.ts" "$TMP_ROOT/fm-primary-turn cp "$ROOT/.pi/extensions/lib/fm-calm-assistant-layout.ts" "$TMP_ROOT/lib/fm-calm-assistant-layout.ts" cp "$ROOT/.pi/extensions/lib/fm-calm-operational-user-layout.ts" "$TMP_ROOT/lib/fm-calm-operational-user-layout.ts" cp "$ROOT/.pi/extensions/lib/fm-calm-visibility.ts" "$TMP_ROOT/lib/fm-calm-visibility.ts" +cp "$ROOT/.pi/extensions/lib/fm-calm-working-ship.ts" "$TMP_ROOT/lib/fm-calm-working-ship.ts" cp "$ROOT/.pi/extensions/lib/fm-operational-input.ts" "$TMP_ROOT/lib/fm-operational-input.ts" ln -s "$PI_PACKAGE_DIR" "$TMP_ROOT/node_modules/@earendil-works/pi-coding-agent" ln -s "$PI_PACKAGE_DIR/node_modules/@earendil-works/pi-tui" "$TMP_ROOT/node_modules/@earendil-works/pi-tui" diff --git a/tests/fm-public-followup.test.sh b/tests/fm-public-followup.test.sh new file mode 100755 index 00000000000..4c0571c466b --- /dev/null +++ b/tests/fm-public-followup.test.sh @@ -0,0 +1,1042 @@ +#!/usr/bin/env bash +# End-to-end and regression tests for the deterministic public-followup consumer. +# +# The failure this suite pins: firstmate promises a public final reply in an X or +# Discord thread, routes the work out, and then the session compacts or restarts. +# Nothing in memory survives. The promise is only kept if a terminal work result +# reconciles the typed obligation from DISK and the final reply lands in the +# ORIGINAL thread exactly once. +# +# Everything here is hermetic: the relay is a fakebin `curl`, so no port, no +# server, and no public post. tasks-axi and jq are the real tools, because +# tasks-axi owns the obligation state machine and stubbing it would test nothing. +set -u + +# shellcheck source=tests/lib.sh +# shellcheck disable=SC1091 +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +PF="$ROOT/bin/fm-public-followup.sh" +EMIT="$ROOT/bin/fm-public-followup-emit.sh" +POLL="$ROOT/bin/fm-x-poll.sh" +TEARDOWN="$ROOT/bin/fm-teardown.sh" +SESSION_START="$ROOT/bin/fm-session-start.sh" +TMP_ROOT=$(fm_test_tmproot fm-public-followup) + +command -v jq >/dev/null 2>&1 || { echo "skip: jq not found"; exit 0; } +command -v tasks-axi >/dev/null 2>&1 || { echo "skip: tasks-axi not found"; exit 0; } + +# A fakebin `curl` standing in for the relay. It logs every call so a test can +# prove exactly how many public posts happened, and honours FAKE_FOLLOWUP_CODE so +# a transport failure can be simulated. +make_fake_curl() { # <home> + local fakebin + fakebin=$(fm_fakebin "$1") + cat > "$fakebin/curl" <<'SH' +#!/usr/bin/env bash +ofile="" url="" data="" +while [ $# -gt 0 ]; do + case "$1" in + -o) ofile=$2; shift 2 ;; + --data-binary) + case "$2" in + @-) data=$(cat) ;; + @*) data=$(cat -- "${2#@}") ;; + *) data=$2 ;; + esac + shift 2 + ;; + -H|-m|-w|-X) shift 2 ;; + -s) shift ;; + http://*|https://*) url=$1; shift ;; + *) shift ;; + esac +done +if [ -n "${FAKE_CURL_LOG:-}" ]; then + { echo "url=$url"; echo "data=$data"; } >> "$FAKE_CURL_LOG" +fi +case "$url" in + */connector/followup) printf '%s' "${FAKE_FOLLOWUP_CODE:-200}" ;; + */connector/answer) printf '200' ;; + */connector/request-context) + [ -n "$ofile" ] && printf '%s' "${FAKE_REQCTX_BODY:-}" > "$ofile" + printf '%s' "${FAKE_REQCTX_CODE:-404}" + ;; + */connector/poll) printf '204' ;; + *) printf '204' ;; +esac +exit 0 +SH + chmod +x "$fakebin/curl" + printf '%s\n' "$fakebin" +} + +# make_home <name> [relay-on|relay-off]: a firstmate home with its own backlog. +# relay-off omits .env entirely, which is exactly what a home that never opted +# into the myfirstmate relay looks like. +make_home() { # <name> [relay-on|relay-off] + local home="$TMP_ROOT/$1" relay=${2:-relay-on} + mkdir -p "$home/data" "$home/state" "$home/config" "$home/projects" + cp "$ROOT/.tasks.toml" "$home/.tasks.toml" + cat > "$home/data/backlog.md" <<'EOF' +## In flight + +## Queued + +## Done +EOF + [ "$relay" = relay-off ] || printf 'FMX_PAIRING_TOKEN=test-token\n' > "$home/.env" + make_fake_curl "$home" >/dev/null + fm_fake_exit0 "$home/fakebin" tmux treehouse no-mistakes gh gh-axi + printf '%s\n' "$home" +} + +run_pf() { # <home> <args...> + local home=$1 + shift + PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FAKE_CURL_LOG="${FAKE_CURL_LOG:-}" \ + FAKE_FOLLOWUP_CODE="${FAKE_FOLLOWUP_CODE:-200}" "$PF" "$@" +} + +tasks_in() { # <home> <tasks-axi args...> + local home=$1 + shift + (cd "$home" && tasks-axi "$@") +} + +# seed_commitment <home> <obligation> <request> <platform> <work-home> <work-id> +# Simulates the intake half that already works today: the relay mention arrives, +# the typed obligation is created with its opaque thread binding, the work is +# bound, and the private request context is retained. +seed_commitment() { + local home=$1 obligation=$2 request=$3 platform=$4 work_home=$5 work_id=$6 + jq -n --arg r "$request" --arg p "$platform" \ + '{request_id:$r, platform:$p, + context_binding:{version:"ctx1", value:("ctx1_" + $r)}, + public_safe_summary:"fix worker placement when two spaces share a name", + received_at:"2026-07-30T10:00:00Z", + followup_expires_at:"2026-08-06T10:00:00Z", + reservation_expires_at:"2026-08-06T10:00:00Z"}' > "$home/request.json" + jq -n '{type:"pr-merged", project:"firstmate", + required_deliverables:["pr_url"], completion_policy:"all-required"}' \ + > "$home/expected.json" + jq -n --arg h "$work_home" --arg w "$work_id" \ + '{relation_id:"rel-code", work_ref:{home_id:$h, task_id:$w}, + role:"fulfills", required:true, generation:1}' > "$home/relation.json" + + tasks_in "$home" public-followup add "$obligation" \ + --request-context-file "$home/request.json" --purpose promised-final \ + --expected-final-file "$home/expected.json" --expires-at 2026-10-01T00:00:00Z >/dev/null \ + || fail "could not create the public commitment" + tasks_in "$home" public-followup bind-work "$obligation" \ + --relation-file "$home/relation.json" >/dev/null \ + || fail "could not bind work to the public commitment" + + # The mention payload and the durable per-request context, exactly as the relay + # poll records them at intake. + mkdir -p "$home/state/x-inbox" + jq -n --arg r "$request" --arg p "$platform" \ + '{request_id:$r, platform:$p, text:"please fix worker placement"}' \ + > "$home/state/x-inbox/$request.json" + chmod 700 "$home/state/x-inbox" + chmod 600 "$home/state/x-inbox/$request.json" + FM_HOME="$home" bash -c \ + ". '$ROOT/bin/fm-x-lib.sh'; fmx_context_registry_set '$home/state' '$request' '$platform' 1900" \ + || fail "could not retain the private request context" + + run_pf "$home" register "$obligation" --relation rel-code \ + --work-home "$work_home" --work-id "$work_id" --generation 1 >/dev/null \ + || fail "could not register the public commitment" +} + +emit_terminal() { # <child-run-dir> <owning-home> <obligation> <work-home> <work-id> [pr-url] [outcome] + local owning=$2 obligation=$3 work_home=$4 work_id=$5 + local pr=${6:-https://github.com/example/repo/pull/7} outcome=${7:-pr-merged} + "$EMIT" --home "$owning" --obligation "$obligation" --relation rel-code \ + --source-home "$work_home" --work-id "$work_id" --generation 1 \ + --outcome "$outcome" --deliverable "pr_url=$pr" \ + --outcome-text 'Fixed: workers now land in the launching workspace even when two spaces share a name.' +} + +delivery_state() { # <home> <obligation> + tasks_in "$1" public-followup list --json 2>/dev/null \ + | jq -r --arg id "$2" '(.public_followups // []) + | map(select(.id == $id)) | .[0].public_followup.delivery.state // "absent"' +} + +task_state() { # <home> <obligation> + tasks_in "$1" public-followup list --json 2>/dev/null \ + | jq -r --arg id "$2" '(.public_followups // []) + | map(select(.id == $id)) | .[0].state // "absent"' +} + +followup_posts() { # <log> + local n + n=$(grep -c 'connector/followup' "$1" 2>/dev/null) || n=0 + printf '%s' "${n:-0}" +} + +# expect_failure <label> <command...>: run <command>, require a non-zero exit, and +# leave its combined output in EXPECT_OUT for the assertions that follow. Keeps +# refusal tests readable without toggling errexit around every case. +EXPECT_OUT= +expect_failure() { + local label=$1 + shift + if EXPECT_OUT=$("$@" 2>&1); then + fail "$label (unexpectedly succeeded)"$'\n'"--- output ---"$'\n'"$EXPECT_OUT" + fi +} + +# --- 0. bounded, single-line, character-safe outcome text ----------------------- + +# The outcome sentence becomes a public reply, so bounding it must not mangle +# non-ASCII characters, and control characters must never survive into the typed +# event or the thread. +test_outcome_text_is_bounded_without_corrupting_characters() { + local home event text long + home=$(make_home outcome-text) + seed_commitment "$home" pf-text req-text discord main work-text + + "$EMIT" --home "$home" --obligation pf-text --relation rel-code \ + --source-home main --work-id work-text --generation 1 --outcome pr-merged \ + --deliverable pr_url=https://github.com/example/repo/pull/3 \ + --outcome-text "$(printf 'Shipped\tthe caf\xc3\xa9 fix \xe2\x80\x94 \xf0\x9f\x9a\xa2\nsecond line')" >/dev/null \ + || fail "emit failed for non-ASCII outcome text" + event=$(find "$home/state/public-followup/events" -name '*.json' | head -1) + text=$(jq -r '.public_safe_outcome' "$event") \ + || fail "the typed event must remain valid JSON with non-ASCII text" + [ "$text" = 'Shipped the café fix — 🚢 second line' ] \ + || fail "non-ASCII outcome text was corrupted or not collapsed: '$text'" + + # A very long sentence is capped by codepoint, so the JSON stays valid. + rm -f "$event" + long=$(python3 -c 'print("é" * 5000, end="")') + "$EMIT" --home "$home" --obligation pf-text --relation rel-code \ + --source-home main --work-id work-text --generation 1 --outcome pr-merged \ + --deliverable pr_url=https://github.com/example/repo/pull/4 \ + --outcome-text "$long" >/dev/null \ + || fail "emit failed for an over-long outcome text" + event=$(find "$home/state/public-followup/events" -name '*.json' | head -1) + text=$(jq -r '.public_safe_outcome' "$event") \ + || fail "an over-long outcome must still produce valid JSON" + [ "${#text}" -le 600 ] || fail "the outcome text was not bounded, got ${#text} characters" + case "$text" in + *[!é]*) fail "codepoint bounding split a multi-byte character" ;; + esac + pass "outcome text is collapsed to one line, bounded by codepoint, and never corrupts characters" +} + +# --- 1. the restart end-to-end ------------------------------------------------- + +# The whole reported failure, start to finish, with no conversation memory +# anywhere: a Discord request becomes a typed commitment, a secondmate child +# lands the work and reports a TYPED terminal result, the session ends, and a +# cold reconciliation from disk delivers exactly one final reply into the +# original thread and closes the obligation. +test_restart_e2e_delivers_exactly_once() { + local home child log out posts receipt + home=$(make_home restart-e2e) + child=$(make_home restart-child relay-off) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-restart req-restart discord secondmate:fmdev work-code-q1 + printf '%s\n' fmdev > "$child/.fm-secondmate-home" + fm_write_meta "$home/state/fmdev.meta" "kind=secondmate" "home=$child" + fm_write_meta "$child/state/work-code-q1.meta" \ + "x_request=req-restart" "x_request_ts=1700000000" "x_followups=1" + + # The reported failure, reproduced: with the work bound but no reconciled + # terminal result, the commitment is stranded at pending-work and nothing can + # be delivered - which is exactly how a promised final reply went unsent. + [ "$(delivery_state "$home" pf-restart)" = pending-work ] \ + || fail "a freshly bound commitment must sit at pending-work" + FAKE_CURL_LOG="$log" expect_failure "a commitment still waiting on its work must not be deliverable" \ + run_pf "$home" deliver pf-restart + assert_contains "$EXPECT_OUT" "still waiting on its bound work" \ + "the stranded state must be reported, not silently skipped" + [ "$(followup_posts "$log")" -eq 0 ] || fail "the stranded state must post nothing" + + # The child home reports its terminal result as typed data. This is the step + # whose absence left the obligation stranded at pending-work. + emit_terminal "$home" "$home" pf-restart secondmate:fmdev work-code-q1 >/dev/null \ + || fail "the child could not report its typed terminal result" + + # Simulate compaction/restart: nothing but disk survives, and the drained inbox + # is gone. The durable private request context is what keeps the thread binding + # resolvable. + rm -f "$home/state/x-inbox/req-restart.json" + + out=$(FAKE_CURL_LOG="$log" run_pf "$home" consume) \ + || fail "cold reconciliation failed" + assert_contains "$out" "ready pf-restart req-restart discord" \ + "reconciliation must report the commitment as delivery-ready" + [ "$(delivery_state "$home" pf-restart)" = ready ] \ + || fail "the typed terminal result must move the commitment to ready" + [ "$(followup_posts "$log")" -eq 0 ] \ + || fail "reconciliation must not post anything by itself" + + out=$(FAKE_CURL_LOG="$log" run_pf "$home" deliver pf-restart) \ + || fail "delivery failed" + assert_contains "$out" "delivered pf-restart request=req-restart platform=discord" \ + "delivery must report the original request binding" + + posts=$(followup_posts "$log") + [ "$posts" -eq 1 ] || fail "expected exactly one public reply, got $posts" + assert_grep 'connector/followup' "$log" "the reply must use the follow-up endpoint" + assert_grep '"request_id":"req-restart"' "$log" \ + "the reply must target the ORIGINAL request binding" + assert_grep 'workers now land in the launching workspace' "$log" \ + "the reply must reuse the accepted terminal outcome verbatim" + + receipt=$(tasks_in "$home" public-followup list --json \ + | jq -r '(.public_followups // []) + | map(select(.id == "pf-restart")) | .[0].public_followup.delivery.receipt.state // "none"') + [ "$receipt" = posted ] || fail "a validated posted receipt must be recorded, got '$receipt'" + [ "$(task_state "$home" pf-restart)" = 'done' ] \ + || fail "the commitment must be Done only after the receipt" + assert_no_grep '^x_request=' "$child/state/work-code-q1.meta" \ + "typed delivery must clear the secondmate's legacy X link" + pass "restart end-to-end: typed result reconciles from disk and delivers one reply to the original thread" +} + +# --- 2. idempotency ------------------------------------------------------------ + +test_duplicate_event_and_replay_are_noops() { + local home log first second out posts + home=$(make_home idempotent) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-dup req-dup discord main work-dup + + first=$(emit_terminal "$home" "$home" pf-dup main work-dup) || fail "first emit failed" + second=$(emit_terminal "$home" "$home" pf-dup main work-dup) || fail "second emit failed" + [ "$first" = "$second" ] \ + || fail "the same terminal result must derive the same event identity" + [ "$(find "$home/state/public-followup/events" -name '*.json' | wc -l | tr -d ' ')" -eq 1 ] \ + || fail "a duplicate emit must not create a second event file" + + FAKE_CURL_LOG="$log" run_pf "$home" consume >/dev/null || fail "first consume failed" + # Replay the identical event after the fact, exactly as a restarted child would. + emit_terminal "$home" "$home" pf-dup main work-dup >/dev/null || fail "replay emit failed" + out=$(FAKE_CURL_LOG="$log" run_pf "$home" consume) || fail "replay consume failed" + [ -z "$out" ] || fail "replaying an accepted event must be silent, got: $out" + [ "$(delivery_state "$home" pf-dup)" = ready ] \ + || fail "replay must not disturb the delivery state" + + FAKE_CURL_LOG="$log" run_pf "$home" deliver pf-dup >/dev/null || fail "delivery failed" + out=$(FAKE_CURL_LOG="$log" run_pf "$home" deliver pf-dup) || fail "second deliver must succeed silently" + assert_contains "$out" "already delivered" "a second delivery must report the existing receipt" + posts=$(followup_posts "$log") + [ "$posts" -eq 1 ] || fail "a repeated delivery must never double-post, got $posts posts" + pass "duplicate terminal results, restart replay, and repeated delivery are all no-ops" +} + +# --- 3. refusals --------------------------------------------------------------- + +# Everything tasks-axi is the authority on - source home, work id, generation, +# schema, and permitted deliverables - must be refused rather than half-applied, +# and quarantined rather than retried forever. +test_invalid_events_are_refused_and_quarantined() { + local home out events rejected + home=$(make_home refusals) + seed_commitment "$home" pf-refuse req-refuse discord secondmate:fmdev work-real + + # Wrong source home and wrong work id are caught at the edge by the emitter, + # because the owning home's own registration disagrees. + expect_failure "a wrong source home must be refused" \ + "$EMIT" --home "$home" --obligation pf-refuse --relation rel-code \ + --source-home secondmate:other --work-id work-real --generation 1 \ + --outcome pr-merged --deliverable pr_url=https://example.invalid/1 \ + --outcome-text 'x' + assert_contains "$EXPECT_OUT" "does not match this home's registration" \ + "the refusal must name the mismatch" + + expect_failure "a wrong work id must be refused" \ + "$EMIT" --home "$home" --obligation pf-refuse --relation rel-code \ + --source-home secondmate:fmdev --work-id work-other --generation 1 \ + --outcome pr-merged --deliverable pr_url=https://example.invalid/1 \ + --outcome-text 'x' + expect_failure "a stale generation must be refused" \ + "$EMIT" --home "$home" --obligation pf-refuse --relation rel-code \ + --source-home secondmate:fmdev --work-id work-real --generation 0 \ + --outcome pr-merged --deliverable pr_url=https://example.invalid/1 \ + --outcome-text 'x' + + events="$home/state/public-followup/events" + rejected="$home/state/public-followup/rejected" + + # A malformed event that bypassed the emitter entirely. + printf 'not json at all\n' > "$events/deadbeef.json" + out=$(run_pf "$home" consume) || fail "consume must survive a malformed event" + assert_contains "$out" "rejected deadbeef" "a malformed event must be refused" + assert_absent "$events/deadbeef.json" "a refused event must leave the pending inbox" + assert_present "$rejected/deadbeef.reason" "a refusal must keep an inspectable reason" + + # A deliverable the expected-final type does not permit. The emitter accepts the + # shape; tasks-axi is the authority that refuses the semantics. + "$EMIT" --home "$home" --obligation pf-refuse --relation rel-code \ + --source-home secondmate:fmdev --work-id work-real --generation 1 \ + --outcome pr-merged --deliverable report_path=data/x/report.md \ + --outcome-text 'wrong deliverable for a merged PR' >/dev/null \ + || fail "the emitter should publish a shape-valid event" + out=$(run_pf "$home" consume) || fail "consume must survive an unsupported deliverable" + assert_contains "$out" "rejected " "an unsupported deliverable must be refused by tasks-axi" + [ "$(delivery_state "$home" pf-refuse)" = pending-work ] \ + || fail "a refused event must leave the commitment untouched" + + # A hand-edited event whose id no longer matches its own identity fields. + jq -n '{schema_version:1, event_id:"forged", obligation_id:"pf-refuse", + relation_id:"rel-code", work_id:"work-real", generation:1, + source_home_id:"secondmate:fmdev", outcome_type:"pr-merged", + deliverables:{pr_url:"https://example.invalid/9"}, + public_safe_outcome:"forged", occurred_at:"2026-07-30T12:00:00Z", + successor:null}' > "$events/forged.json" + out=$(run_pf "$home" consume) || fail "consume must survive a forged event" + assert_contains "$out" "rejected forged" "a forged event identity must be refused" + pass "wrong source, wrong work id, stale generation, malformed, unsupported deliverable, and forged identity are all refused" +} + +# --- 4. transport failure and late receipt ------------------------------------- + +test_relay_failure_holds_without_false_completion() { + local home log out posts + home=$(make_home retryable) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-retry req-retry discord main work-retry + emit_terminal "$home" "$home" pf-retry main work-retry >/dev/null || fail "emit failed" + FAKE_CURL_LOG="$log" run_pf "$home" consume >/dev/null || fail "consume failed" + + FAKE_CURL_LOG="$log" FAKE_FOLLOWUP_CODE=500 \ + expect_failure "a failed relay post must not report success" \ + run_pf "$home" deliver pf-retry + assert_contains "$EXPECT_OUT" "recorded as retryable" "the failure must be typed as retryable" + [ "$(delivery_state "$home" pf-retry)" = retry-due ] \ + || fail "a failed post must leave a retryable state, got $(delivery_state "$home" pf-retry)" + [ "$(task_state "$home" pf-retry)" != 'done' ] \ + || fail "a failed post must never close the commitment" + + # The retry succeeds and closes it, with exactly one successful post. + : > "$log" + FAKE_CURL_LOG="$log" run_pf "$home" deliver pf-retry >/dev/null || fail "the retry should deliver" + posts=$(followup_posts "$log") + [ "$posts" -eq 1 ] || fail "the retry must post exactly once, got $posts" + [ "$(task_state "$home" pf-retry)" = 'done' ] || fail "a successful retry must close the commitment" + pass "a relay transport failure is held as retryable with no false completion, and the retry posts once" +} + +test_dry_run_does_not_close_commitment() { + local home log out posts + home=$(make_home dry-run) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-dry req-dry discord main work-dry + emit_terminal "$home" "$home" pf-dry main work-dry >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + + FMX_DRY_RUN=1 FAKE_CURL_LOG="$log" expect_failure \ + "a dry-run must not close a public commitment" run_pf "$home" deliver pf-dry + assert_contains "$EXPECT_OUT" "recorded as retryable" \ + "a dry-run must leave a retryable typed state" + [ "$(delivery_state "$home" pf-dry)" = retry-due ] \ + || fail "a dry-run must leave the obligation retryable, got $(delivery_state "$home" pf-dry)" + [ "$(task_state "$home" pf-dry)" != 'done' ] \ + || fail "a dry-run must never close the commitment" + posts=$(followup_posts "$log") + [ "$posts" -eq 0 ] || fail "a dry-run must not post to the relay, got $posts posts" + pass "a dry-run records no public delivery and leaves the commitment retryable" +} + +test_late_receipt_closes_the_exact_attempt_without_reposting() { + local home log out posts attempt + home=$(make_home late-receipt) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-late req-late x main work-late + fm_write_meta "$home/state/work-late.meta" \ + "x_request=req-late" "x_request_ts=1700000000" "x_followups=1" + emit_terminal "$home" "$home" pf-late main work-late >/dev/null || fail "emit failed" + FAKE_CURL_LOG="$log" run_pf "$home" consume >/dev/null || fail "consume failed" + + FAKE_CURL_LOG="$log" FAKE_FOLLOWUP_CODE=503 run_pf "$home" deliver pf-late >/dev/null 2>&1 || true + attempt=$(tasks_in "$home" public-followup list --json \ + | jq -r '(.public_followups // []) | map(select(.id == "pf-late")) + | .[0].public_followup.delivery.attempt_count') + [ "$attempt" = 1 ] || fail "the failed attempt must be recorded as attempt 1, got '$attempt'" + + expect_failure "a late receipt must include its exact message count" \ + run_pf "$home" record-posted pf-late --attempt 1 + assert_contains "$EXPECT_OUT" "--chunks <n> is required" \ + "a late receipt without a message count must be refused" + + # The post actually landed; its receipt was simply lost. Close the exact attempt + # without sending anything else. + : > "$log" + out=$(FAKE_CURL_LOG="$log" run_pf "$home" record-posted pf-late --attempt 1 --chunks 1) \ + || fail "recording a late receipt for the exact attempt must succeed" + assert_contains "$out" "recorded pf-late attempt=1" "the late receipt must name its attempt" + posts=$(followup_posts "$log") + [ "$posts" -eq 0 ] || fail "recording a late receipt must post nothing, got $posts posts" + [ "$(task_state "$home" pf-late)" = 'done' ] || fail "a validated late receipt must close the commitment" + assert_no_grep '^x_request=' "$home/state/work-late.meta" \ + "a late receipt must clear the legacy X link" + + FAKE_CURL_LOG="$log" expect_failure "a receipt for a different attempt must be refused" \ + run_pf "$home" record-posted pf-late --attempt 9 --chunks 1 + pass "a late success receipt closes the exact attempt with no second post, and a mismatched attempt is refused" +} + +test_typed_terminal_clear_only_removes_legacy_link() { + local home meta out + home=$(make_home typed-clear) + meta="$home/state/work-clear.meta" + printf '%s\n' 'status=working' 'x_request=req-clear' 'x_request_ts=1700000000' \ + 'x_followups=2' 'x_platform=discord' 'x_reply_max_chars=1900' > "$meta" + + out=$(PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" "$ROOT/bin/fm-x-followup.sh" --clear work-clear) \ + || fail "the typed terminal clear transition must succeed" + [ "$out" = work-clear ] || fail "the clear-only transition must identify the task" + assert_grep 'status=working' "$meta" "clear-only transition must preserve unrelated task metadata" + assert_no_grep '^x_request=' "$meta" "clear-only transition must remove the request link" + assert_no_grep '^x_followups=' "$meta" "clear-only transition must remove the follow-up counter" + assert_no_grep '^x_platform=' "$meta" "clear-only transition must remove platform metadata" + pass "typed terminal cleanup clears the legacy link without posting" +} + +# A crash between the post and its receipt is the one case where we cannot know +# whether the thread already got a reply. Delivery must refuse rather than guess. +test_interrupted_delivery_refuses_to_repost() { + local home log out posts + home=$(make_home interrupted) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-crash req-crash discord main work-crash + emit_terminal "$home" "$home" pf-crash main work-crash >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + + # Reproduce the crash window directly through the state machine. + tasks_in "$home" public-followup begin-delivery pf-crash \ + --payload-hash 0000000000000000000000000000000000000000000000000000000000000000 >/dev/null \ + || fail "could not stage the interrupted attempt" + + FAKE_CURL_LOG="$log" expect_failure "an interrupted delivery must not silently post again" \ + run_pf "$home" deliver pf-crash + assert_contains "$EXPECT_OUT" "mid-delivery" "the refusal must name the interrupted attempt" + posts=$(followup_posts "$log") + [ "$posts" -eq 0 ] || fail "an interrupted delivery must post nothing, got $posts posts" + pass "a delivery interrupted between post and receipt refuses to repost" +} + +# --- 5. ownership -------------------------------------------------------------- + +# The outward post belongs to the home holding the relay consent and the thread +# binding. A child home has neither, and must not be able to acquire them. +test_outward_delivery_stays_with_the_owning_home() { + local owner child log out + owner=$(make_home owner) + child=$(make_home child relay-off) + log="$owner/curl.log"; : > "$log" + seed_commitment "$owner" pf-own req-own discord secondmate:child work-child + printf '%s\n' child > "$child/.fm-secondmate-home" + fm_write_meta "$owner/state/child.meta" "kind=secondmate" "home=$child" + fm_write_meta "$child/state/work-child.meta" \ + "x_request=req-own" "x_request_ts=1700000000" "x_followups=1" + + FAKE_CURL_LOG="$log" emit_terminal "$owner" "$owner" pf-own secondmate:child work-child >/dev/null \ + || fail "the child could not report its typed result" + [ "$(followup_posts "$log")" -eq 0 ] \ + || fail "reporting a terminal result must never post publicly" + run_pf "$owner" consume >/dev/null || fail "the owning home could not consume the child's typed result" + + # The child home has no commitment of its own and no relay consent, so it can + # neither deliver nor even see one. + PATH="$child/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$child" \ + FM_STATE_OVERRIDE="$child/state" FAKE_CURL_LOG="$log" \ + expect_failure "a home without relay consent must not deliver a public reply" \ + "$PF" deliver pf-own + assert_contains "$EXPECT_OUT" "has not opted into the myfirstmate relay" \ + "the refusal must name the missing relay consent" + [ "$(followup_posts "$log")" -eq 0 ] || fail "the refused delivery must post nothing" + FAKE_CURL_LOG="$log" run_pf "$owner" deliver pf-own >/dev/null \ + || fail "the owning home must deliver the typed public reply" + assert_no_grep '^x_request=' "$child/state/work-child.meta" \ + "typed delivery must clear the child task's legacy X link" + pass "a child home reports typed results but can never become the outward-post owner" +} + +test_delivery_requires_registration_before_posting() { + local home log out + home=$(make_home missing-registration) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-missing req-missing x main work-missing + fm_write_meta "$home/state/work-missing.meta" \ + "x_request=req-missing" "x_request_ts=1700000000" "x_followups=1" + emit_terminal "$home" "$home" pf-missing main work-missing >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + rm -f "$home/state/public-followup/registry/pf-missing" + + FAKE_CURL_LOG="$log" expect_failure "delivery without a registration must refuse" \ + run_pf "$home" deliver pf-missing + assert_contains "$EXPECT_OUT" "registration for 'pf-missing' is missing or invalid" \ + "missing registration must be an actionable delivery refusal" + [ "$(followup_posts "$log")" -eq 0 ] || fail "missing registration must prevent any public post" + [ "$(task_state "$home" pf-missing)" != 'done' ] \ + || fail "missing registration must not close the obligation" + assert_grep 'x_request=req-missing' "$home/state/work-missing.meta" \ + "missing registration must leave the legacy link for reconciliation" + pass "typed delivery refuses to post when its cleanup registration is missing" +} + +test_secondmate_teardown_requires_parent_binding() { + local parent child registry_before marker_before + parent=$(make_home teardown-parent) + child=$(make_home teardown-child) + printf '%s\n' mate > "$child/.fm-secondmate-home" + seed_commitment "$parent" pf-teardown req-teardown x secondmate:mate work-child + fm_write_meta "$parent/state/mate.meta" "kind=secondmate" "home=$child" + fm_write_meta "$child/state/work-child.meta" \ + "window=firstmate:fm-work-child" "endpoint_task_id=work-child" \ + "worktree=$child" "project=$child" "kind=ship" "mode=local-only" + + PATH="$child/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$child" \ + FM_STATE_OVERRIDE="$child/state" FM_DATA_OVERRIDE="$child/data" \ + expect_failure "marked child teardown without a parent must refuse cleanup" \ + "$TEARDOWN" work-child + assert_contains "$EXPECT_OUT" "cannot resolve the primary home for marked secondmate mate" \ + "missing parent binding must be an actionable teardown refusal" + assert_present "$child/state/work-child.meta" \ + "missing parent binding must preserve the child work metadata" + + parent=$(make_home teardown-valid-parent) + child=$(make_home teardown-valid-child) + printf '%s\n' mate > "$child/.fm-secondmate-home" + printf -- '- mate - synthetic (id is legacy); preserve this (home: %s; scope: synthetic (child); semicolon remains meaningful; projects: ; added 2026-07-30)\n' \ + "$child" > "$parent/data/secondmates.md" + FM_HOME="$parent" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null \ + || fail "home-seed validation rejected a punctuation-bearing operational registry record" + registry_before=$(cat "$parent/data/secondmates.md") + marker_before=$(cat "$child/.fm-secondmate-home") + seed_commitment "$parent" pf-teardown-valid req-teardown-valid x secondmate:mate work-child + fm_write_meta "$parent/state/mate.meta" "kind=secondmate" "home=$child" + fm_write_meta "$child/state/work-child.meta" \ + "window=firstmate:fm-work-child" "endpoint_task_id=work-child" \ + "worktree=$child" "project=$child" "kind=ship" "mode=local-only" + + PATH="$child/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$child" \ + FM_STATE_OVERRIDE="$child/state" FM_DATA_OVERRIDE="$child/data" \ + FM_PUBLIC_FOLLOWUP_PRIMARY_HOME="$parent" \ + expect_failure "marked child teardown with a valid parent must enforce the parent commitment" \ + "$TEARDOWN" work-child + assert_contains "$EXPECT_OUT" "still owes a public reply" \ + "valid parent binding must route cleanup through the parent commitment" + case "$EXPECT_OUT" in + *"cannot resolve the primary home"*) fail "valid parent binding was reported as unresolved" ;; + esac + assert_present "$child/state/work-child.meta" \ + "an owed parent commitment must preserve the child work metadata" + [ "$registry_before" = "$(cat "$parent/data/secondmates.md")" ] \ + || fail "guarded cleanup refusal changed the parent registry" + [ "$marker_before" = "$(cat "$child/.fm-secondmate-home")" ] \ + || fail "guarded cleanup refusal changed the child identity marker" + pass "marked secondmate teardown resolves its parent and fails closed when unavailable" +} + +test_relay_disabled_unmarked_teardown_skips_public_path() { + local home tasks_log out rc + home=$(make_home teardown-disabled-unmarked relay-off) + fm_git_init_commit "$home/projects/worktree" + tasks_log="$home/tasks-axi.log"; : > "$tasks_log" + printf 'manual\n' > "$home/config/backlog-backend" + cat > "$home/fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +echo "$*" >> "$FAKE_TASKS_AXI_LOG" +exit 99 +SH + chmod +x "$home/fakebin/tasks-axi" + fm_write_meta "$home/state/work-disabled.meta" \ + "window=firstmate:fm-work-disabled" "endpoint_task_id=work-disabled" \ + "worktree=$home/projects/worktree" "project=$home/projects/worktree" \ + "kind=ship" "mode=local-only" + + rc=0 + out=$(PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \ + FM_CONFIG_OVERRIDE="$home/config" FAKE_TASKS_AXI_LOG="$tasks_log" \ + "$TEARDOWN" work-disabled 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "relay-disabled unmarked teardown must not refuse public-followup cleanup (rc=$rc): $out" + [ ! -s "$tasks_log" ] || fail "relay-disabled unmarked teardown must not invoke tasks-axi: $(tr '\n' ';' < "$tasks_log")" + assert_not_contains "$out" "still owes a public reply" \ + "relay-disabled unmarked teardown must not run the public commitment guard" + assert_absent "$home/state/public-followup" \ + "relay-disabled unmarked teardown must not create a public-followup artifact" + pass "relay-disabled unmarked teardown runs no public-followup work" +} + +test_relay_disabled_parent_allows_marked_child_teardown() { + local parent child tasks_log out rc + parent=$(make_home teardown-disabled-parent relay-off) + child=$(make_home teardown-disabled-child relay-off) + fm_git_init_commit "$child/projects/worktree" + printf '%s\n' disabled-mate > "$child/.fm-secondmate-home" + printf -- '- disabled-mate - synthetic (home: %s; scope: synthetic; projects: ; added 2026-07-30)\n' \ + "$child" > "$parent/data/secondmates.md" + fm_write_meta "$parent/state/disabled-mate.meta" "kind=secondmate" "home=$child" + tasks_log="$child/tasks-axi.log"; : > "$tasks_log" + printf 'manual\n' > "$child/config/backlog-backend" + cat > "$child/fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +echo "$*" >> "$FAKE_TASKS_AXI_LOG" +exit 99 +SH + chmod +x "$child/fakebin/tasks-axi" + fm_write_meta "$child/state/work-disabled.meta" \ + "window=firstmate:fm-work-disabled" "endpoint_task_id=work-disabled" \ + "worktree=$child/projects/worktree" "project=$child/projects/worktree" \ + "kind=ship" "mode=local-only" + + rc=0 + out=$(PATH="$child/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$child" \ + FM_STATE_OVERRIDE="$child/state" FM_DATA_OVERRIDE="$child/data" \ + FM_CONFIG_OVERRIDE="$child/config" \ + FM_PUBLIC_FOLLOWUP_PRIMARY_HOME="$parent" FAKE_TASKS_AXI_LOG="$tasks_log" \ + "$TEARDOWN" work-disabled 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "relay-disabled parent must allow marked-child teardown (rc=$rc): $out" + [ ! -s "$tasks_log" ] || fail "relay-disabled parent must not invoke tasks-axi for a marked child" + assert_not_contains "$out" "still owes a public reply" \ + "relay-disabled parent must not run the public commitment guard" + assert_absent "$child/state/public-followup" \ + "relay-disabled parent must not create a public-followup artifact" + pass "a marked child proceeds without tasks-axi when its parent relay is disabled" +} + +test_secondmate_parent_binding_matches_literal_id() { + local parent child + parent=$(make_home teardown-literal-parent) + child=$(make_home teardown-literal-child) + printf '%s\n' 'mate.id' > "$child/.fm-secondmate-home" + printf -- '- mateXid - synthetic (home: %s; scope: synthetic; projects: ; added 2026-07-30)\n' \ + "$child" > "$parent/data/secondmates.md" + seed_commitment "$parent" pf-teardown-literal req-teardown-literal x secondmate:mate.id work-literal + fm_write_meta "$parent/state/mate.id.meta" "kind=secondmate" "home=$child" + fm_write_meta "$child/state/work-literal.meta" \ + "window=firstmate:fm-work-literal" "endpoint_task_id=work-literal" \ + "worktree=$child" "project=$child" "kind=ship" "mode=local-only" + + PATH="$child/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$child" \ + FM_STATE_OVERRIDE="$child/state" FM_DATA_OVERRIDE="$child/data" \ + FM_CONFIG_OVERRIDE="$child/config" FM_PUBLIC_FOLLOWUP_PRIMARY_HOME="$parent" \ + expect_failure "a near-match registry id must not satisfy a dotted parent binding" \ + "$TEARDOWN" work-literal + assert_contains "$EXPECT_OUT" "cannot resolve the primary home for marked secondmate mate.id" \ + "a dotted id must be matched as an exact registry field" + assert_present "$child/state/work-literal.meta" \ + "a near-match parent binding must preserve the child work metadata" + pass "secondmate parent resolution matches the durable registry id literally" +} + +test_traversal_registration_is_refused_before_delivery() { + local home log out + home=$(make_home traversal-registration) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-traversal req-traversal x main work-traversal + emit_terminal "$home" "$home" pf-traversal main work-traversal >/dev/null \ + || fail "emit failed for traversal registration" + sed -i.bak 's/^work_home=.*/work_home=secondmate:..\/..\/x/' \ + "$home/state/public-followup/registry/pf-traversal" + rm -f "$home/state/public-followup/registry/pf-traversal.bak" + run_pf "$home" consume >/dev/null || fail "consume failed for traversal registration" + + out=$(FAKE_CURL_LOG="$log" run_pf "$home" deliver pf-traversal 2>&1) && \ + fail "a traversal-shaped registration must not be deliverable" + assert_contains "$out" "registration for 'pf-traversal' is missing or invalid" \ + "a traversal-shaped work home must be rejected before delivery" + [ "$(followup_posts "$log")" -eq 0 ] || fail "an invalid work home must not post publicly" + assert_present "$home/state/public-followup/registry/pf-traversal" \ + "an invalid work home must retain its registration for reconciliation" + [ "$(task_state "$home" pf-traversal)" != 'done' ] \ + || fail "an invalid work home must not close the obligation" + pass "traversal-shaped registrations are rejected before path construction or posting" +} + +test_pending_rejects_malformed_listing() { + local home out + home=$(make_home pending-malformed) + seed_commitment "$home" pf-malformed req-malformed discord main work-malformed + cat > "$home/fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +printf '%s' '{"public_followups":[' +SH + chmod +x "$home/fakebin/tasks-axi" + + out=$(run_pf "$home" pending) || fail "pending must survive malformed tasks-axi output" + assert_contains "$out" "cannot read this home's public commitments through tasks-axi" \ + "malformed backlog output must use the loud fallback" + assert_present "$home/state/public-followup/registry/pf-malformed" \ + "malformed backlog output must retain the registration" + pass "pending keeps registrations when tasks-axi returns malformed JSON" +} + +test_private_context_survives_inbox_cleanup() { + local home log posts + home=$(make_home context-retention) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-ctx req-ctx discord main work-ctx + emit_terminal "$home" "$home" pf-ctx main work-ctx >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + + # Drain the inbox exactly as answering the original mention does, and make any + # relay fallback fail, so only the retained private context can resolve the + # thread's platform and size budget. + rm -f "$home/state/x-inbox/req-ctx.json" + assert_present "$home/state/x-context/req-ctx.json" \ + "the private request context must outlive the inbox payload" + + FAKE_CURL_LOG="$log" FAKE_REQCTX_CODE=500 run_pf "$home" deliver pf-ctx >/dev/null \ + || fail "delivery must still resolve the thread from retained private context" + posts=$(followup_posts "$log") + [ "$posts" -eq 1 ] || fail "expected one reply after inbox cleanup, got $posts" + assert_grep '"request_id":"req-ctx"' "$log" "the reply must still target the original thread" + pass "the retained private request context keeps the original thread deliverable after inbox cleanup" +} + +# --- 6. completion semantics --------------------------------------------------- + +test_cleanup_refuses_while_a_public_reply_is_owed() { + local home rc + home=$(make_home cleanup-guard) + seed_commitment "$home" pf-guard req-guard discord main ship-task + fm_write_meta "$home/state/ship-task.meta" \ + "window=firstmate:fm-ship-task" \ + "worktree=$home/projects/gone" \ + "project=$home/projects/sample" \ + "harness=codex" \ + "kind=ship" \ + "mode=no-mistakes" + + rc=0 + PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \ + FM_CONFIG_OVERRIDE="$home/config" "$TEARDOWN" ship-task \ + > "$home/teardown.out" 2> "$home/teardown.err" || rc=$? + [ "$rc" -ne 0 ] || fail "cleanup must refuse while a public reply is still owed" + assert_grep "still owes a public reply" "$home/teardown.err" "the refusal must be explicit" + assert_present "$home/state/ship-task.meta" "a refused cleanup must preserve the task record" + + # Once the reply has landed, the same cleanup is allowed to proceed. + emit_terminal "$home" "$home" pf-guard main ship-task >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + FAKE_CURL_LOG="$home/curl.log" run_pf "$home" deliver pf-guard >/dev/null || fail "delivery failed" + rc=0 + PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FM_DATA_OVERRIDE="$home/data" \ + FM_CONFIG_OVERRIDE="$home/config" "$TEARDOWN" ship-task >/dev/null 2>&1 || rc=$? + [ "$rc" -eq 0 ] || fail "cleanup must proceed once the public reply has landed (rc=$rc)" + pass "cleanup refuses while a public reply is owed and proceeds once it has landed" +} + +# --- 7. zero overhead for homes that do not use the relay ---------------------- + +# The hard acceptance criterion. A home that never opted into the myfirstmate +# relay must see no process, no tasks-axi call, no scan, no output, and no file. +test_relay_disabled_home_pays_nothing() { + local home tasks_log out rc before after cmd + home=$(make_home relay-disabled relay-off) + tasks_log="$home/tasks-axi.log"; : > "$tasks_log" + # Any tasks-axi invocation at all is a failure here, so make it loud. + cat > "$home/fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +echo "$*" >> "$FAKE_TASKS_AXI_LOG" +exit 0 +SH + chmod +x "$home/fakebin/tasks-axi" + + before=$(find "$home/state" | LC_ALL=C sort) + for cmd in "consume" "pending" "guard-work main any-task" "retire anything"; do + rc=0 + # shellcheck disable=SC2086 # each cmd is a deliberate argument list + out=$(PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FAKE_TASKS_AXI_LOG="$tasks_log" "$PF" $cmd 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "'$cmd' must be a silent success in a relay-disabled home (rc=$rc)" + [ -z "$out" ] || fail "'$cmd' must print nothing in a relay-disabled home, got: $out" + done + + rc=0 + PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FAKE_TASKS_AXI_LOG="$tasks_log" "$PF" active || rc=$? + [ "$rc" -eq 1 ] || fail "'active' must report inactive in a relay-disabled home" + + [ ! -s "$tasks_log" ] \ + || fail "a relay-disabled home must never invoke tasks-axi: $(cat "$tasks_log")" + after=$(find "$home/state" | LC_ALL=C sort) + [ "$before" = "$after" ] \ + || fail "a relay-disabled home must gain no public-followup artifact" + assert_absent "$home/state/public-followup" \ + "a relay-disabled home must never get a public-followup directory" + + # A child cannot force artifacts into a home that never opted in either. + rc=0 + out=$("$EMIT" --home "$home" --obligation pf-x --relation rel-code \ + --source-home main --work-id w --generation 1 --outcome pr-merged \ + --outcome-text 'x' 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "emitting into a relay-disabled home must be a silent no-op (rc=$rc)" + [ -z "$out" ] || fail "emitting into a relay-disabled home must produce no output: $out" + assert_absent "$home/state/public-followup" \ + "a refused emit must not create a public-followup directory" + pass "a relay-disabled home runs no tasks-axi call, prints nothing, and gains no artifact" +} + +# An opted-in home that has never made a public commitment must not start paying +# either: the second gate is a directory presence check, not a backlog scan. +test_relay_enabled_empty_state_makes_no_calls() { + local home tasks_log out rc cmd + home=$(make_home relay-enabled-empty) + tasks_log="$home/tasks-axi.log"; : > "$tasks_log" + cat > "$home/fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +echo "$*" >> "$FAKE_TASKS_AXI_LOG" +exit 0 +SH + chmod +x "$home/fakebin/tasks-axi" + + for cmd in "consume" "pending" "guard-work main any-task"; do + rc=0 + # shellcheck disable=SC2086 # each cmd is a deliberate argument list + out=$(PATH="$home/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$home" \ + FM_STATE_OVERRIDE="$home/state" FAKE_TASKS_AXI_LOG="$tasks_log" "$PF" $cmd 2>&1) || rc=$? + [ "$rc" -eq 0 ] || fail "'$cmd' must be a silent success with no commitments (rc=$rc)" + [ -z "$out" ] || fail "'$cmd' must print nothing with no commitments, got: $out" + done + [ ! -s "$tasks_log" ] \ + || fail "an empty relay home must not query the backlog: $(cat "$tasks_log")" + pass "a relay-enabled home with no commitments makes no backlog call and stays silent" +} + +# The relay's own refusal of an exhausted follow-up binding is a captain +# decision, not something to retry into a public thread. +test_exhausted_binding_is_not_retried() { + local home log out posts + home=$(make_home exhausted) + log="$home/curl.log"; : > "$log" + seed_commitment "$home" pf-gone req-gone x main work-gone + emit_terminal "$home" "$home" pf-gone main work-gone >/dev/null || fail "emit failed" + run_pf "$home" consume >/dev/null || fail "consume failed" + + FAKE_CURL_LOG="$log" FAKE_FOLLOWUP_CODE=409 \ + expect_failure "an exhausted binding must not be reported as delivered" \ + run_pf "$home" deliver pf-gone + assert_contains "$EXPECT_OUT" "captain decision" "an exhausted binding must be escalated, not retried" + [ "$(delivery_state "$home" pf-gone)" = expired-action-required ] \ + || fail "an exhausted binding must be recorded as needing action, got $(delivery_state "$home" pf-gone)" + [ "$(task_state "$home" pf-gone)" != 'done' ] \ + || fail "an exhausted binding must never close the commitment" + posts=$(followup_posts "$log") + [ "$posts" -eq 1 ] || fail "the refused attempt is one relay call, got $posts" + pass "a relay-exhausted follow-up binding is escalated rather than retried into the thread" +} + +# The relay poll is the only thing that runs on a cadence in an opted-in home, so +# it must stay a hard no-op without a token, and must not start scanning when a +# relay-enabled home has no public commitments at all. +test_relay_poll_stays_inert_and_surfaces_once() { + local off on out first second + off=$(make_home poll-off relay-off) + out=$(PATH="$off/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$off" \ + FM_STATE_OVERRIDE="$off/state" "$POLL" 2>&1) + [ -z "$out" ] || fail "the relay poll must stay silent without a token, got: $out" + assert_absent "$off/state/public-followup" "an inert poll must create nothing" + + on=$(make_home poll-on) + out=$(PATH="$on/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$on" \ + FM_STATE_OVERRIDE="$on/state" "$POLL" 2>&1) + assert_not_contains "$out" "public-followup" \ + "a relay home with no public commitments must not mention public follow-ups" + + seed_commitment "$on" pf-poll req-poll discord main work-poll + out=$(PATH="$on/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$on" \ + FM_STATE_OVERRIDE="$on/state" "$POLL" 2>&1) + assert_not_contains "$out" "public-followup" \ + "a registered commitment with no terminal result yet must not wake the poll" + + emit_terminal "$on" "$on" pf-poll main work-poll >/dev/null || fail "emit failed" + first=$(PATH="$on/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$on" \ + FM_STATE_OVERRIDE="$on/state" "$POLL" 2>&1) + assert_contains "$first" "public-followup terminal results are waiting" \ + "a new terminal result must surface through the existing relay poll" + second=$(PATH="$on/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$on" \ + FM_STATE_OVERRIDE="$on/state" "$POLL" 2>&1) + assert_not_contains "$second" "public-followup" \ + "an unchanged pending set must not wake firstmate again every cycle" + pass "the relay poll stays inert without a token, silent with no commitments, and surfaces a new result once" +} + +# --- 8. startup surfacing ------------------------------------------------------ + +test_session_start_surfaces_only_when_owed() { + local off on out + off=$(make_home startup-off relay-off) + out=$(PATH="$off/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$off" \ + FM_STATE_OVERRIDE="$off/state" FM_DATA_OVERRIDE="$off/data" \ + FM_CONFIG_OVERRIDE="$off/config" "$SESSION_START" 2>&1) + assert_not_contains "$out" "Public commitments" \ + "a relay-disabled home must not gain a public-commitments section at startup" + + on=$(make_home startup-on) + seed_commitment "$on" pf-start req-start discord main work-start + out=$(PATH="$on/fakebin:$PATH" FM_ROOT_OVERRIDE="$ROOT" FM_HOME="$on" \ + FM_STATE_OVERRIDE="$on/state" FM_DATA_OVERRIDE="$on/data" \ + FM_CONFIG_OVERRIDE="$on/config" "$SESSION_START" 2>&1) + assert_contains "$out" "Public commitments awaiting delivery" \ + "an unresolved commitment must be surfaced at startup" + assert_contains "$out" "unresolved pf-start state=pending-work platform=discord" \ + "the startup summary must be typed and actionable" + assert_contains "$out" "fix worker placement when two spaces share a name" \ + "the startup summary must carry the public-safe summary" + assert_not_contains "$out" "please fix worker placement" \ + "the startup summary must not carry raw request text" + pass "startup surfaces unresolved public commitments only in a relay home that owes one" +} + +# --- 9. typed records stay public-safe ---------------------------------------- + +test_typed_records_exclude_raw_public_material() { + local home backlog event + home=$(make_home privacy) + seed_commitment "$home" pf-priv req-priv discord main work-priv + emit_terminal "$home" "$home" pf-priv main work-priv >/dev/null || fail "emit failed" + event=$(find "$home/state/public-followup/events" -name '*.json' | head -1) + assert_no_grep 'please fix worker placement' "$event" \ + "a terminal event must not carry raw request text" + run_pf "$home" consume >/dev/null || fail "consume failed" + + backlog="$home/data/backlog.md" + assert_no_grep 'please fix worker placement' "$backlog" \ + "the backlog must never carry raw public message text" + # The typed record is base64url canonical JSON, so check the decoded payload too. + tasks_in "$home" public-followup list --json > "$home/typed.json" + assert_no_grep 'please fix worker placement' "$home/typed.json" \ + "the typed obligation must never carry raw public message text" + pass "typed public-followup records carry only public-safe summaries and deliverables" +} + +test_outcome_text_is_bounded_without_corrupting_characters +test_restart_e2e_delivers_exactly_once +test_duplicate_event_and_replay_are_noops +test_invalid_events_are_refused_and_quarantined +test_relay_failure_holds_without_false_completion +test_dry_run_does_not_close_commitment +test_late_receipt_closes_the_exact_attempt_without_reposting +test_typed_terminal_clear_only_removes_legacy_link +test_interrupted_delivery_refuses_to_repost +test_outward_delivery_stays_with_the_owning_home +test_delivery_requires_registration_before_posting +test_secondmate_teardown_requires_parent_binding +test_relay_disabled_unmarked_teardown_skips_public_path +test_relay_disabled_parent_allows_marked_child_teardown +test_secondmate_parent_binding_matches_literal_id +test_traversal_registration_is_refused_before_delivery +test_pending_rejects_malformed_listing +test_private_context_survives_inbox_cleanup +test_cleanup_refuses_while_a_public_reply_is_owed +test_relay_disabled_home_pays_nothing +test_relay_enabled_empty_state_makes_no_calls +test_exhausted_binding_is_not_retried +test_relay_poll_stays_inert_and_surfaces_once +test_session_start_surfaces_only_when_owed +test_typed_records_exclude_raw_public_material diff --git a/tests/fm-quota-array-dispatch-live-e2e.test.sh b/tests/fm-quota-array-dispatch-live-e2e.test.sh new file mode 100755 index 00000000000..0b7f1102aba --- /dev/null +++ b/tests/fm-quota-array-dispatch-live-e2e.test.sh @@ -0,0 +1,109 @@ +#!/usr/bin/env bash +# Credentialed behavior regression for the agent-owned quota-array-dispatch skill. +# +# This drives the public Pi skill-loading interface against a fake quota-axi +# executable rather than parsing instruction source bytes or recreating the +# selector in test code. +set -u + +if [ "${FM_QUOTA_ARRAY_DISPATCH_LIVE_E2E:-0}" != 1 ]; then + echo "skip: set FM_QUOTA_ARRAY_DISPATCH_LIVE_E2E=1 to run the credentialed Pi dispatch-selection regression" + exit 0 +fi + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +OWNER="$ROOT/.agents/skills/quota-array-dispatch/SKILL.md" + +fail() { + printf 'not ok - %s\n' "$1" >&2 + exit 1 +} + +command -v pi >/dev/null 2>&1 || fail "pi not found" +[ -f "$OWNER" ] || fail "quota-array-dispatch skill not found" + +LAB=$(mktemp -d "${TMPDIR:-/tmp}/fm-quota-array-dispatch-live.XXXXXX") +PROJECT="$LAB/project" +FAKEBIN="$LAB/fakebin" +FIXTURE="$LAB/quota.json" +CALLS="$LAB/quota-axi.calls" + +cleanup() { + rm -rf "$LAB" +} +trap cleanup EXIT + +mkdir -p "$PROJECT/.agents/skills/quota-array-dispatch" "$FAKEBIN" +cp "$OWNER" "$PROJECT/.agents/skills/quota-array-dispatch/SKILL.md" + +cat > "$FAKEBIN/quota-axi" <<'SH' +#!/usr/bin/env bash +set -u +if [ "${1:-}" != --json ] || [ "$#" -ne 1 ]; then + printf 'unexpected quota-axi invocation: %s\n' "$*" >&2 + exit 64 +fi +printf '%s\n' "$*" >> "${QUOTA_AXI_CALLS:?}" +cat "${QUOTA_AXI_FIXTURE:?}" +SH +chmod +x "$FAKEBIN/quota-axi" + +write_fixture() { + cat > "$FIXTURE" +} + +run_case() { + local label=$1 expected=$2 prompt=$3 out calls required + shift 3 + : > "$CALLS" + out=$( + cd "$PROJECT" && + PATH="$FAKEBIN:$PATH" QUOTA_AXI_CALLS="$CALLS" QUOTA_AXI_FIXTURE="$FIXTURE" \ + pi --print --approve --no-session --no-context-files --no-extensions \ + --no-skills --skill .agents/skills --tools bash \ + --model openai-codex/gpt-5.6-sol --thinking high \ + "$prompt" + ) || fail "$label: Pi skill run failed: $out" + calls=$(cat "$CALLS") + [ "$calls" = "--json" ] || fail "$label: skill did not use one quota-axi --json snapshot: $calls" + printf '%s\n' "$out" | grep -Fxq "$expected" \ + || fail "$label: expected final line $expected, got: $out" + for required in "$@"; do + printf '%s\n' "$out" | grep -Fxq "$required" \ + || fail "$label: expected accounting line $required, got: $out" + done + printf '%s\n' "$out" + printf 'ok - %s\n' "$label" +} + +write_fixture <<'JSON' +{"schemaVersion":3,"providers":[{"provider":"claude","quotaSemantics":{"description":"The all_models scope bounds every Claude model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":1,"boundedBy":["weekly"],"runway":{"status":"projected_exhaustion","usableRunwaySeconds":600,"projectedExhaustedAt":"2030-01-01T00:10:00Z","limitingWindowId":"weekly","projectionConfidence":"established","projectionBasis":"cycle_average"}}]},"effectivePace":[{"scope":"all_models","pace":"ahead","worstReservePercentPoints":-1}]},{"provider":"codex","quotaSemantics":{"description":"The all_models scope bounds every Codex model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":55,"boundedBy":["weekly"],"runway":{"status":"projected_exhaustion","usableRunwaySeconds":14400,"projectedExhaustedAt":"2030-01-01T04:00:00Z","limitingWindowId":"weekly","projectionConfidence":"established","projectionBasis":"cycle_average"}}]},"effectivePace":[{"scope":"all_models","pace":"ahead","worstReservePercentPoints":-40}]}]} +JSON +run_case \ + "higher headroom and viable runway beat a less-negative reserve" \ + "SELECTED=codex" \ + "Resolve this matched dispatch profile array now. Load quota-array-dispatch and run quota-axi --json exactly once. Both profiles have comparable required task fit and the same strongest reasoning class. The authoritative catalogs already prove Claude/Sonnet and Codex/GPT models supported in their stated provider families, and their selected authentication surfaces are usable. The likely task-completion horizon is two hours with established confidence. Return exact lines FACT=claude|headroom=1|runway_seconds=600|reserve=-1 and FACT=codex|headroom=55|runway_seconds=14400|reserve=-40 to preserve candidate accounting, then an exact final line SELECTED=<claude|codex>. Do not use other vendor or model commands and do not modify files." \ + "FACT=claude|headroom=1|runway_seconds=600|reserve=-1" \ + "FACT=codex|headroom=55|runway_seconds=14400|reserve=-40" + +write_fixture <<'JSON' +{"schemaVersion":3,"providers":[{"provider":"claude","quotaSemantics":{"description":"The all_models scope bounds every Claude model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":55,"boundedBy":["weekly"],"runway":{"status":"unknown","unmeasurableWindowIds":["weekly"]}}]}},{"provider":"codex","quotaSemantics":{"description":"The all_models scope bounds every Codex model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":45,"boundedBy":["weekly"],"runway":{"status":"projected_exhaustion","usableRunwaySeconds":14400,"projectedExhaustedAt":"2030-01-01T04:00:00Z","limitingWindowId":"weekly","projectionConfidence":"established","projectionBasis":"cycle_average"}}]}}]} +JSON +run_case \ + "unmeasurable runway stays eligible and is accounted for explicitly" \ + "DECISION=CODEX" \ + "Resolve this matched dispatch profile array now. Load quota-array-dispatch and run quota-axi --json exactly once. Both profiles have comparable required task fit and the same strongest reasoning class. The authoritative catalogs already prove both models supported in their stated provider families, and their selected authentication surfaces are usable. The likely task-completion horizon is two hours with established confidence. Claude has higher known headroom but explicitly unmeasurable runway, while Codex has lower known headroom and established runway that supports completion. The snapshot cannot prove Pareto dominance in either direction, but the known completion-supporting runway justifies Codex while Claude remains eligible and its uncertainty must be disclosed. Return exact lines FACT=claude|eligible=yes|headroom=55|runway=unknown|unmeasurable=weekly and FACT=codex|eligible=yes|headroom=45|runway_seconds=14400|supports_horizon=yes, then an exact final line DECISION=CODEX. Do not use other vendor or model commands and do not modify files." \ + "FACT=claude|eligible=yes|headroom=55|runway=unknown|unmeasurable=weekly" \ + "FACT=codex|eligible=yes|headroom=45|runway_seconds=14400|supports_horizon=yes" + +write_fixture <<'JSON' +{"schemaVersion":3,"providers":[{"provider":"claude","quotaSemantics":{"description":"The all_models scope bounds every Claude model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":1,"boundedBy":["weekly"],"runway":{"status":"projected_exhaustion","usableRunwaySeconds":10800,"projectedExhaustedAt":"2030-01-01T03:00:00Z","limitingWindowId":"weekly","projectionConfidence":"established","projectionBasis":"cycle_average"}}]}},{"provider":"codex","quotaSemantics":{"description":"The all_models scope bounds every Codex model.","effectiveAvailability":[{"scope":"all_models","status":"known","effectivePercentRemaining":80,"boundedBy":["weekly"],"runway":{"status":"projected_exhaustion","usableRunwaySeconds":28800,"projectedExhaustedAt":"2030-01-01T08:00:00Z","limitingWindowId":"weekly","projectionConfidence":"established","projectionBasis":"cycle_average"}}]}}]} +JSON +run_case \ + "required strongest reasoning class is not downgraded for quota" \ + "SELECTED=claude" \ + "Resolve this matched dispatch profile array now. Load quota-array-dispatch and run quota-axi --json exactly once. The likely task-completion horizon is two hours with established confidence. Claude/Sonnet is catalog-supported with usable authentication and is the only profile that meets the task's required strongest reasoning class. Codex/GPT is catalog-supported with usable authentication but is a weaker reasoning class and cannot meet the requirement. Return exact lines FACT=claude|reasoning=required|headroom=1|runway_seconds=10800 and FACT=codex|reasoning=weaker|headroom=80|runway_seconds=28800, then an exact final line SELECTED=<claude|codex>. Do not use other vendor or model commands and do not modify files." \ + "FACT=claude|reasoning=required|headroom=1|runway_seconds=10800" \ + "FACT=codex|reasoning=weaker|headroom=80|runway_seconds=28800" + +echo "# all quota-array-dispatch live behavior tests passed" diff --git a/tests/fm-secondmate-harness.test.sh b/tests/fm-secondmate-harness.test.sh index 0f6e8dc7a17..fa9b06b11ff 100755 --- a/tests/fm-secondmate-harness.test.sh +++ b/tests/fm-secondmate-harness.test.sh @@ -14,7 +14,8 @@ # explicit per-spawn harness arg still wins. # B) Inheritance. The primary pushes a declared, extensible set of LOCAL # (gitignored) config items - config/crew-dispatch.json, config/crew-harness, -# config/backlog-backend, config/backend, and config/herdr-presentation-spaces - +# config/backlog-backend, config/backend, config/herdr-presentation-spaces, and +# config/startup-memory-budget - # down into each secondmate home's config/, so the secondmate's OWN crewmates, # dispatch profiles, backlog backend, runtime-backend default, and Herdr # presentation opt-in inherit the primary's settings. It is primary-authoritative @@ -44,6 +45,15 @@ set -u # shellcheck source=/dev/null . "$ROOT/bin/fm-config-inherit-lib.sh" +# The harness-detection cases below fake `ps` so process ancestry is fully +# controlled, but bin/fm-harness.sh checks verified ENV markers before ancestry. +# A suite run from inside one of those harnesses inherits its marker, and the +# highest-precedence one wins over everything these cases set up: with an +# ambient CLAUDECODE=1, the pi-signed ancestry case resolves "claude". Drop the +# ambient markers so what this suite asserts does not depend on which harness it +# was launched from; every case states the marker it means to test. +unset CLAUDECODE PI_CODING_AGENT FM_PI_HARNESS GROK_AGENT + BASE_PATH=${FM_TEST_BASE_PATH:-/usr/bin:/bin:/usr/sbin:/sbin} fm_git_identity fmtest fmtest@example.com TMP_ROOT=$(fm_test_tmproot fm-secondmate-harness) @@ -159,19 +169,19 @@ esac SH chmod +x "$fakebin/ps" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "unmarked shared signed-wrapper ancestry resolved '$got', expected pi" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi-signed "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi-signed "$ROOT/bin/fm-harness.sh") [ "$got" = pi-signed ] || fail "selected signed wrapper resolved '$got', expected pi-signed" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "selected plain Pi resolved '$got', expected pi" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi-signed-helper "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_PI_HARNESS=pi-signed-helper "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "inexact signed selection marker resolved '$got', expected pi" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT='' FM_PI_HARNESS=pi-signed "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT -u PI_CODING_AGENT PATH="$fakebin:$BASE_PATH" FM_PI_HARNESS=pi-signed "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "signed selection marker without Pi's family marker resolved '$got', expected pi" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_TEST_SIGNED_SHAPE=plain "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_TEST_SIGNED_SHAPE=plain "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "plain Pi marker resolved '$got', expected pi" - got=$(PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_TEST_SIGNED_SHAPE=helper "$ROOT/bin/fm-harness.sh") + got=$(env -u CLAUDECODE -u GROK_AGENT PATH="$fakebin:$BASE_PATH" PI_CODING_AGENT=true FM_TEST_SIGNED_SHAPE=helper "$ROOT/bin/fm-harness.sh") [ "$got" = pi ] || fail "unrelated pi-signed-helper ancestry resolved '$got', expected pi" got=$(PATH="$fakebin:$BASE_PATH" bash -c \ @@ -887,7 +897,7 @@ new_world() { printf 'projects/\nstate/\ndata/\n.no-mistakes/\n' [ "$dispatch_ignore" = no ] || printf 'config/crew-dispatch.json\n' printf 'config/crew-harness\nconfig/secondmate-harness\nconfig/backlog-backend\n' - printf 'config/backend\nconfig/herdr-presentation-spaces\n' + printf 'config/backend\nconfig/herdr-presentation-spaces\nconfig/startup-memory-budget\n' } > "$w/main/.gitignore" printf 'v1\n' > "$w/main/AGENTS.md" printf 'r1\n' > "$w/main/README.md" @@ -1180,10 +1190,10 @@ test_bootstrap_sweep_defers_dispatch_on_stale_unignored_home() { pass "B9 bootstrap sweep defers new inherited config until the home ignores it" } -# Backward-compat: with no inherited config set, the sweep is a no-op for the -# home's config/ - exactly as before this feature - and ordinary sweep behavior -# (fast-forward) is unaffected. -test_bootstrap_sweep_no_inheritance_is_noop() { +# The primary bootstrap always materializes the startup-memory default, so an +# otherwise empty inherited surface converges that one visible value while +# ordinary tracked-file fast-forward behavior remains unchanged. +test_bootstrap_sweep_materializes_and_inherits_memory_default() { local w c1 w=$(new_world boot-noop) c1=$(git -C "$w/main" rev-parse HEAD) @@ -1197,13 +1207,16 @@ test_bootstrap_sweep_no_inheritance_is_noop() { run_bootstrap "$w" >/dev/null - [ -e "$w/sm/config/crew-dispatch.json" ] && fail "no-inheritance sweep created a home crew-dispatch.json" - [ -e "$w/sm/config/crew-harness" ] && fail "no-inheritance sweep created a home crew-harness" - [ -e "$w/sm/config/backend" ] && fail "no-inheritance sweep created a home backend" - [ -e "$w/sm/config" ] && fail "no-inheritance sweep created a home config/ dir" + [ -e "$w/sm/config/crew-dispatch.json" ] && fail "default-only sweep created a home crew-dispatch.json" + [ -e "$w/sm/config/crew-harness" ] && fail "default-only sweep created a home crew-harness" + [ -e "$w/sm/config/backend" ] && fail "default-only sweep created a home backend" + [ "$(cat "$w/home/config/startup-memory-budget")" = 7500 ] \ + || fail "primary bootstrap did not materialize the startup-memory default" + [ "$(cat "$w/sm/config/startup-memory-budget")" = 7500 ] \ + || fail "default-only sweep did not converge startup-memory-budget" [ "$(git -C "$w/sm" rev-parse HEAD)" = "$head" ] \ - || fail "no-inheritance sweep did not still fast-forward the tracked files" - pass "B10 bootstrap sweep with no inherited config is a config no-op and still fast-forwards" + || fail "default-only sweep did not still fast-forward the tracked files" + pass "B10 bootstrap sweep materializes and inherits the startup-memory default while fast-forwarding" } # config/backend: present and absent primary state converges exactly. @@ -2197,6 +2210,7 @@ cat > "$w/main/bin/fm-spawn.sh" <<SH . '$w/main/bin/fm-config-inherit-lib.sh' printf '%s' spawn >> '$log' printf '%s' codex > '$w/sm/config/crew-harness' +printf '%s\n' 7500 > '$w/sm/config/startup-memory-budget' SH chmod +x "$w/main/bin/fm-spawn.sh" fakebin=$(make_fake_toolchain "$w") @@ -2321,7 +2335,7 @@ test_spawn_fallback_chain_and_crew_scout_unaffected test_bootstrap_sweep_propagates_and_reconverges test_bootstrap_sweep_propagates_when_tracked_current test_bootstrap_sweep_defers_dispatch_on_stale_unignored_home -test_bootstrap_sweep_no_inheritance_is_noop +test_bootstrap_sweep_materializes_and_inherits_memory_default test_backend_inheritance_present_and_absent test_bootstrap_sweep_surfaces_config_propagation_failure test_bootstrap_rereads_after_partial_propagation diff --git a/tests/fm-secondmate-safety.test.sh b/tests/fm-secondmate-safety.test.sh index e1318411227..0985a2b30fa 100755 --- a/tests/fm-secondmate-safety.test.sh +++ b/tests/fm-secondmate-safety.test.sh @@ -109,6 +109,72 @@ EOF pass "seed allows overlapping project clone lists and drops the owns/owner routing" } +test_home_seed_validate_rejects_unparseable_registry_entry() { + local home err + home="$TMP_ROOT/unparseable-registry-home" + err="$TMP_ROOT/unparseable-registry.err" + mkdir -p "$home/data" + printf '%s\n' '- broken - prose (home: /tmp/child; scope: missing projects and date)' > "$home/data/secondmates.md" + if FM_HOME="$home" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null 2>"$err"; then + fail "home-seed validation accepted an operationally unparseable registry record" + fi + grep -F 'malformed secondmate registry entry' "$err" >/dev/null \ + || fail "home-seed validation did not explain the malformed registry record" + pass "home-seed validation rejects registry records no operational parser can consume" +} + +test_home_seed_refuses_broken_registry_symlink() { + local home sub err target + home="$TMP_ROOT/broken-registry-symlink-home" + sub="$TMP_ROOT/broken-registry-symlink-subhome" + err="$TMP_ROOT/broken-registry-symlink.err" + target="$home/data/missing-secondmates.md" + mkdir -p "$home/data" "$home/state" "$home/projects" + ln -s "$target" "$home/data/secondmates.md" + if FM_HOME="$home" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null 2>"$err"; then + fail "home-seed validation accepted a broken registry symlink" + fi + grep -F 'secondmate registry is unavailable or unsafe' "$err" >/dev/null \ + || fail "home-seed validation did not explain the broken registry symlink" + if FM_HOME="$home" FM_SECONDMATE_CHARTER='design domain' \ + "$ROOT/bin/fm-home-seed.sh" design "$sub" alpha >/dev/null 2>"$err"; then + fail "home seeding accepted a broken registry symlink" + fi + [ -L "$home/data/secondmates.md" ] || fail "home seeding replaced the broken registry symlink" + [ ! -e "$target" ] || fail "home seeding wrote through the broken registry symlink" + [ ! -e "$sub" ] || fail "home seeding provisioned a home before broken registry refusal" + [ ! -e "$home/data/design" ] || fail "home seeding created a brief before broken registry refusal" + pass "home seeding refuses broken registry symlinks before provisioning" +} + +test_home_seed_refuses_unreadable_registry() { + local home sub err registry + home="$TMP_ROOT/unreadable-registry-home" + sub="$TMP_ROOT/unreadable-registry-subhome" + err="$TMP_ROOT/unreadable-registry.err" + registry="$home/data/secondmates.md" + mkdir -p "$home/data" "$home/state" "$home/projects" + printf '%s\n' '- design - design domain (home: /tmp/design; scope: design; projects: alpha; added 2026-07-30)' > "$registry" + chmod 000 "$registry" + if FM_HOME="$home" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null 2>"$err"; then + chmod 600 "$registry" + fail "home-seed validation accepted an unreadable registry" + fi + grep -F 'secondmate registry is unavailable or unsafe' "$err" >/dev/null || { + chmod 600 "$registry" + fail "home-seed validation did not explain the unreadable registry" + } + if FM_HOME="$home" FM_SECONDMATE_CHARTER='design domain' \ + "$ROOT/bin/fm-home-seed.sh" design "$sub" alpha >/dev/null 2>"$err"; then + chmod 600 "$registry" + fail "home seeding accepted an unreadable registry" + fi + chmod 600 "$registry" + [ ! -e "$sub" ] || fail "home seeding provisioned a home before unreadable registry refusal" + [ ! -e "$home/data/design" ] || fail "home seeding created a brief before unreadable registry refusal" + pass "home seeding refuses unreadable registries before provisioning" +} + test_home_seed_validate_rejects_duplicate_homes() { local home subhome subhome_abs err home="$TMP_ROOT/duplicate-home" @@ -444,6 +510,94 @@ test_home_seed_no_projects_end_to_end() { pass "home seeding scaffolds, registers, and spawns a project-less home end to end" } +test_secondmate_spawn_resolves_punctuated_registry_projects() { + local home sub sub_abs fakebin log meta projects + home="$TMP_ROOT/punctuated-spawn-home" + sub="$TMP_ROOT/punctuated-spawn-subhome" + mkdir -p "$home/data" "$home/state" "$home/config" "$home/projects" + mkdir -p "$sub/data" "$sub/state" "$sub/config" "$sub/projects" + mark_firstmate_home "$sub" + printf 'punctuated\n' > "$sub/.fm-secondmate-home" + printf '# Charter\n\nHandled work.\n' > "$sub/data/charter.md" + sub_abs=$(cd "$sub" && pwd -P) + printf -- '- punctuated - launch notes (parenthetical) (home: %s; scope: launch (child); semicolon is valid; projects: alpha, beta; added 2026-07-30)' \ + "$sub_abs" > "$home/data/secondmates.md" + FM_HOME="$home" "$ROOT/bin/fm-home-seed.sh" validate >/dev/null \ + || fail "home-seed validation rejected punctuated registry fields before spawn" + fakebin=$(make_fake_tmux "$TMP_ROOT/punctuated-spawn-fake") + log="$TMP_ROOT/punctuated-spawn-fake/tmux.log" + PATH="$fakebin:$PATH" FM_HOME="$home" FM_FAKE_TMUX_LOG="$log" \ + FM_FAKE_TMUX_CAPTURE="$TMP_ROOT/punctuated-spawn-fake/pane.txt" \ + "$ROOT/bin/fm-spawn.sh" punctuated codex --secondmate >/dev/null 2>&1 \ + || fail "secondmate spawn failed for punctuated registry fields" + meta="$home/state/punctuated.meta" + projects=$(grep '^projects=' "$meta" | cut -d= -f2-) + [ "$projects" = 'alpha, beta' ] \ + || fail "secondmate spawn resolved the wrong projects field: '$projects'" + pass "secondmate spawn resolves home validation and projects from punctuated registry fields" +} + +test_secondmate_spawn_refuses_ambiguous_and_mismatched_registry_bindings() { + local row case_name home sub other fakebin log err meta_before + for row in duplicate-id unterminated-duplicate-id duplicate-home supplied-mismatch metadata-mismatch; do + case_name=${row%%|*} + home="$TMP_ROOT/spawn-binding-$case_name-home" + sub="$TMP_ROOT/spawn-binding-$case_name-sub" + other="$TMP_ROOT/spawn-binding-$case_name-other" + mkdir -p "$home/data" "$home/state" "$home/config" "$home/projects" + mark_firstmate_home "$sub" + mark_firstmate_home "$other" + printf 'domain\n' > "$sub/.fm-secondmate-home" + printf 'domain\n' > "$other/.fm-secondmate-home" + case "$case_name" in + duplicate-id) + cat > "$home/data/secondmates.md" <<EOF +- domain - primary route (home: $sub; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30) +- domain - duplicate route (home: $other; scope: duplicate; projects: beta; added 2026-07-30) +EOF + ;; + unterminated-duplicate-id) + printf -- '- domain - primary route (home: %s; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30)\n- domain - duplicate route (home: %s; scope: duplicate; projects: beta; added 2026-07-30)' \ + "$sub" "$other" > "$home/data/secondmates.md" + ;; + duplicate-home) + cat > "$home/data/secondmates.md" <<EOF +- domain - primary route (home: $sub; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30) +- other - duplicate home route (home: $sub; scope: duplicate; projects: beta; added 2026-07-30) +EOF + ;; + supplied-mismatch|metadata-mismatch) + printf -- '- domain - mismatched route (home: %s; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30)\n' \ + "$other" > "$home/data/secondmates.md" + ;; + esac + fakebin=$(make_fake_tmux "$TMP_ROOT/spawn-binding-$case_name-fake") + log="$TMP_ROOT/spawn-binding-$case_name-fake/tmux.log" + err="$TMP_ROOT/spawn-binding-$case_name.err" + if [ "$case_name" = metadata-mismatch ]; then + fm_write_secondmate_meta "$home/state/domain.meta" "$sub" + meta_before="$TMP_ROOT/spawn-binding-$case_name.meta.before" + cp "$home/state/domain.meta" "$meta_before" + if PATH="$fakebin:$PATH" FM_HOME="$home" FM_FAKE_TMUX_LOG="$log" \ + FM_FAKE_TMUX_CAPTURE="$TMP_ROOT/spawn-binding-$case_name-fake/pane.txt" \ + "$ROOT/bin/fm-spawn.sh" domain codex --secondmate >/dev/null 2>"$err"; then + fail "secondmate spawn accepted $case_name registry binding" + fi + cmp -s "$meta_before" "$home/state/domain.meta" || fail "secondmate spawn changed metadata after $case_name refusal" + else + if PATH="$fakebin:$PATH" FM_HOME="$home" FM_FAKE_TMUX_LOG="$log" \ + FM_FAKE_TMUX_CAPTURE="$TMP_ROOT/spawn-binding-$case_name-fake/pane.txt" \ + "$ROOT/bin/fm-spawn.sh" domain "$sub" codex --secondmate >/dev/null 2>"$err"; then + fail "secondmate spawn accepted $case_name registry binding" + fi + [ ! -e "$home/state/domain.meta" ] || fail "secondmate spawn wrote metadata after $case_name refusal" + fi + [ ! -e "$home/state/.spawn-domain.lock" ] || fail "secondmate spawn left a lock after $case_name refusal" + grep -F 'new-window' "$log" >/dev/null && fail "secondmate spawn created an endpoint before $case_name refusal" + done + pass "secondmate spawn refuses ambiguous, supplied-home, and metadata-home registry bindings" +} + test_home_seed_refuses_projectful_reused_charter_for_projectless_home() { local home reusable_sub stale_sub stale_brief stale_brief_before err home="$TMP_ROOT/no-projects-reused-charter-home" @@ -1316,6 +1470,53 @@ EOF pass "secondmate teardown retires empty homes and releases routing" } +test_secondmate_teardown_refuses_ambiguous_and_mismatched_registry_bindings() { + local case_name home sub other fakebin log err meta_before registry_before + for case_name in duplicate-id duplicate-home home-mismatch; do + home="$TMP_ROOT/teardown-binding-$case_name-home" + sub="$TMP_ROOT/teardown-binding-$case_name-sub" + other="$TMP_ROOT/teardown-binding-$case_name-other" + mkdir -p "$home/state" "$home/data" "$sub/state" "$sub/data" "$sub/config" "$sub/projects" "$other" + printf 'domain\n' > "$sub/.fm-secondmate-home" + fm_write_secondmate_meta "$home/state/domain.meta" "$sub" + case "$case_name" in + duplicate-id) + cat > "$home/data/secondmates.md" <<EOF +- domain - primary route (home: $sub; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30) +- domain - duplicate route (home: $other; scope: duplicate; projects: beta; added 2026-07-30) +EOF + ;; + duplicate-home) + cat > "$home/data/secondmates.md" <<EOF +- domain - primary route (home: $sub; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30) +- other - duplicate home route (home: $sub; scope: duplicate; projects: beta; added 2026-07-30) +EOF + ;; + home-mismatch) + printf -- '- domain - mismatched route (home: %s; scope: valid (scope); punctuation; projects: alpha; added 2026-07-30)\n' \ + "$other" > "$home/data/secondmates.md" + ;; + esac + meta_before="$TMP_ROOT/teardown-binding-$case_name.meta.before" + registry_before="$TMP_ROOT/teardown-binding-$case_name.registry.before" + cp "$home/state/domain.meta" "$meta_before" + cp "$home/data/secondmates.md" "$registry_before" + fakebin=$(make_fake_tmux "$TMP_ROOT/teardown-binding-$case_name-fake") + log="$TMP_ROOT/teardown-binding-$case_name-fake/tmux.log" + err="$TMP_ROOT/teardown-binding-$case_name.err" + if PATH="$fakebin:$PATH" FM_HOME="$home" FM_FAKE_TMUX_LOG="$log" \ + FM_FAKE_TMUX_CAPTURE="$TMP_ROOT/teardown-binding-$case_name-fake/pane.txt" \ + "$ROOT/bin/fm-teardown.sh" domain --force >/dev/null 2>"$err"; then + fail "secondmate teardown accepted $case_name registry binding" + fi + [ -d "$sub" ] || fail "secondmate teardown removed the home after $case_name refusal" + cmp -s "$meta_before" "$home/state/domain.meta" || fail "secondmate teardown changed metadata after $case_name refusal" + cmp -s "$registry_before" "$home/data/secondmates.md" || fail "secondmate teardown changed registry after $case_name refusal" + grep -F 'kill-window' "$log" >/dev/null && fail "secondmate teardown killed an endpoint before $case_name refusal" + done + pass "secondmate teardown refuses ambiguous and identity-mismatched registry bindings" +} + test_secondmate_teardown_refuses_failed_leased_home_return() { local home subhome subhome_abs fakebin log fmroot err rc home="$TMP_ROOT/teardown-return-fail-home" @@ -2167,6 +2368,9 @@ EOF test_fm_home_parameterization test_lock_status_is_per_home test_seed_allows_overlapping_clones_and_drops_owner +test_home_seed_validate_rejects_unparseable_registry_entry +test_home_seed_refuses_broken_registry_symlink +test_home_seed_refuses_unreadable_registry test_home_seed_validate_rejects_duplicate_homes test_home_seed_validate_rejects_duplicate_ids test_home_seed_validate_rejects_nested_homes @@ -2179,6 +2383,8 @@ test_home_seed_refuses_missing_filled_charter test_home_seed_refuses_placeholder_charter test_home_seed_refuses_empty_charter_fields test_home_seed_no_projects_end_to_end +test_secondmate_spawn_resolves_punctuated_registry_projects +test_secondmate_spawn_refuses_ambiguous_and_mismatched_registry_bindings test_home_seed_refuses_projectful_reused_charter_for_projectless_home test_home_seed_refuses_projectless_conversion_of_populated_home test_home_seed_refuses_projectless_home_with_uninspectable_projects @@ -2205,6 +2411,7 @@ test_secondmate_spawn_requires_seeded_matching_home test_secondmate_spawn_refuses_operational_dirs_outside_subhome test_fm_send_refuses_bare_window_without_home_meta test_secondmate_teardown_retires_empty_home +test_secondmate_teardown_refuses_ambiguous_and_mismatched_registry_bindings test_secondmate_teardown_refuses_failed_leased_home_return test_secondmate_teardown_removes_plain_clone_home_without_treehouse_return test_secondmate_force_teardown_discards_child_work diff --git a/tests/fm-secondmate-sync.test.sh b/tests/fm-secondmate-sync.test.sh index 999aebc2df3..d67350a1e70 100755 --- a/tests/fm-secondmate-sync.test.sh +++ b/tests/fm-secondmate-sync.test.sh @@ -347,6 +347,9 @@ SH chmod +x "$fakebin/tasks-axi" cat > "$fakebin/quota-axi" <<'SH' #!/usr/bin/env bash +if [ "${1:-}" = --version ]; then + printf '%s\n' 'quota-axi 0.1.16 (fake)' +fi exit 0 SH chmod +x "$fakebin/quota-axi" diff --git a/tests/fm-send-settle.test.sh b/tests/fm-send-settle.test.sh index 01d2d427e7b..3961bfe85ae 100755 --- a/tests/fm-send-settle.test.sh +++ b/tests/fm-send-settle.test.sh @@ -16,6 +16,8 @@ set -u # shellcheck source=tests/lib.sh . "$(dirname "${BASH_SOURCE[0]}")/lib.sh" +# shellcheck source=/dev/null +. "$ROOT/bin/fm-busy-lib.sh" SEND="$ROOT/bin/fm-send.sh" @@ -116,7 +118,29 @@ test_key_path_never_pauses() { pass "fm-send: the --key path never pauses (settle scoped to text submit)" } +test_claude_escape_records_interrupt_idle() { + local dir fb log rc home gen out + dir="$TMP_ROOT/claude-interrupt"; mkdir -p "$dir" + fb=$(make_stubs "$dir"); log="$dir/sleep.log" + home="$dir/home"; mkdir -p "$home/state" + fm_write_meta "$home/state/task.meta" \ + "window=sess:win" "worktree=$home/wt" "project=$home/project" \ + "harness=claude" "kind=ship" "mode=no-mistakes" "yolo=off" + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$home/state" task) + printf 'busy_gen=%s\n' "$gen" >> "$home/state/task.meta" + : > "$log" + + env PATH="$fb:$PATH" FM_HOME="$home" FM_SLEEP_LOG="$log" \ + "$SEND" task --key Escape 2>/dev/null; rc=$? + expect_code 0 "$rc" "Claude Escape send should succeed" + out=$(fm_busy_classify tmux sess:win claude task "$home/state") + [ "$out" = "idle fm-interrupt" ] \ + || fail "Claude Escape must classify idle/fm-interrupt, got '$out'" + pass "fm-send: a successful Claude Escape records the interrupt lifecycle edge" +} + test_default_send_pauses_one_second test_zero_disables_pause test_pause_is_tunable test_key_path_never_pauses +test_claude_escape_records_interrupt_idle diff --git a/tests/fm-session-start.test.sh b/tests/fm-session-start.test.sh index 5b13895f5d3..061145263a8 100755 --- a/tests/fm-session-start.test.sh +++ b/tests/fm-session-start.test.sh @@ -318,6 +318,9 @@ SH make_fake_herdr_secondmate_recovery() { local fakebin=$1 + # The recovery kill now requires the shared named-session lock and an exact + # focus snapshot. Keep a focused sibling tab so this test's husk close is + # provably non-workspace-emptying and never needs to signal a fake shell pid. cat > "$fakebin/herdr" <<'SH' #!/usr/bin/env bash set -u @@ -331,16 +334,19 @@ case "${1:-} ${2:-}" in "status --json") printf '%s\n' '{"client":{"protocol":14,"version":"test"},"server":{"running":true}}' ;; + "session list") + printf '{"sessions":[{"name":"default","running":true,"socket_path":"%s.sock"}]}\n' "$state" + ;; "workspace list") - printf '{"result":{"workspaces":[{"workspace_id":"ws1","label":"2ndmate-%s"}]}}\n' "$mate_id" + printf '{"result":{"workspaces":[{"workspace_id":"ws1","label":"2ndmate-%s","focused":true,"active_tab_id":"t-focus"}]}}\n' "$mate_id" ;; "tab list") if [ -e "$spawned" ]; then - printf '{"result":{"tabs":[{"tab_id":"t-new","workspace_id":"ws1","label":"fm-%s"}]}}\n' "$mate_id" + printf '{"result":{"tabs":[{"tab_id":"t-focus","workspace_id":"ws1","label":"captain","focused":true},{"tab_id":"t-new","workspace_id":"ws1","label":"fm-%s","focused":false}]}}\n' "$mate_id" elif [ -e "$killed" ]; then - printf '%s\n' '{"result":{"tabs":[]}}' + printf '%s\n' '{"result":{"tabs":[{"tab_id":"t-focus","workspace_id":"ws1","label":"captain","focused":true}]}}' else - printf '{"result":{"tabs":[{"tab_id":"t-old","workspace_id":"ws1","label":"fm-%s"}]}}\n' "$mate_id" + printf '{"result":{"tabs":[{"tab_id":"t-focus","workspace_id":"ws1","label":"captain","focused":true},{"tab_id":"t-old","workspace_id":"ws1","label":"fm-%s","focused":false}]}}\n' "$mate_id" fi ;; "tab create") @@ -359,9 +365,9 @@ case "${1:-} ${2:-}" in "pane get") pane=${3:-} if [ "$pane" = p-new ] && [ -e "$spawned" ]; then - printf '%s\n' '{"result":{"pane":{"pane_id":"p-new"}}}' + printf '%s\n' '{"result":{"pane":{"pane_id":"p-new","tab_id":"t-new","workspace_id":"ws1"}}}' elif [ "$pane" = p-old ] && [ ! -e "$killed" ]; then - printf '%s\n' '{"result":{"pane":{"pane_id":"p-old"}}}' + printf '%s\n' '{"result":{"pane":{"pane_id":"p-old","tab_id":"t-old","workspace_id":"ws1"}}}' else printf '%s\n' '{"error":{"code":"pane_not_found"}}' >&2 exit 1 diff --git a/tests/fm-spawn-dispatch-profile.test.sh b/tests/fm-spawn-dispatch-profile.test.sh index 01da39d8b18..ad32c1f8ff5 100755 --- a/tests/fm-spawn-dispatch-profile.test.sh +++ b/tests/fm-spawn-dispatch-profile.test.sh @@ -529,6 +529,18 @@ test_pi_signed_threads_shared_pi_profile_and_preserves_identity() { assert_contains "$launch" "fm-operational-input.sh' encode launch-brief" \ "pi-signed launch lost the canonical typed launch-brief envelope" assert_present "$HOME_DIR/state/$id.pi-ext.ts" "pi-signed launch did not install Pi's turn-end extension" + assert_present "$HOME_DIR/state/$id.busy-gen" "pi-signed spawn did not arm the busy-state contract" + assert_contains "$(cat "$HOME_DIR/state/$id.busy-state")" "state=busy source=fm-spawn" \ + "pi-signed spawn did not seed the busy-state record from the launch brief" + local ext gen + ext=$(cat "$HOME_DIR/state/$id.pi-ext.ts") + gen=$(cat "$HOME_DIR/state/$id.busy-gen") + assert_contains "$ext" 'pi.on("agent_start"' "pi extension lost the semantic agent_start busy edge" + assert_contains "$ext" 'pi.on("agent_settled"' "pi extension lost the semantic agent_settled idle edge" + assert_contains "$ext" 'ctx.isIdle()' "pi extension no longer confirms idle with ctx.isIdle()" + assert_contains "$ext" "\"--gen\", \"$gen\"" "pi extension does not carry the armed incarnation gen" + assert_contains "$ext" '"--source", "pi-ext"' "pi extension does not attribute its semantic source" + assert_contains "$ext" 'pi.on("turn_end"' "pi extension lost the turn-end notification touch" pass "pi-signed shares Pi launch semantics while preserving its configured and recorded identity" } diff --git a/tests/fm-startup-memory-budget.test.sh b/tests/fm-startup-memory-budget.test.sh new file mode 100755 index 00000000000..59eeb0649b7 --- /dev/null +++ b/tests/fm-startup-memory-budget.test.sh @@ -0,0 +1,317 @@ +#!/usr/bin/env bash +# Behavioral coverage for the visible startup-memory budget, its safe parser, +# accounting command, primary-to-secondmate convergence, and exact reread bytes. +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +BASE_PATH=${FM_TEST_BASE_PATH:-/usr/bin:/bin:/usr/sbin:/sbin} +TMP_ROOT=$(fm_test_tmproot fm-startup-memory-budget) +BUDGET="$ROOT/bin/fm-startup-memory-budget.sh" +BOOTSTRAP="$ROOT/bin/fm-bootstrap.sh" +CONFIG_PUSH="$ROOT/bin/fm-config-push.sh" + +make_fake_toolchain() { + local dir=$1 fakebin + fakebin=$(fm_fakebin "$dir") + fm_fake_exit0 "$fakebin" node gh-axi chrome-devtools-axi lavish-axi quota-axi + cat > "$fakebin/quota-axi" <<'SH' +#!/usr/bin/env bash +if [ "${1:-}" = --version ]; then + printf '%s\n' 'quota-axi 0.1.16 (fake)' +fi +exit 0 +SH + cat > "$fakebin/gh" <<'SH' +#!/usr/bin/env bash +exit 0 +SH + cat > "$fakebin/treehouse" <<'SH' +#!/usr/bin/env bash +if [ "${1:-}" = get ] && [ "${2:-}" = --help ]; then + printf '%s\n' 'Usage: treehouse get [--lease]' +fi +SH + cat > "$fakebin/no-mistakes" <<'SH' +#!/usr/bin/env bash +if [ "${1:-}" = --version ]; then + printf '%s\n' 'no-mistakes version v1.31.2 (fake)' +fi +SH + cat > "$fakebin/tasks-axi" <<'SH' +#!/usr/bin/env bash +case "${1:-}:${2:-}" in + --version:*) printf '%s\n' '0.2.3' ;; + update:--help) printf '%s\n' '--archive-body' ;; + mv:--help) printf '%s\n' 'usage: tasks-axi mv <id> [<id>...]' ;; +esac +SH + cat > "$fakebin/tmux" <<'SH' +#!/usr/bin/env bash +[ -z "${FM_FAKE_TMUX_LOG:-}" ] || printf '%s\n' "$*" >> "$FM_FAKE_TMUX_LOG" +case "$*" in + *display-message*'#{pane_current_command}'*) printf '%s\n' codex ;; + *display-message*'#{pane_id}'*) printf '%s\n' '%1' ;; + *display-message*'#{cursor_y}'*) printf '%s\n' 0 ;; + *capture-pane*) printf '\n' ;; +esac +exit 0 +SH + chmod +x "$fakebin"/* + printf '%s\n' "$fakebin" +} + +new_bootstrap_world() { + local name=$1 world root home + world="$TMP_ROOT/$name" + root="$world/root" + home="$world/home" + mkdir -p "$home/config" "$home/data" "$home/state" "$root/bin" + git init -q -b main "$root" + printf '%s\n' 'config/' > "$root/.gitignore" + printf '%s\n' '# Firstmate test root' > "$root/AGENTS.md" + printf '%s\n' '#!/usr/bin/env bash' 'exit 0' > "$root/bin/placeholder.sh" + chmod +x "$root/bin/placeholder.sh" + git -C "$root" add -A + git -C "$root" -c user.name=fmtest -c user.email=fmtest@example.invalid commit -qm initial + printf '%s|%s\n' "$root" "$home" +} + +run_bootstrap() { + local root=$1 home=$2 fakebin=$3 + PATH="$fakebin:$BASE_PATH" FM_BACKEND=tmux FM_HOME="$home" FM_ROOT_OVERRIDE="$root" \ + "$BOOTSTRAP" +} + +test_primary_bootstrap_materializes_visible_default() { + local rec root home fakebin out second + rec=$(new_bootstrap_world materialize) + root=${rec%%|*} + home=${rec#*|} + fakebin=$(make_fake_toolchain "$TMP_ROOT/materialize") + + out=$(run_bootstrap "$root" "$home" "$fakebin") + [ -z "$out" ] || fail "default materialization should stay quiet, got: $out" + [ "$(<"$home/config/startup-memory-budget")" = 7500 ] \ + || fail "bootstrap did not materialize the visible 7500 default" + [ "$(FM_HOME="$home" "$BUDGET" read)" = 7500 ] \ + || fail "read command did not expose the generated default" + + printf '321\n' > "$home/config/startup-memory-budget" + run_bootstrap "$root" "$home" "$fakebin" >/dev/null + [ "$(<"$home/config/startup-memory-budget")" = 321 ] \ + || fail "bootstrap replaced a valid captain-selected budget" + + second="$TMP_ROOT/materialize/secondmate" + mkdir -p "$second/config" "$second/data" "$second/state" + printf '%s\n' sm > "$second/.fm-secondmate-home" + run_bootstrap "$root" "$second" "$fakebin" >/dev/null + [ ! -e "$second/config/startup-memory-budget" ] \ + || fail "secondmate bootstrap created an independent budget instead of awaiting inheritance" + pass "primary bootstrap materializes only the visible default and preserves valid captain choices" +} + +expect_rejected_read() { + local home=$1 expected=$2 out rc + set +e + out=$(FM_HOME="$home" "$BUDGET" read 2>&1) + rc=$? + set -e + [ "$rc" -ne 0 ] || fail "unsafe budget unexpectedly parsed: $expected" + assert_contains "$out" "$expected" "unsafe budget rejection was not specific" +} + +test_safe_parser_rejects_ambiguous_and_unsafe_values() { + local home outside + home="$TMP_ROOT/parser-home" + mkdir -p "$home/config" "$home/data" + printf '42\n' > "$home/config/startup-memory-budget" + [ "$(FM_HOME="$home" "$BUDGET" read)" = 42 ] || fail "valid positive decimal budget was rejected" + + printf '0\n' > "$home/config/startup-memory-budget" + expect_rejected_read "$home" 'value must be one positive decimal integer' + printf '42\nextra\n' > "$home/config/startup-memory-budget" + expect_rejected_read "$home" 'value must be one positive decimal integer' + printf '+42\n' > "$home/config/startup-memory-budget" + expect_rejected_read "$home" 'value must be one positive decimal integer' + + outside="$TMP_ROOT/parser-outside" + printf '77\n' > "$outside" + rm -f "$home/config/startup-memory-budget" + ln -s "$outside" "$home/config/startup-memory-budget" + expect_rejected_read "$home" 'file is symlinked' + [ "$(<"$outside")" = 77 ] || fail "symlink rejection changed its external target" + + rm -f "$home/config/startup-memory-budget" + ln "$outside" "$home/config/startup-memory-budget" + expect_rejected_read "$home" 'file is hardlinked' + [ "$(<"$outside")" = 77 ] || fail "hardlink rejection changed its external source" + + rm -f "$home/config/startup-memory-budget" + rm -rf "$home/config" + ln -s "$TMP_ROOT/parser-config-target" "$home/config" + mkdir -p "$TMP_ROOT/parser-config-target" + printf '88\n' > "$TMP_ROOT/parser-config-target/startup-memory-budget" + expect_rejected_read "$home" 'config directory is symlinked' + pass "budget parser accepts one exact positive value and rejects malformed or unsafe inputs" +} + +test_budget_accounting_reports_all_three_files_and_safe_failure() { + local home out rc outside + home="$TMP_ROOT/accounting-home" + mkdir -p "$home/config" "$home/data" + printf '10\n' > "$home/config/startup-memory-budget" + printf 'abc\n' > "$home/data/captain.md" + printf 'abcdef\n' > "$home/data/captain-shared.md" + + out=$(FM_HOME="$home" "$BUDGET" report) + assert_contains "$out" 'estimator=ceil(UTF-8 bytes / 3) conservative-local-estimate' \ + "report did not name the stable estimator" + assert_contains "$out" 'file=data/captain.md bytes=4 estimated_tokens=2 status=present' \ + "report did not account for captain memory" + assert_contains "$out" 'file=data/captain-shared.md bytes=7 estimated_tokens=3 status=present' \ + "report did not account for shared memory" + assert_contains "$out" 'file=data/learnings.md bytes=0 estimated_tokens=0 status=absent' \ + "report did not account for absent learnings" + assert_contains "$out" 'total_estimated_tokens=5' "report total was not the sum of all three files" + assert_contains "$out" 'budget_status=within-budget' "report did not classify the initial total" + + printf 'abcdefabcdefabcdefabcdef\n' > "$home/data/learnings.md" + out=$(FM_HOME="$home" "$BUDGET" report) + assert_contains "$out" 'budget_status=over-budget' "report did not surface an over-budget total" + + outside="$TMP_ROOT/accounting-outside" + printf 'outside\n' > "$outside" + rm -f "$home/data/captain.md" + ln -s "$outside" "$home/data/captain.md" + set +e + out=$(FM_HOME="$home" "$BUDGET" report 2>&1) + rc=$? + set -e + expect_code 2 "$rc" "unsafe memory input should fail the accounting command" + assert_contains "$out" 'memory file is not an ordinary regular file' \ + "accounting failure did not identify the unsafe memory file" + [ "$(<"$outside")" = outside ] || fail "accounting failure changed a symlink target" + pass "budget accounting sums the three startup files and reports safe failures" +} + +new_propagation_world() { + local world=$1 root="$1/root" home="$1/home" sm="$1/sm" head + mkdir -p "$home/config" "$home/data" "$home/state" "$root/bin" + touch "$home/state/.last-watcher-beat" + git init -q -b main "$root" + printf '%s\n' 'config/' > "$root/.gitignore" + printf '%s\n' '# Firstmate test root' > "$root/AGENTS.md" + printf '%s\n' '#!/usr/bin/env bash' 'exit 0' > "$root/bin/placeholder.sh" + chmod +x "$root/bin/placeholder.sh" + git -C "$root" add -A + git -C "$root" -c user.name=fmtest -c user.email=fmtest@example.invalid commit -qm initial + head=$(git -C "$root" rev-parse HEAD) + git -C "$root" worktree add -q --detach "$sm" "$head" + printf '%s\n' sm > "$sm/.fm-secondmate-home" + mkdir -p "$sm/config" "$sm/data" "$sm/state" "$sm/projects" + { + printf 'window=firstmate:fm-sm\n' + printf 'kind=secondmate\n' + printf 'harness=codex\n' + printf 'home=%s\n' "$sm" + } > "$home/state/sm.meta" + printf '%s|%s|%s\n' "$root" "$home" "$sm" +} + +latest_reread_instruction() { + local home=$1 state path latest= + state=$(cd "$home/state" && pwd -P) || return 1 + for path in "$state"/.fm-inherited-config-reread.*; do + case "$path" in *.pending) continue ;; esac + [ -f "$path" ] && [ ! -L "$path" ] || continue + latest=$path + done + [ -n "$latest" ] || return 1 + printf '%s\n' "$latest" +} + +run_config_push() { + local root=$1 home=$2 fakebin=$3 log=$4 + PATH="$fakebin:$BASE_PATH" FM_HOME="$home" FM_ROOT_OVERRIDE="$root" FM_SEND_SETTLE=0 \ + FM_FAKE_TMUX_LOG="$log" "$CONFIG_PUSH" +} + +test_primary_budget_converges_with_exact_reread_and_safe_failures() { + local world="$TMP_ROOT/propagation" rec root home sm fakebin log out rc instruction expected outside + mkdir -p "$world" + rec=$(new_propagation_world "$world") + root=${rec%%|*} + rec=${rec#*|} + home=${rec%%|*} + sm=${rec#*|} + fakebin=$(make_fake_toolchain "$world") + log="$world/tmux.log" + + printf '321\n' > "$home/config/startup-memory-budget" + out=$(run_config_push "$root" "$home" "$fakebin" "$log") + assert_contains "$out" 'startup-memory-budget: pushed' \ + "config push did not report the new budget as inherited" + [ "$(<"$sm/config/startup-memory-budget")" = 321 ] \ + || fail "secondmate did not receive the primary budget bytes" + instruction=$(latest_reread_instruction "$sm") || fail "budget propagation did not publish a reread instruction" + expected=$(printf '%s\n\n%s\n%s\n321\n%s' \ + 'These inherited config files changed. Re-read and apply their exact contents at every future intake. They are defaults/rules and do not remove your judgment to choose differently when warranted.' \ + 'config/startup-memory-budget' \ + '-----BEGIN config/startup-memory-budget-----' \ + '-----END config/startup-memory-budget-----') + [ "$(<"$instruction")" = "$expected" ] \ + || fail "budget reread payload was not the exact destination bytes" + assert_contains "$(<"$log")" "CONFIG_REREAD: $instruction" \ + "budget propagation did not send the pointer to its exact reread generation" + + outside="$world/unsafe-budget" + printf '555\n' > "$outside" + rm -f "$sm/config/startup-memory-budget" + ln "$outside" "$sm/config/startup-memory-budget" + set +e + out=$(run_config_push "$root" "$home" "$fakebin" "$log" 2>&1) + rc=$? + set -e + expect_code 1 "$rc" "unsafe inherited destination should stop propagation" + assert_contains "$out" 'startup-memory-budget: error - unsafe or invalid destination: file is hardlinked' \ + "unsafe inherited destination did not produce a concrete propagation error" + [ "$(<"$outside")" = 555 ] || fail "unsafe destination handling changed its hardlinked source" + rm -f "$sm/config/startup-memory-budget" + run_config_push "$root" "$home" "$fakebin" "$log" >/dev/null + [ "$(<"$sm/config/startup-memory-budget")" = 321 ] \ + || fail "safe retry did not restore the converged primary budget" + + rm -f "$home/config/startup-memory-budget" + out=$(run_config_push "$root" "$home" "$fakebin" "$log") + assert_contains "$out" 'startup-memory-budget: pushed - mirrored primary absence' \ + "primary absence was not reported as a converging removal" + [ ! -e "$sm/config/startup-memory-budget" ] \ + || fail "primary absence did not remove the inherited budget" + instruction=$(latest_reread_instruction "$sm") || fail "budget absence did not publish a reread instruction" + assert_contains "$(<"$instruction")" $'-----BEGIN config/startup-memory-budget-----\nABSENT\n-----END config/startup-memory-budget-----' \ + "budget absence reread did not use the explicit ABSENT payload" + + rm -f "$sm/config/startup-memory-budget" + printf '555\n' > "$outside" + ln -s "$outside" "$home/config/startup-memory-budget" + set +e + out=$(run_config_push "$root" "$home" "$fakebin" "$log" 2>&1) + rc=$? + set -e + expect_code 1 "$rc" "unsafe primary budget should stop propagation" + assert_contains "$out" 'startup-memory-budget: error - unsafe or invalid primary source: file is symlinked' \ + "unsafe primary budget did not produce a concrete propagation error" + [ ! -e "$sm/config/startup-memory-budget" ] \ + || fail "unsafe primary budget changed the converged secondmate copy" + [ "$(<"$outside")" = 555 ] || fail "unsafe primary budget handling changed its symlink target" + pass "budget propagation converges through config push with exact rereads, absence, and safe rejection" +} + +test_primary_bootstrap_materializes_visible_default +test_safe_parser_rejects_ambiguous_and_unsafe_values +test_budget_accounting_reports_all_three_files_and_safe_failure +test_primary_budget_converges_with_exact_reread_and_safe_failures + +echo '# all fm-startup-memory-budget tests passed' diff --git a/tests/fm-teardown.test.sh b/tests/fm-teardown.test.sh index 9c5e2672a0e..f033eb7fdf5 100755 --- a/tests/fm-teardown.test.sh +++ b/tests/fm-teardown.test.sh @@ -1351,6 +1351,27 @@ test_local_only_force_overrides_unpushed() { pass "local-only worktree with unpushed work is torn down under --force (escape hatch)" } +test_teardown_missing_busy_sidecar_completes() { + local case_dir gen rc + case_dir=$(make_case missing-busy-sidecar) + write_meta "$case_dir" local-only ship + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$case_dir/state" task-x1) + printf 'busy_gen=%s\n' "$gen" >> "$case_dir/state/task-x1.meta" + rm -f "$case_dir/state/task-x1.busy-gen" + + set +e + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" + rc=$? + set -e + + expect_code 0 "$rc" "missing-busy-sidecar: teardown should treat the incarnation as already retired" + assert_absent "$case_dir/state/task-x1.busy-state" \ + "missing-busy-sidecar: teardown left the orphan busy record" + assert_absent "$case_dir/state/task-x1.meta" \ + "missing-busy-sidecar: teardown remained incomplete" + pass "teardown completes when an exact busy-state sidecar is already absent" +} + test_herdr_teardown_clears_escalation_marker() { local case_dir marker case_dir=$(make_case herdr-marker-cleanup) @@ -1363,20 +1384,451 @@ test_herdr_teardown_clears_escalation_marker() { 'herdr_workspace_id=wG' \ 'herdr_tab_id=wG:tQ' \ 'herdr_pane_id=wG:pQ' >> "$case_dir/state/task-x1.meta" - cat > "$case_dir/fakebin/herdr" <<'SH' + # A reachable session whose exact pane is already structurally gone: the + # locked close is a no-op and the record gate sees a confirmed-gone pane. + cat > "$case_dir/fakebin/herdr" <<SH #!/usr/bin/env bash -exit 0 +case "\${1:-} \${2:-}" in + "session list") printf '%s\n' '{"sessions":[{"name":"default","running":true,"socket_path":"$case_dir/herdr.sock"}]}' ;; + "status --json") printf '%s\n' '{"server":{"running":true}}' ;; + "pane get") printf '%s\n' '{"error":{"code":"pane_not_found"}}'; exit 1 ;; + *) exit 0 ;; +esac SH chmod +x "$case_dir/fakebin/herdr" marker="$case_dir/state/.herdr-escalated-default_wG_pQ" : > "$marker" run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" \ - || fail "herdr-marker-cleanup: forced teardown failed" + || fail "herdr-marker-cleanup: forced teardown failed: $(cat "$case_dir/stderr")" [ ! -e "$marker" ] || fail "herdr-marker-cleanup: teardown left the pane's escalation marker behind" pass "herdr teardown removes pane-owned escalation dedupe state" } +# Flat (non-projected) Herdr endpoint whose fake pane exists until a locked +# close removes it. The socket path is case-local so the derived presentation +# lock never collides with another test or a real fleet session. +configure_flat_herdr_teardown_case() { # <case-dir> + local case_dir=$1 + sed -i.bak 's/^window=.*/window=default:wG:pQ/' "$case_dir/state/task-x1.meta" + rm -f "$case_dir/state/task-x1.meta.bak" + printf '%s\n' \ + 'backend=herdr' \ + 'herdr_session=default' \ + 'herdr_workspace_id=wG' \ + 'herdr_tab_id=wG:tQ' \ + 'herdr_pane_id=wG:pQ' >> "$case_dir/state/task-x1.meta" + cat > "$case_dir/fakebin/herdr" <<SH +#!/usr/bin/env bash +set -u +printf '%s\n' "\$*" >> "\${FM_FAKE_HERDR_LOG:?}" +case "\${1:-} \${2:-}" in + "workspace list") + printf '%s\n' '{"result":{"workspaces":[{"workspace_id":"wH","active_tab_id":"wH:t1","focused":true},{"workspace_id":"wG","active_tab_id":"wG:tQ","focused":false}]}}' + ;; + "tab list") + case "\$*" in + *"--workspace wH"*) printf '%s\n' '{"result":{"tabs":[{"tab_id":"wH:t1","focused":true}]}}' ;; + *"--workspace wG"*) printf '%s\n' '{"result":{"tabs":[{"tab_id":"wG:tQ","workspace_id":"wG"}]}}' ;; + *) printf '%s\n' '{"result":{"tabs":[]}}' ;; + esac + ;; + "pane list") + printf '%s\n' '{"result":{"panes":[{"pane_id":"wG:pQ","tab_id":"wG:tQ"}]}}' + ;; + "status --json") + printf '%s\n' '{"server":{"running":true}}' + ;; + "session list") + if [ "\${FM_FAKE_HERDR_SESSION_LIST_GARBAGE:-0}" = 1 ]; then + printf '%s\n' 'not-json' + else + printf '%s\n' '{"sessions":[{"name":"default","running":true,"socket_path":"$case_dir/herdr.sock"}]}' + fi + ;; + "pane close") + : > "\${FM_FAKE_HERDR_CLOSED:?}" + ;; + "pane get") + if [ "\${FM_FAKE_HERDR_PANE_GET_GARBAGE:-0}" = 1 ]; then + printf '%s\n' 'not-json' + exit 0 + fi + if [ -e "\${FM_FAKE_HERDR_CLOSED:?}" ]; then + printf '%s\n' '{"error":{"code":"pane_not_found"}}' >&2 + exit 1 + fi + printf '%s\n' '{"result":{"pane":{"pane_id":"wG:pQ","tab_id":"wG:tQ","workspace_id":"wG"}}}' + ;; + "agent get") + printf '%s\n' '{"error":{"code":"agent_not_found"}}' >&2 + exit 1 + ;; +esac +SH + chmod +x "$case_dir/fakebin/herdr" +} + +test_herdr_flat_teardown_refuses_orphaning_records_then_retry_completes() { + local case_dir log closed lock ready release holder_pid rc thlog + case_dir=$(make_case herdr-orphan-refusal) + write_meta "$case_dir" local-only ship + configure_flat_herdr_teardown_case "$case_dir" + log="$case_dir/herdr.log"; : > "$log" + closed="$case_dir/closed" + : > "$case_dir/state/task-x1.status" + : > "$case_dir/state/task-x1.turn-ended" + # Record every treehouse invocation: the contended-lock refusal must fire + # BEFORE the isolated copy is returned, so phase 1 may not invoke it at all. + thlog="$case_dir/treehouse.log"; : > "$thlog" + cat > "$case_dir/fakebin/treehouse" <<SH +#!/usr/bin/env bash +printf '%s\n' "\$*" >> "$thlog" +exit 0 +SH + chmod +x "$case_dir/fakebin/treehouse" + + lock=$(FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" PATH="$case_dir/fakebin:$PATH" \ + bash -c '. "$0/bin/backends/herdr.sh"; fm_backend_herdr_presentation_session_lock_path default' "$ROOT") \ + || fail "herdr-orphan-refusal: could not resolve the fixture presentation lock path" + ready="$case_dir/lock-ready"; release="$case_dir/lock-release" + ROOT="$ROOT" LOCK="$lock" READY="$ready" RELEASE="$release" bash -c ' + . "$ROOT/bin/fm-wake-lib.sh" + fm_lock_try_acquire "$LOCK" || exit 1 + : > "$READY" + while [ ! -e "$RELEASE" ]; do sleep 0.1; done + fm_lock_release "$LOCK" + ' & + holder_pid=$! + local waited=0 + while [ ! -e "$ready" ] && [ "$waited" -lt 50 ]; do sleep 0.1; waited=$((waited + 1)); done + [ -e "$ready" ] || fail "herdr-orphan-refusal: the contending lock holder never started" + + rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + if [ "$rc" -eq 0 ]; then + : > "$release"; wait "$holder_pid" 2>/dev/null || true + fail "herdr-orphan-refusal: teardown reported success while the exact pane still existed under lock contention" + fi + [ -e "$case_dir/state/task-x1.meta" ] || { : > "$release"; fail "herdr-orphan-refusal: refusal erased the durable endpoint metadata"; } + [ -e "$case_dir/state/task-x1.status" ] || { : > "$release"; fail "herdr-orphan-refusal: refusal erased the task status record"; } + [ -e "$case_dir/state/task-x1.turn-ended" ] || { : > "$release"; fail "herdr-orphan-refusal: refusal erased the turn-end record"; } + assert_grep "presentation lock is contended" "$case_dir/stderr" \ + "herdr-orphan-refusal: the pre-return refusal was not explained visibly" + if [ -s "$thlog" ]; then + : > "$release"; fail "herdr-orphan-refusal: the contended refusal still returned the isolated copy: $(cat "$thlog")" + fi + [ -d "$case_dir/wt" ] || { : > "$release"; fail "herdr-orphan-refusal: the contended refusal removed the isolated copy"; } + if [ "$(git -C "$case_dir/wt" rev-parse --abbrev-ref HEAD 2>/dev/null)" != "fm/task-x1" ]; then + : > "$release"; fail "herdr-orphan-refusal: the contended refusal dropped the task branch before refusing" + fi + if grep -q "teardown task-x1 complete" "$case_dir/stdout"; then + : > "$release"; fail "herdr-orphan-refusal: refusal still reported cleanup complete" + fi + if grep -q "^pane close" "$log"; then + : > "$release"; fail "herdr-orphan-refusal: an unlocked pane close was attempted under contention" + fi + + : > "$release" + wait "$holder_pid" 2>/dev/null || true + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=1 \ + run_teardown "$case_dir" --force > "$case_dir/stdout2" 2> "$case_dir/stderr2" \ + || fail "herdr-orphan-refusal: the retry after lock release failed: $(cat "$case_dir/stderr2")" + [ -e "$closed" ] || fail "herdr-orphan-refusal: the retry never closed the pane under the lock" + [ -s "$thlog" ] || fail "herdr-orphan-refusal: the successful retry never returned the isolated copy" + [ ! -e "$case_dir/state/task-x1.meta" ] || fail "herdr-orphan-refusal: the successful retry left the metadata behind" + [ ! -e "$case_dir/state/task-x1.status" ] || fail "herdr-orphan-refusal: the successful retry left the status record behind" + grep -q "teardown task-x1 complete" "$case_dir/stdout2" \ + || fail "herdr-orphan-refusal: the successful retry did not report completion" + pass "herdr flat teardown refuses before returning the isolated copy under lock contention and the retry completes cleanly" +} + +test_herdr_flat_teardown_refuses_records_on_unparseable_presence() { + local case_dir log closed rc + case_dir=$(make_case herdr-garbage-presence) + write_meta "$case_dir" local-only ship + configure_flat_herdr_teardown_case "$case_dir" + log="$case_dir/herdr.log"; : > "$log" + closed="$case_dir/closed" + : > "$case_dir/state/task-x1.status" + rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" FM_FAKE_HERDR_PANE_GET_GARBAGE=1 \ + FM_BACKEND_HERDR_IDLE_SHELL_PROOF_POLLS=1 \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] \ + || fail "herdr-garbage-presence: teardown erased records on an unparseable pane presence" + [ -e "$case_dir/state/task-x1.meta" ] \ + || fail "herdr-garbage-presence: ambiguous presence erased the durable endpoint metadata" + [ -e "$case_dir/state/task-x1.status" ] \ + || fail "herdr-garbage-presence: ambiguous presence erased the task status record" + assert_grep "ambiguous structured presence" "$case_dir/stderr" \ + "herdr-garbage-presence: the ambiguity refusal was not explained visibly" + pass "herdr flat teardown never erases records when pane presence is unparseable" +} + +assert_herdr_teardown_preflight_refuses_before_changes() { + local mode=$1 case_dir log closed rc thlog teardown_bin + case_dir=$(make_case "herdr-preflight-$mode") + write_meta "$case_dir" local-only ship + configure_flat_herdr_teardown_case "$case_dir" + log="$case_dir/herdr.log"; : > "$log" + closed="$case_dir/closed" + : > "$case_dir/state/task-x1.status" + : > "$case_dir/state/task-x1.turn-ended" + thlog="$case_dir/treehouse.log"; : > "$thlog" + cat > "$case_dir/fakebin/treehouse" <<SH +#!/usr/bin/env bash +printf '%s\n' "\$*" >> "$thlog" +exit 0 +SH + chmod +x "$case_dir/fakebin/treehouse" + + teardown_bin=$TEARDOWN + case "$mode" in + missing-adapter|missing-parser|missing-explicit-close-helper) + mkdir -p "$case_dir/test-root" + cp -R "$ROOT/bin" "$case_dir/test-root/bin" + if [ "$mode" = missing-adapter ]; then + rm -f "$case_dir/test-root/bin/backends/herdr.sh" + elif [ "$mode" = missing-explicit-close-helper ]; then + sed -i.bak 's/^fm_backend_herdr_explicit_close_pane_confirmed()/fm_backend_herdr_explicit_close_pane_confirmed_unavailable()/' \ + "$case_dir/test-root/bin/backends/herdr.sh" + rm -f "$case_dir/test-root/bin/backends/herdr.sh.bak" + else + sed -i.bak 's/^fm_backend_herdr_parse_target()/fm_backend_herdr_parse_target_unavailable()/' \ + "$case_dir/test-root/bin/backends/herdr.sh" + rm -f "$case_dir/test-root/bin/backends/herdr.sh.bak" + fi + teardown_bin="$case_dir/test-root/bin/fm-teardown.sh" + ;; + esac + rc=0 + FM_ROOT_OVERRIDE="$ROOT" FM_STATE_OVERRIDE="$case_dir/state" FM_CONFIG_OVERRIDE="$case_dir/config" \ + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" \ + FM_FAKE_HERDR_SESSION_LIST_GARBAGE="$([ "$mode" = unresolvable-lock ] && printf 1 || printf 0)" \ + PATH="$case_dir/fakebin:$PATH" \ + "$teardown_bin" task-x1 --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] || fail "herdr-preflight-$mode: teardown continued without its required preflight" + assert_grep "nothing was changed" "$case_dir/stderr" \ + "herdr-preflight-$mode: the retryable pre-return refusal was not explained visibly" + [ -d "$case_dir/wt" ] || fail "herdr-preflight-$mode: refusal removed the isolated copy" + [ "$(git -C "$case_dir/wt" rev-parse --abbrev-ref HEAD 2>/dev/null)" = "fm/task-x1" ] \ + || fail "herdr-preflight-$mode: refusal dropped the task branch" + [ -e "$case_dir/state/task-x1.meta" ] \ + || fail "herdr-preflight-$mode: refusal erased the durable endpoint metadata" + [ -e "$case_dir/state/task-x1.status" ] \ + || fail "herdr-preflight-$mode: refusal erased the task status record" + [ -e "$case_dir/state/task-x1.turn-ended" ] \ + || fail "herdr-preflight-$mode: refusal erased the turn-end record" + [ ! -s "$thlog" ] || fail "herdr-preflight-$mode: refusal returned the isolated copy" + [ ! -e "$closed" ] || fail "herdr-preflight-$mode: refusal attempted an unlocked pane close" +} + +test_herdr_flat_teardown_preflight_refuses_before_changes() { + assert_herdr_teardown_preflight_refuses_before_changes unresolvable-lock + assert_herdr_teardown_preflight_refuses_before_changes missing-adapter + assert_herdr_teardown_preflight_refuses_before_changes missing-parser + assert_herdr_teardown_preflight_refuses_before_changes missing-explicit-close-helper + pass "herdr flat teardown preflight refuses before every destructive change" +} + +configure_secondmate_with_herdr_child() { # <case-dir> + local case_dir=$1 home="$1/secondmate-home" + mkdir -p "$home/state" "$home/data" "$home/config" "$home/projects" + printf '%s\n' task-x1 > "$home/.fm-secondmate-home" + # Fork ownership (fm_backend_legacy_worktree_matches) requires a secondmate's + # worktree path to equal its marked home. Upstream fixtures only appended home=; + # rewrite both fields so parent ownership and child preflight can both run. + printf '%s\n' "home=$home" >> "$case_dir/state/task-x1.meta" + if grep -q '^worktree=' "$case_dir/state/task-x1.meta" 2>/dev/null; then + # Replace the project worktree write_meta recorded with the secondmate home. + local tmp="$case_dir/state/task-x1.meta.tmp" + grep -v '^worktree=' "$case_dir/state/task-x1.meta" > "$tmp" + printf '%s\n' "worktree=$home" >> "$tmp" + mv "$tmp" "$case_dir/state/task-x1.meta" + else + printf '%s\n' "worktree=$home" >> "$case_dir/state/task-x1.meta" + fi + fm_write_meta "$home/state/child-herdr.meta" \ "window=childsession:wC:p1" \ + "endpoint_task_id=child-herdr" \ + "worktree=$case_dir/wt" \ + "project=$case_dir/project" \ + "kind=ship" \ + "mode=local-only" \ + "backend=herdr" \ + "herdr_session=childsession" \ + "herdr_workspace_id=wC" \ + "herdr_tab_id=wC:t1" \ + "herdr_pane_id=wC:p1" + : > "$home/state/child-herdr.status" + : > "$home/state/child-herdr.turn-ended" + cat > "$case_dir/fakebin/herdr" <<SH +#!/usr/bin/env bash +set -u +printf '%s\n' "\$*" >> "\${FM_FAKE_HERDR_LOG:?}" +case "\${1:-} \${2:-}" in + "session list") + if [ "\${FM_FAKE_HERDR_SESSION_LIST_GARBAGE:-0}" = 1 ]; then + printf '%s\n' 'not-json' + else + printf '%s\n' '{"sessions":[{"name":"childsession","running":true,"socket_path":"$case_dir/child.sock"}]}' + fi + ;; + "workspace list") exit 1 ;; + "pane get") + if [ -e "\${FM_FAKE_HERDR_CLOSED:?}" ]; then + if [ "\${FM_FAKE_HERDR_PRESENCE_UNKNOWN:-0}" = 1 ]; then + printf '%s\n' 'not-json' + else + printf '%s\n' '{"error":{"code":"pane_not_found"}}' >&2 + exit 1 + fi + else + printf '%s\n' '{"result":{"pane":{"pane_id":"wC:p1","tab_id":"wC:t1","workspace_id":"wC"}}}' + fi + ;; + "pane close") : > "\${FM_FAKE_HERDR_CLOSED:?}" ;; +esac +SH + chmod +x "$case_dir/fakebin/herdr" +} + +test_forced_secondmate_herdr_child_preflight_refuses_before_changes() { + local case_dir home log closed rc thlog + case_dir=$(make_case herdr-child-preflight) + write_meta "$case_dir" local-only secondmate + configure_secondmate_with_herdr_child "$case_dir" + home="$case_dir/secondmate-home" + log="$case_dir/herdr.log"; closed="$case_dir/closed"; thlog="$case_dir/treehouse.log" + : > "$log"; : > "$thlog" + cat > "$case_dir/fakebin/treehouse" <<SH +#!/usr/bin/env bash +printf '%s\n' "\$*" >> "$thlog" +exit 0 +SH + chmod +x "$case_dir/fakebin/treehouse" + rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" \ + FM_FAKE_HERDR_SESSION_LIST_GARBAGE=1 \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] || fail "herdr-child-preflight: teardown continued through an unresolvable child lock" + [ -e "$case_dir/state/task-x1.meta" ] || fail "herdr-child-preflight: refusal erased the parent record" + [ -e "$home/state/child-herdr.meta" ] || fail "herdr-child-preflight: refusal erased the child record" + [ -e "$home/state/child-herdr.status" ] || fail "herdr-child-preflight: refusal erased child status" + [ -d "$home" ] || fail "herdr-child-preflight: refusal removed the secondmate home" + [ ! -s "$thlog" ] || fail "herdr-child-preflight: refusal returned work before child preflight" + [ ! -e "$closed" ] || fail "herdr-child-preflight: refusal attempted a child close" + assert_grep "nothing was changed" "$case_dir/stderr" \ + "herdr-child-preflight: refusal did not explain its non-mutating boundary" + pass "forced secondmate teardown preflights every Herdr child before cleanup mutation" +} + +test_forced_secondmate_herdr_child_retains_records_when_close_unconfirmed() { + local case_dir home log closed rc + case_dir=$(make_case herdr-child-unconfirmed-close) + write_meta "$case_dir" local-only secondmate + configure_secondmate_with_herdr_child "$case_dir" + home="$case_dir/secondmate-home" + log="$case_dir/herdr.log"; closed="$case_dir/closed"; : > "$log" + rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" FM_FAKE_HERDR_PRESENCE_UNKNOWN=1 \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] || fail "herdr-child-unconfirmed-close: teardown erased records after an ambiguous close" + [ -e "$closed" ] || fail "herdr-child-unconfirmed-close: fixture did not attempt the child close" + [ -e "$home/state/child-herdr.meta" ] || fail "herdr-child-unconfirmed-close: ambiguous close erased child metadata" + [ -e "$home/state/child-herdr.status" ] || fail "herdr-child-unconfirmed-close: ambiguous close erased child status" + [ -e "$case_dir/state/task-x1.meta" ] || fail "herdr-child-unconfirmed-close: failed child cleanup erased parent metadata" + [ -d "$home" ] || fail "herdr-child-unconfirmed-close: failed child cleanup removed the secondmate home" + assert_grep "retaining that child's durable identity records" "$case_dir/stderr" \ + "herdr-child-unconfirmed-close: refusal did not explain child record retention" + pass "forced secondmate teardown retains Herdr child identity until exact pane disappearance" +} + +configure_nested_secondmate_with_herdr_grandchild() { # <case-dir> + local case_dir=$1 home="$1/secondmate-home" nested_home="$1/secondmate-home/nested-home" tmp + mkdir -p "$home/state" "$home/data" "$home/config" "$home/projects" + mkdir -p "$nested_home/state" "$nested_home/data" "$nested_home/config" "$nested_home/projects" + printf '%s\n' task-x1 > "$home/.fm-secondmate-home" + printf '%s\n' nested-sm > "$nested_home/.fm-secondmate-home" + printf '%s\n' "home=$home" >> "$case_dir/state/task-x1.meta" + # Same fork ownership rule as configure_secondmate_with_herdr_child: secondmate + # worktree path must equal the marked home for parent and nested secondmates. + tmp="$case_dir/state/task-x1.meta.tmp" + grep -v '^worktree=' "$case_dir/state/task-x1.meta" > "$tmp" + printf '%s\n' "worktree=$home" >> "$tmp" + mv "$tmp" "$case_dir/state/task-x1.meta" + fm_write_meta "$home/state/nested-sm.meta" \ + "window=firstmate:fm-nested-sm" \ + "endpoint_task_id=nested-sm" \ + "worktree=$nested_home" \ + "project=$case_dir/project" \ + "kind=secondmate" \ + "mode=local-only" \ + "home=$nested_home" + fm_write_meta "$nested_home/state/grandchild-herdr.meta" \ + "window=grandchildsession:wG:p1" \ + "endpoint_task_id=grandchild-herdr" \ + "worktree=$case_dir/wt" \ + "project=$case_dir/project" \ + "kind=ship" \ + "mode=local-only" \ + "backend=herdr" \ + "herdr_session=grandchildsession" \ + "herdr_workspace_id=wG" \ + "herdr_tab_id=wG:t1" \ + "herdr_pane_id=wG:p1" + : > "$nested_home/state/grandchild-herdr.status" + : > "$nested_home/state/grandchild-herdr.turn-ended" + cat > "$case_dir/fakebin/herdr" <<SH +#!/usr/bin/env bash +set -u +printf '%s\n' "\$*" >> "\${FM_FAKE_HERDR_LOG:?}" +case "\${1:-} \${2:-}" in + "session list") + printf '%s\n' '{"sessions":[{"name":"grandchildsession","running":true,"socket_path":"$case_dir/grandchild.sock"}]}' + ;; + "workspace list") exit 1 ;; + "pane get") + if [ -e "\${FM_FAKE_HERDR_CLOSED:?}" ]; then + printf '%s\n' 'not-json' + else + printf '%s\n' '{"result":{"pane":{"pane_id":"wG:p1","tab_id":"wG:t1","workspace_id":"wG"}}}' + fi + ;; + "pane close") : > "\${FM_FAKE_HERDR_CLOSED:?}" ;; +esac +SH + chmod +x "$case_dir/fakebin/herdr" +} + +test_forced_teardown_retains_nested_secondmate_home_when_grandchild_close_unconfirmed() { + local case_dir home nested_home log closed rc + case_dir=$(make_case herdr-grandchild-unconfirmed-close) + write_meta "$case_dir" local-only secondmate + configure_nested_secondmate_with_herdr_grandchild "$case_dir" + home="$case_dir/secondmate-home"; nested_home="$home/nested-home" + log="$case_dir/herdr.log"; closed="$case_dir/closed"; : > "$log" + rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] \ + || fail "herdr-grandchild-unconfirmed-close: teardown erased records after an ambiguous grandchild close" + [ -e "$closed" ] \ + || fail "herdr-grandchild-unconfirmed-close: fixture did not attempt the grandchild close" + [ -d "$nested_home" ] \ + || fail "herdr-grandchild-unconfirmed-close: the recursive failure still removed the nested secondmate home" + [ -e "$nested_home/state/grandchild-herdr.meta" ] \ + || fail "herdr-grandchild-unconfirmed-close: ambiguous close erased the grandchild's metadata" + [ -e "$nested_home/state/grandchild-herdr.status" ] \ + || fail "herdr-grandchild-unconfirmed-close: ambiguous close erased the grandchild's status record" + [ -e "$home/state/nested-sm.meta" ] \ + || fail "herdr-grandchild-unconfirmed-close: the recursive failure erased the nested secondmate's own record" + [ -e "$case_dir/state/task-x1.meta" ] \ + || fail "herdr-grandchild-unconfirmed-close: the recursive failure erased the top-level secondmate's record" + pass "forced teardown retains a nested secondmate home and its grandchild's Herdr identity when the grandchild close is unconfirmed" +} + configure_herdr_projection_teardown_case() { # <case-dir> local case_dir=$1 token=AbCdEfGhIjKlMnOpQrStUv sed -i.bak 's/^window=.*/window=fmtest:w1:p2/' "$case_dir/state/task-x1.meta" @@ -1426,6 +1878,10 @@ case "${1:-} ${2:-}" in ;; "pane get") if [ -e "${FM_FAKE_HERDR_CLOSED:?}" ]; then + if [ "${FM_FAKE_HERDR_PRESENCE_UNKNOWN:-0}" = 1 ]; then + printf '%s\n' '{"error":{"code":"internal"}}' >&2 + exit 1 + fi printf '%s\n' '{"error":{"code":"pane_not_found"}}' >&2 exit 1 fi @@ -1473,16 +1929,24 @@ test_herdr_projection_teardown_retains_journal_when_close_unconfirmed() { configure_herdr_projection_teardown_case "$case_dir" log="$case_dir/herdr.log"; closed="$case_dir/closed"; restored="$case_dir/restored"; : > "$log" - FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" FM_FAKE_HERDR_RESTORED="$restored" FM_FAKE_HERDR_CLOSE_FAIL=1 \ - run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" \ - || fail "herdr-projection-unconfirmed-close: teardown should preserve best-effort endpoint semantics" + local rc=0 + FM_FAKE_HERDR_LOG="$log" FM_FAKE_HERDR_CLOSED="$closed" FM_FAKE_HERDR_RESTORED="$restored" FM_FAKE_HERDR_PRESENCE_UNKNOWN=1 \ + run_teardown "$case_dir" --force > "$case_dir/stdout" 2> "$case_dir/stderr" || rc=$? + [ "$rc" -ne 0 ] \ + || fail "herdr-projection-unconfirmed-close: teardown reported success after an unknown post-close presence read" + [ -e "$closed" ] \ + || fail "herdr-projection-unconfirmed-close: regression did not exercise an attempted close" [ -e "$case_dir/state/task-x1.herdr-presentation" ] \ || fail "unconfirmed task-pane close incorrectly retired the presentation journal" + [ -e "$case_dir/state/task-x1.meta" ] \ + || fail "unconfirmed task-pane close erased the durable endpoint metadata" assert_grep "close could not be confirmed" "$case_dir/stderr" \ "unconfirmed projected close did not explain why the journal was retained" + assert_grep "not confirmed gone" "$case_dir/stderr" \ + "unconfirmed projected close did not explain why the records were retained" assert_not_contains "$(cat "$log")" "workspace close" \ "unconfirmed projected close must not escalate to workspace cleanup" - pass "herdr projection teardown retains the stale journal and attempts no workspace cleanup when exact-pane close is unconfirmed" + pass "herdr projection teardown retains every record when post-close presence is unknown" } test_teardown_reaps_task_browser_before_cleanup() { @@ -1541,7 +2005,14 @@ test_local_only_merged_to_local_main_allows test_no_mistakes_origin_remote_allows test_no_mistakes_truly_unpushed_refuses test_local_only_force_overrides_unpushed +test_teardown_missing_busy_sidecar_completes test_herdr_teardown_clears_escalation_marker +test_herdr_flat_teardown_refuses_orphaning_records_then_retry_completes +test_herdr_flat_teardown_refuses_records_on_unparseable_presence +test_herdr_flat_teardown_preflight_refuses_before_changes +test_forced_secondmate_herdr_child_preflight_refuses_before_changes +test_forced_secondmate_herdr_child_retains_records_when_close_unconfirmed +test_forced_teardown_retains_nested_secondmate_home_when_grandchild_close_unconfirmed test_herdr_projection_teardown_retires_journal_only_after_confirmed_close test_herdr_projection_teardown_retains_journal_when_close_unconfirmed test_teardown_reaps_task_browser_before_cleanup diff --git a/tests/fm-vendor-auth-probe.test.sh b/tests/fm-vendor-auth-probe.test.sh new file mode 100755 index 00000000000..47367a32682 --- /dev/null +++ b/tests/fm-vendor-auth-probe.test.sh @@ -0,0 +1,395 @@ +#!/usr/bin/env bash +# Behavior tests for fm-vendor-auth-probe.sh - the one hard-bounded, +# non-destructive authentication probe of a named vendor CLI. +# +# Two defects this suite pins: +# +# 1. The script must render no dispatch verdict and hold no routing knowledge. +# Its predecessor resolved a candidate's credential surface from a hard-coded +# harness-to-provider table plus a `pi:<model-prefix>` source-id matcher, and +# emitted `eligible=`. A supported Pi model in a provider family with no such +# prefixed source was therefore dropped as unresolved while the family's own +# quota and credentials were healthy. The tests below prove the script now has +# no harness, model, or provider input surface at all, so no such mapping can +# influence it, and that both probe outcomes exit alike because neither is a +# verdict. +# +# 2. The captain-approved probe envelope must not depend on agent memory: fixed +# argv, stdin closed, a hard positive bound, and raw vendor output never +# printed. The fake grok records every invocation's argv and anything it can +# read from stdin, so "argv is fixed to `models`", "no login or logout", and +# "stdin stays closed" are observable facts rather than comments. +set -u + +# shellcheck source=tests/lib.sh disable=SC1091 +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +BASE_PATH=${FM_TEST_BASE_PATH:-/usr/bin:/bin:/usr/sbin:/sbin} +TMP_ROOT=$(fm_test_tmproot fm-vendor-auth-probe-tests) +SCRIPT="$ROOT/bin/fm-vendor-auth-probe.sh" + +# A stdin payload the script must never leak into a probed vendor CLI. +STDIN_SENTINEL='SENTINEL-STDIN-MUST-NOT-REACH-VENDOR-CLI' + +# --- fake toolchain --------------------------------------------------------- +# +# quota-axi is present on PATH and logs every invocation. The script must never +# call it: reading quota is the dispatch owner's job against one intake snapshot, +# and a probe that re-read it would reintroduce the retired coupling. +make_fakebin() { + local dir=$1 fakebin + fakebin=$(fm_fakebin "$dir") + cat > "$fakebin/quota-axi" <<'SH' +#!/usr/bin/env bash +printf '%s\n' "$*" >> "$FM_FAKE_QUOTA_LOG" +exit 0 +SH + chmod +x "$fakebin/quota-axi" + + cat > "$fakebin/grok" <<'SH' +#!/usr/bin/env bash +printf '%s\n' "$*" >> "$FM_FAKE_GROK_LOG" +# Record whatever is readable on stdin. With stdin correctly closed by the +# caller this reads EOF immediately and records nothing. +if IFS= read -r -t 2 leaked; then + printf '%s\n' "$leaked" >> "$FM_FAKE_GROK_STDIN" +fi +if [ "${1:-}" = --version ]; then + printf 'grok %s (fakebuild) [stable]\n' "${FM_FAKE_GROK_VERSION:-0.2.117}" + exit 0 +fi +case "${FM_FAKE_GROK_MODE:-authenticated}" in + authenticated) + printf '%s\n' 'You are logged in with grok.com.' + printf '\n%s\n' 'Default model: grok-4.5' + ;; + unauthenticated) + printf '%s\n' 'You are not authenticated.' + ;; + garbage) + printf '%s\n' 'Session status: unknown (0.9.0 rewrote this line)' + ;; + leading-blank) + printf '\n%s\n' 'You are logged in with grok.com.' + ;; + empty) : ;; + hang) sleep 30 ;; +esac +# grok 0.2.117 exits 0 whether or not the session authenticates; the fake keeps +# that property so a regression to exit-status reading fails here. +exit 0 +SH + chmod +x "$fakebin/grok" + printf '%s\n' "$fakebin" +} + +# run_probe <case> [args...] -- [env assignments...] +# Sets RUN_LINE, RUN_RC, RUN_GROK_LOG, RUN_GROK_STDIN, RUN_QUOTA_LOG in the +# caller's shell, so it must not be invoked in a command substitution. +RUN_LINE= +RUN_RC=0 +RUN_GROK_LOG= +RUN_GROK_STDIN= +RUN_QUOTA_LOG= +run_probe() { + local case_name=$1 + shift + local case_dir fakebin out rc=0 arg + local -a script_args=() env_pairs=() + case_dir="$TMP_ROOT/$case_name" + mkdir -p "$case_dir" + fakebin=$(make_fakebin "$case_dir") + RUN_GROK_LOG="$case_dir/grok.log" + RUN_GROK_STDIN="$case_dir/grok.stdin" + RUN_QUOTA_LOG="$case_dir/quota.log" + : > "$RUN_GROK_LOG" + : > "$RUN_GROK_STDIN" + : > "$RUN_QUOTA_LOG" + local seen_separator=0 + for arg in "$@"; do + if [ "$seen_separator" -eq 0 ] && [ "$arg" = -- ]; then + seen_separator=1 + continue + fi + if [ "$seen_separator" -eq 0 ]; then + script_args+=("$arg") + else + env_pairs+=("$arg") + fi + done + out=$(env "PATH=$fakebin:$BASE_PATH" \ + "FM_FAKE_GROK_LOG=$RUN_GROK_LOG" \ + "FM_FAKE_GROK_STDIN=$RUN_GROK_STDIN" \ + "FM_FAKE_QUOTA_LOG=$RUN_QUOTA_LOG" \ + "${env_pairs[@]+"${env_pairs[@]}"}" \ + "$SCRIPT" "${script_args[@]+"${script_args[@]}"}" \ + <<<"$STDIN_SENTINEL" 2>/dev/null) || rc=$? + RUN_RC=$rc + RUN_LINE=$out +} + +field() { # <line> <key> + printf '%s\n' "$1" | tr ' ' '\n' | sed -n "s/^$2=//p" +} + +assert_field() { # <line> <key> <expected> <label> + local got + got=$(field "$1" "$2") + [ "$got" = "$3" ] || fail "$4: expected $2=$3, got $2=${got:-<absent>}"$'\n'"--- line ---"$'\n'"$1" +} + +# Every recorded grok invocation must be one of the two fixed, non-destructive +# argv forms. A login, logout, or bare interactive launch fails here. +assert_grok_argv_safe() { # <label> + local line + while IFS= read -r line; do + [ -n "$line" ] || continue + case "$line" in + models|--version) : ;; + *) fail "$1: unexpected Grok CLI invocation 'grok $line'" ;; + esac + done < "$RUN_GROK_LOG" +} + +assert_grok_never_ran() { # <label> + [ ! -s "$RUN_GROK_LOG" ] \ + || fail "$1: no vendor CLI may run, but grok was invoked with: $(tr '\n' '|' < "$RUN_GROK_LOG")" +} + +assert_quota_never_read() { # <label> + [ ! -s "$RUN_QUOTA_LOG" ] \ + || fail "$1: the probe must never call quota-axi, but it ran: $(tr '\n' '|' < "$RUN_QUOTA_LOG")" +} + +# --- the retired dispatch coupling ------------------------------------------ + +# The core retirement: the probe carries no candidate identity, so no +# harness-to-provider table, model prefix matcher, or provider-family mapping can +# exist behind it. Every shape of candidate input is a usage error, and none of +# them reaches a vendor CLI. +test_probe_accepts_no_candidate_identity() { + local label + local -a args + # Both shapes matter. Without a probe name, candidate identity must not stand + # in for one. WITH a valid probe name, candidate identity must still be + # refused rather than quietly accepted and ignored - a silently tolerated + # `--model` is exactly the seam a routing mapping would grow back through. + for label in harness-flag model-flag provider-flag tuple positional-model \ + probe-with-harness probe-with-model probe-with-tuple probe-with-provider; do + case "$label" in + harness-flag) args=(--harness pi) ;; + model-flag) args=(--model openai-codex/gpt-5.6-terra) ;; + provider-flag) args=(--provider codex) ;; + tuple) args=(--harness pi --model openai-codex/gpt-5.6-terra) ;; + positional-model) args=(grok openai-codex/gpt-5.6-terra) ;; + probe-with-harness) args=(grok --harness pi) ;; + probe-with-model) args=(grok --model openai-codex/gpt-5.6-terra) ;; + probe-with-tuple) args=(grok --harness pi --model openai-codex/gpt-5.6-terra) ;; + probe-with-provider) args=(grok --provider codex) ;; + esac + run_probe "identity-$label" "${args[@]}" + expect_code 2 "$RUN_RC" "$label must be a usage error, not a candidate verdict" + [ -z "$RUN_LINE" ] || fail "$label must not emit a fact line: $RUN_LINE" + assert_grok_never_ran "identity-$label" + assert_quota_never_read "identity-$label" + done + pass "the probe accepts no harness, model, or provider and so can hold no routing mapping" +} + +# The retired script read quota to decide eligibility. This one must not, so an +# intake keeps exactly one snapshot and the probe cannot re-derive a route. +test_probe_never_reads_quota() { + local mode + for mode in authenticated unauthenticated; do + run_probe "no-quota-$mode" grok -- "FM_FAKE_GROK_MODE=$mode" + assert_quota_never_read "no-quota-$mode" + done + pass "the probe never reads quota, leaving one intake snapshot to the dispatch owner" +} + +# Neither outcome is a verdict, so neither may be encoded in the exit status. A +# caller that branched on the exit status would be reinventing the eligibility +# gate this script was narrowed to remove. +test_probe_result_is_never_an_exit_status_verdict() { + local mode + for mode in authenticated unauthenticated garbage empty; do + run_probe "rc-$mode" grok -- "FM_FAKE_GROK_MODE=$mode" + expect_code 0 "$RUN_RC" "probe result '$mode' must not be encoded in the exit status" + [ -n "$RUN_LINE" ] || fail "probe result '$mode' must still print its fact line" + done + pass "every probe result exits alike because the script renders no verdict" +} + +test_unregistered_probe_is_a_usage_error() { + local name + for name in openai codex claude pi ''; do + if [ -z "$name" ]; then + run_probe "unregistered-empty" + else + run_probe "unregistered-$name" "$name" + fi + expect_code 2 "$RUN_RC" "an unregistered probe name must be a usage error" + assert_grok_never_ran "unregistered-${name:-empty}" + done + pass "only a registered probe name runs, and an unregistered one is a usage error" +} + +# --- probe classification --------------------------------------------------- + +test_authenticated_session_is_reported() { + run_probe authenticated grok -- "FM_FAKE_GROK_MODE=authenticated" + expect_code 0 "$RUN_RC" "a completed probe prints its fact" + assert_field "$RUN_LINE" probe grok "the probe name must be echoed" + assert_field "$RUN_LINE" status authenticated "an authenticated first line must be recognized" + assert_grok_argv_safe "authenticated case" + pass "an authenticated vendor session is reported as ground truth" +} + +test_unauthenticated_session_is_reported() { + run_probe unauthenticated grok -- "FM_FAKE_GROK_MODE=unauthenticated" + assert_field "$RUN_LINE" status unauthenticated "an unauthenticated first line must be recognized" + assert_grok_argv_safe "unauthenticated case" + pass "an unauthenticated vendor session is reported as ground truth" +} + +# The exit status is deliberately not the verdict, so a rewritten status line +# must read as indeterminate rather than as a successful authentication. +test_unrecognized_output_is_indeterminate() { + local mode + for mode in garbage leading-blank empty; do + run_probe "indeterminate-$mode" grok -- "FM_FAKE_GROK_MODE=$mode" + assert_field "$RUN_LINE" status indeterminate "'$mode' output must never read as authenticated" + done + pass "unrecognized, blank-led, and silent probe output is indeterminate, never authenticated" +} + +test_missing_vendor_cli_is_reported_not_assumed() { + local case_dir fakebin line rc=0 + case_dir="$TMP_ROOT/grok-absent" + mkdir -p "$case_dir" + fakebin=$(make_fakebin "$case_dir") + rm -f "$fakebin/grok" + line=$(env "PATH=$fakebin:$BASE_PATH" \ + "FM_FAKE_QUOTA_LOG=$case_dir/quota.log" \ + "$SCRIPT" grok </dev/null 2>/dev/null) || rc=$? + expect_code 0 "$rc" "an absent vendor CLI is a fact, not a usage error" + assert_field "$line" status unavailable "an absent probe command must be reported" + assert_field "$line" version none "an absent CLI has no version to report" + assert_field "$line" versionVerified none "an absent CLI cannot be version-verified" + pass "an absent vendor CLI is reported rather than assumed authenticated" +} + +# --- the bounded, non-destructive envelope ---------------------------------- + +test_hanging_probe_is_bounded_and_reported() { + local started finished + started=$(date +%s) + run_probe grok-hang grok -- "FM_FAKE_GROK_MODE=hang" "FM_VENDOR_AUTH_PROBE_TIMEOUT=2" + finished=$(date +%s) + assert_field "$RUN_LINE" status timeout "a hit bound must be reported as a timeout" + [ $((finished - started)) -lt 25 ] \ + || fail "the probe was not bounded: took $((finished - started))s against a 2s bound" + pass "a hanging vendor CLI is hard-bounded, reported, and cannot wedge an intake" +} + +# `timeout 0` and the Perl fallback's `alarm 0` both mean "no deadline", so a +# zero bound passed through would silently remove the hard bound entirely. The +# fake hangs for 30s, longer than the 20s default it must fall back to, so the +# two outcomes are distinguishable. +test_zero_bound_falls_back_to_a_real_bound() { + local started finished value + for value in 0 00; do + started=$(date +%s) + run_probe "bound-zero-$value" grok -- "FM_FAKE_GROK_MODE=hang" "FM_VENDOR_AUTH_PROBE_TIMEOUT=$value" + finished=$(date +%s) + assert_field "$RUN_LINE" status timeout "a zero bound must fall back to the default bound, not to no bound" + [ $((finished - started)) -lt 28 ] \ + || fail "a zero bound removed the hard bound: took $((finished - started))s" + done + pass "zero and all-zero bounds fall back to the default instead of removing the hard bound" +} + +# A bogus bound must be replaced, not forwarded: `timeout abc` and `timeout -1` +# fail outright, which would turn a healthy probe into a false indeterminate. +test_malformed_bound_is_replaced_not_forwarded() { + local value + for value in -1 abc 1.5 ' '; do + run_probe "bound-${value// /space}" grok -- "FM_FAKE_GROK_MODE=authenticated" "FM_VENDOR_AUTH_PROBE_TIMEOUT=$value" + assert_field "$RUN_LINE" status authenticated "bound '$value' must be replaced, not forwarded to the bounding command" + done + pass "a malformed bound is replaced by the default rather than forwarded" +} + +test_probe_never_inherits_caller_stdin() { + run_probe grok-stdin grok -- "FM_FAKE_GROK_MODE=authenticated" + [ -n "$RUN_LINE" ] || fail "expected a fact line" + [ ! -s "$RUN_GROK_STDIN" ] \ + || fail "the probe inherited caller stdin: $(cat "$RUN_GROK_STDIN")" + pass "the bounded probe runs with stdin closed and cannot read caller input" +} + +test_probe_argv_is_fixed_and_non_destructive() { + local mode + for mode in authenticated unauthenticated garbage; do + run_probe "argv-$mode" grok -- "FM_FAKE_GROK_MODE=$mode" + assert_grok_argv_safe "argv-$mode" + [ "$(grep -c . "$RUN_GROK_LOG")" -eq 2 ] \ + || fail "argv-$mode: expected exactly one --version and one models call, got: $(tr '\n' '|' < "$RUN_GROK_LOG")" + done + pass "the vendor CLI is invoked only through its two fixed, non-destructive argv forms" +} + +test_fact_line_carries_no_vendor_output_or_credential_material() { + run_probe sanitized grok -- "FM_FAKE_GROK_MODE=authenticated" + assert_not_contains "$RUN_LINE" "You are logged in" "the fact line must not echo raw vendor output" + assert_not_contains "$RUN_LINE" "grok.com" "the fact line must not echo raw vendor output" + assert_not_contains "$RUN_LINE" "auth.json" "the fact line must not name a credential path" + assert_not_contains "$RUN_LINE" "$STDIN_SENTINEL" "the fact line must not echo caller stdin" + case "$RUN_LINE" in + *$'\n'*) fail "the fact line must be exactly one line" ;; + esac + pass "the fact line is one sanitized line with no raw vendor output or credential material" +} + +# --- version disclosure ----------------------------------------------------- + +# The discriminator strings are un-owned vendor UI text. A version change does +# not silently invalidate the fact, but it is disclosed so it can be re-verified. +test_probe_version_change_is_disclosed() { + run_probe version-drift grok -- "FM_FAKE_GROK_MODE=authenticated" "FM_FAKE_GROK_VERSION=0.9.0" + assert_field "$RUN_LINE" version 0.9.0 "the probed CLI version must be recorded" + assert_field "$RUN_LINE" versionVerified no "an unverified version must be disclosed" + pass "a vendor CLI version change is recorded and disclosed for re-verification" +} + +test_probe_version_match_is_recorded() { + run_probe version-pinned grok -- "FM_FAKE_GROK_MODE=authenticated" + assert_field "$RUN_LINE" versionVerified yes "the pinned verified version must be recognized" + pass "the pinned verified vendor version is recognized" +} + +test_help_succeeds_and_names_the_registered_probes() { + local out rc=0 + out=$("$SCRIPT" --help 2>&1) || rc=$? + expect_code 0 "$rc" "--help must succeed" + assert_contains "$out" "grok" "--help must name the registered probes" + pass "--help succeeds and names the registered probes" +} + +test_probe_accepts_no_candidate_identity +test_probe_never_reads_quota +test_probe_result_is_never_an_exit_status_verdict +test_unregistered_probe_is_a_usage_error +test_authenticated_session_is_reported +test_unauthenticated_session_is_reported +test_unrecognized_output_is_indeterminate +test_missing_vendor_cli_is_reported_not_assumed +test_hanging_probe_is_bounded_and_reported +test_zero_bound_falls_back_to_a_real_bound +test_malformed_bound_is_replaced_not_forwarded +test_probe_never_inherits_caller_stdin +test_probe_argv_is_fixed_and_non_destructive +test_fact_line_carries_no_vendor_output_or_credential_material +test_probe_version_change_is_disclosed +test_probe_version_match_is_recorded +test_help_succeeds_and_names_the_registered_probes diff --git a/tests/fm-wake-daemon-lifecycle-e2e.test.sh b/tests/fm-wake-daemon-lifecycle-e2e.test.sh index 639db67b5a3..42f879080bd 100755 --- a/tests/fm-wake-daemon-lifecycle-e2e.test.sh +++ b/tests/fm-wake-daemon-lifecycle-e2e.test.sh @@ -106,7 +106,7 @@ test_routine_then_terminal_after_restart() { # --- Phase 2: stale working-pane transient -> persistent -> resumed ---------- test_stale_pane_transient_persistent_resume() { - local dir state fakebin win key + local dir state fakebin win key resumed_gen dir=$(make_supercase wd-stale) state="$dir/state" fakebin="$dir/fakebin" @@ -128,15 +128,23 @@ test_stale_pane_transient_persistent_resume() { echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key" : > "$state/.subsuper-escalations" 2>/dev/null || true PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$dir/pane.txt" \ - FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state" + FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state" \ + 2>"$dir/housekeeping.err" + [ ! -s "$dir/housekeeping.err" ] \ + || fail "missing task metadata leaked a raw read error: $(cat "$dir/housekeeping.err")" [ -s "$state/.subsuper-escalations" ] || fail "persistent stale did not escalate" [ ! -e "$state/.subsuper-stale-$key" ] || fail "stale marker not cleared after escalation" - # Resumed: a fresh transient marker but the pane is now busy -> housekeeping - # clears the marker without escalating. + # Resumed: a fresh transient marker but the crew is provably working again -> + # housekeeping clears the marker without escalating. The proof is the crew's + # own semantic busy-state record (bin/fm-busy-lib.sh), not rendered pane text. stale_marker_record "$win" "$state" echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key" printf 'Working...\n' > "$dir/pane.txt" + fm_write_meta "$state/stale-w2.meta" "window=$win" "worktree=$dir/wt" "kind=ship" "harness=pi" + resumed_gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" stale-w2) + "$ROOT/bin/fm-busy-event.sh" apply "$state" stale-w2 busy --gen "$resumed_gen" \ + --source pi-ext --event agent-start : > "$state/.subsuper-escalations" PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$dir/pane.txt" \ FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state" diff --git a/tests/fm-watch-triage.test.sh b/tests/fm-watch-triage.test.sh index d79a7219a03..c852d30a406 100755 --- a/tests/fm-watch-triage.test.sh +++ b/tests/fm-watch-triage.test.sh @@ -102,6 +102,13 @@ prime_turnend_seen() { # <file> printf '%s' "$(seen_sig "$f")" > "$(dirname "$f")/.seen-$base" } +record_pi_busy() { # <state-dir> <id> + local state=$1 id=$2 gen + gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" "$id") + "$ROOT/bin/fm-busy-event.sh" apply "$state" "$id" busy --gen "$gen" \ + --source pi-ext --event agent-start +} + reap() { kill "$1" 2>/dev/null || true; wait "$1" 2>/dev/null || true; } # --- pure classifier predicates (fm-classify-lib.sh) ------------------------ @@ -1130,6 +1137,7 @@ test_busy_pane_below_turn_age_bound_is_absorbed() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-fresh" printf 'Working... (12.3s)' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-fresh.meta" + record_pi_busy "$state" busy-fresh printf 'working: setup complete\n' > "$state/busy-fresh.status" sig=$(seen_sig "$state/busy-fresh.status"); printf '%s' "$sig" > "$state/.seen-busy-fresh_status" key=$(printf '%s' "$window" | tr ':/.' '___') @@ -1155,6 +1163,7 @@ test_busy_pane_stable_hash_escalates_past_turn_age_bound() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-stable" printf 'Working...' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-stable.meta" + record_pi_busy "$state" busy-stable printf 'working: setup complete\n' > "$state/busy-stable.status" sig=$(seen_sig "$state/busy-stable.status"); printf '%s' "$sig" > "$state/.seen-busy-stable_status" key=$(printf '%s' "$window" | tr ':/.' '___') @@ -1198,6 +1207,7 @@ test_busy_pane_changing_hash_escalates_past_turn_age_bound() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-ticking" printf 'Working... (3600.1s)' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-ticking.meta" + record_pi_busy "$state" busy-ticking printf 'working: setup complete\n' > "$state/busy-ticking.status" sig=$(seen_sig "$state/busy-ticking.status"); printf '%s' "$sig" > "$state/.seen-busy-ticking_status" key=$(printf '%s' "$window" | tr ':/.' '___') @@ -1238,6 +1248,7 @@ test_busy_pane_turn_end_touch_resets_age() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-reset" printf 'Working...' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-reset.meta" + record_pi_busy "$state" busy-reset printf 'working: setup complete\n' > "$state/busy-reset.status" sig=$(seen_sig "$state/busy-reset.status"); printf '%s' "$sig" > "$state/.seen-busy-reset_status" key=$(printf '%s' "$window" | tr ':/.' '___') @@ -1271,6 +1282,7 @@ test_busy_pane_repeated_escalation_reaches_demand_deep_inspection() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-demand-inspect" printf 'Working...' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-demand.meta" + record_pi_busy "$state" busy-demand printf 'working: setup complete\n' > "$state/busy-demand.status" sig=$(seen_sig "$state/busy-demand.status"); printf '%s' "$sig" > "$state/.seen-busy-demand_status" key=$(printf '%s' "$window" | tr ':/.' '___') @@ -1322,6 +1334,7 @@ test_busy_pane_default_turn_age_bound_is_3600s() { out="$dir/watch.out"; capture_file="$dir/pane.txt"; window="test:fm-busy-default" printf 'Working...' > "$capture_file" printf 'window=%s\nkind=ship\nharness=pi\n' "$window" > "$state/busy-default.meta" + record_pi_busy "$state" busy-default printf 'working: setup complete\n' > "$state/busy-default.status" sig=$(seen_sig "$state/busy-default.status"); printf '%s' "$sig" > "$state/.seen-busy-default_status" key=$(printf '%s' "$window" | tr ':/.' '___') diff --git a/tests/herdr-test-safety.sh b/tests/herdr-test-safety.sh index 984acd02134..59a2bb46cc2 100644 --- a/tests/herdr-test-safety.sh +++ b/tests/herdr-test-safety.sh @@ -14,6 +14,25 @@ HERDR_TEST_SAFETY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" # shellcheck source=/dev/null . "$HERDR_TEST_SAFETY_DIR/bin/fm-herdr-lab.sh" +# herdr_forget_inherited_pane: drop the Herdr PANE identity this test process +# inherited from whatever terminal it was started in. +# +# Herdr injects HERDR_ENV, HERDR_PANE_ID, HERDR_TAB_ID, HERDR_WORKSPACE_ID, +# HERDR_SOCKET_PATH, and HERDR_SESSION into every process it manages a pane for +# (verified 0.7.5 - docs/verification/runtime-backends.md), and a test run from +# inside a Herdr pane inherits all of them. Spawn now treats that pane as the +# authoritative parent to place workers next to, so a leaked identity from the +# developer's own session would follow the test into its isolated lab session +# and be refused there as a cross-session parent - a result that depends on +# where the suite was launched from, not on what it asserts. +# +# Call this before exporting the lab HERDR_SESSION in any suite whose subject is +# the per-home container path. A suite that means to exercise a launcher-bound +# spawn sets HERDR_PANE_ID itself, to a pane it created in its own lab session. +herdr_forget_inherited_pane() { + unset HERDR_ENV HERDR_PANE_ID HERDR_TAB_ID HERDR_WORKSPACE_ID HERDR_SOCKET_PATH HERDR_SESSION +} + herdr_refuse_if_default() { # <session> fm_herdr_lab_refuse_if_default "$1" }