feat(bus): B-0444 — add worktree field to claim envelope

[AceHack]

Summary

Implements B-0444 — adds worktree?: string to ClaimPayload so the claim envelope captures the worktree path the claim was acquired from. Closes Otto-Desktop's identified follow-up gap filed in #3038.

• Schema: ClaimPayload.worktree? + ClaimRecord.worktree? (both optional → back-compat)
• CLI: acquire --worktree <path> flag; defaults to process.cwd()
• Output: check text + check --json + acquire --json all surface the field

Design decision (substrate-honest)

Surface-tagged sender IDs (#3037) arbitrate split-brain at the coordination layer (otto-cli vs otto-desktop are distinct claims on the same item). worktree is observability metadata, not a coordination key — same sender re-acquiring from a different worktree remains idempotent. Pinned by the test same sender re-acquiring from a different worktree is idempotent (existing behavior preserved).

Test plan

• 14 new tests in tools/bus/claim.test.ts — default cwd, explicit --worktree, JSON shape, combined with --branch, surface-IDs-still-arbitrate, same-sender different-worktree idempotency, claim-record shape
• bun test tools/bus/claim.test.ts → 52/52 pass
• Built from isolated worktree at /tmp/zeta-b0444 to avoid multi-Otto split-brain (the very class of problem this row addresses)

Composes with

• B-0400 (bus protocol root)
• B-0400 slice 3 / PR feat(B-0400): inter-agent claim coordinator — slice 3 #2939 (claim-coordinator implementation)
• PR feat(bus): SENDER_IDS schema extension — multi-surface variants (substrate-level split-brain fix) #3037 (SENDER_IDS schema extension — sibling surface-level fix)
• .claude/rules/claim-acquire-before-worktree-work.md — rule this row's gap was identified against
• PR docs(backlog): B-0444 — bus claim envelope worktree field (Otto-Desktop's identified follow-up gap) #3038 (docs(backlog) commit that filed this row)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an optional worktree field to bus claim envelopes (B-0444) so claims carry the per-process operational coordinate (which checkout produced them) for observability. Coordination/arbitration remains driven by surface-tagged sender IDs (PR #3037); worktree is metadata only, optional for back-compat.

Changes:

• Schema: ClaimPayload.worktree? and ClaimRecord.worktree? added as optional fields.
• CLI: acquire --worktree <path> flag (defaults to process.cwd()); surfaced in text and JSON output of check/acquire.
• Tests: 7 new tests covering default cwd, explicit path, JSON shape, branch+worktree combo, surface-ID arbitration still wins, same-sender different-worktree idempotency.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
tools/bus/types.ts	Adds optional worktree?: string to ClaimPayload with doc comment.
tools/bus/claim.ts	Adds worktree to ClaimRecord, propagates through activeClaims/allActiveClaims, adds --worktree CLI flag with process.cwd() default, surfaces in text/JSON outputs.
tools/bus/claim.test.ts	Adds a 7-test describe block covering the new field, including back-compat (same-sender idempotency) and surface-ID arbitration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a5f3e0473f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 774070094b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

tools/bus/claim.ts:277

• The bare---worktree rejection runs before the --from/--item presence check, so a user typo like acquire --worktree (omitting required flags entirely) reports "--worktree requires a path argument" instead of the more informative "--from and --item are required". Consider moving the worktree validation after the required-flag checks for a more useful error ordering.

      if (flags.worktree === "true") {
        console.error("Error: --worktree requires a path argument");
        process.exit(1);
      }
      const worktree = flags.worktree ?? process.cwd();
      if (!from || !itemId) {
        console.error("Error: --from and --item are required");
        process.exit(1);
      }

tools/bus/claim.ts:324

• Since worktree is unconditionally assigned to flags.worktree ?? process.cwd() on line 273, it is always a non-empty string. The conditional spread ...(worktree ? { worktree } : {}) on line 300 and the ternary worktree ? ... : "" on line 323 can never take their false branch. This is confusing — either the default should be removed (making worktree truly optional in the payload) or the truthiness guards should be dropped. As written, the type signature suggests optionality the runtime never actually exercises.

            payload: {
              action: "claim",
              itemId,
              ...(branch ? { branch } : {}),
              ...(worktree ? { worktree } : {}),
            },
          });
          return { acquired: true, claimedByOthers: [] as string[], messageId: env.id };
        }));
      } catch (err) {
        console.error(`Error: ${(err as Error).message}`);
        process.exit(1);
      }

      if (!acquired) {
        if (asJson) {
          console.log(JSON.stringify({ itemId, acquired: false, claimedBy: claimedByOthers }));
        } else {
          console.error(`${itemId}: already claimed by ${claimedByOthers.join(", ")} — not acquiring`);
        }
        process.exit(1);
      }

      if (asJson) {
        console.log(JSON.stringify({ itemId, acquired: true, messageId, worktree }));
      } else {
        const branchStr = branch ? ` (${branch})` : "";
        const worktreeStr = worktree ? ` [worktree: ${worktree}]` : "";
        console.log(`${itemId}: claimed by ${sender}${branchStr}${worktreeStr} — ${messageId}`);