feat: propagate W3C trace context to spawned agents

[allstargg]

Intent

Make the already-validated upstream PR-995 native W3C trace-context capability available on the captain's integration fork (allstargg/firstmate) without waiting for the canonical upstream merge of PR 995. This is a deliberate, exact port: the trace-context implementation is preserved byte-for-byte from PR-995 head 2fbe2fd (every feature-only file is byte-identical), applied as the isolated feature delta (a53ffc1..2ff8ab8) via cherry-pick -m1 onto current fork main. Fork main already carries canonical Firstmate content from an earlier squash fork-sync, so this change is intentionally scoped to ONLY the trace-context feature: the 22 changed files are exactly PR 995's files. Three genuine overlaps with the newer canonical commit kunchenguid#1303 (bound and consolidate startup memory during stow) were resolved BY DESIGN to preserve BOTH behaviors - bin/fm-config-inherit-lib.sh, docs/configuration.md, and tests/fm-secondmate-harness.test.sh now declare both startup-memory-budget and trace-context in their shared config lists/comments; no canonical content was dropped and no old upstream content reintroduced. The capability is default-off (presence flag config/trace-context plus FM_TRACE_CONTEXT override), propagates a W3C traceparent to spawned agents, freezes its decision at locked session start, and inherits into secondmate homes. PR 995 passed 10/10 upstream checks and the focused suites (trace-context lib/spawn, session-start, documentation-audiences, secondmate-harness, lint) pass locally. The exact integrated trace-context tree is required and must not be altered; the cherry-pick merge strategy and the kunchenguid#1303 overlap resolutions were explicitly captain-approved.

What Changed

• Add opt-in W3C traceparent propagation and metadata recording for spawned agents, including inherited child traces and stable relaunch context.
• Freeze trace-context enablement at session start, propagate it into Secondmate homes, and safely handle backend injection failures.
• Document the configuration and behavior, with focused coverage for trace generation, spawning, session startup, inheritance, and supported backends.

Risk Assessment

✅ Low: The trace-context port is well-bounded and source evidence shows the required default-off behavior, locked-session decision, spawn propagation, metadata agreement, secondmate inheritance, and approved overlap resolutions remain intact.

Testing

The required startup check was clean; focused library, real spawn-path, locked-session, secondmate-inheritance, documentation, backend-carrier, and test-run fixtures all passed, with transcripts demonstrating default-off behavior, identical recorded/injected W3C carriers, safe failure handling, frozen decisions, relaunch identity, and primary-to-secondmate-to-worker propagation. This is a shell capability with no rendered UI, so visual screenshots were not applicable.

Evidence: End-to-end trace-context spawn transcript

ok - enabled: one resolved carrier is recorded in meta and the identical TRACEPARENT is exported before launch
ok - disabled: neither traceparent= in meta nor a TRACEPARENT export is produced
ok - failed TRACEPARENT delivery omits metadata while the source task still launches
ok - uncleared TRACEPARENT input stops before the launch command is appended
ok - failed traceparent metadata append removes the carrier from the launched task
ok - duplicate secondmate preflight leaves trace-context unchanged
ok - relaunch reuses the recorded carrier verbatim for both the meta record and the injected export
ok - session start freezes the env override and later config or environment edits do not alter spawns
ok - two-level: env-on/file-absent keeps the nested worker enabled and in the same trace as the primary
ok - two-level: env-off/file-present keeps the nested worker disabled even though the config file was copied into the secondmate home
ok - secondmate carrier and FM_TRACE_CONTEXT snapshot always agree, both derived from one frozen decision (file-decided path)
# all fm-trace-context-spawn tests passed

Evidence: Secondmate inheritance transcript

ok - A1 fm-harness.sh secondmate resolves the fallback chain; crew mode unchanged
ok - C1 fm-harness.sh secondmate-model/secondmate-effort resolve the optional tokens; bare harness stays empty (backward-compat)
ok - pi-signed identity: authoritative launch selection distinguishes shared wrapper ancestry
ok - harness identity: dash-leading ps command names are basename operands, not options
ok - B1 propagate_inheritable_config: copy, idempotence, convergence, absence-mirror, exclusion, no-op, skip diagnostics
ok - B2 spawn: secondmate runs the secondmate harness; its home inherits declared config
ok - B3 spawn: an absent secondmate-harness falls back to the crew harness (backward-compat)
ok - B4 spawn: no config at all -> own harness and no propagation side effects
ok - B5 spawn: an explicit per-spawn harness arg overrides config/secondmate-harness
ok - B6 spawn: an unverified resolved secondmate harness is refused (guard intact)
ok - B5b spawn: FM_BACKEND wins over inherited config/backend
ok - B5c spawn: explicit --backend wins over FM_BACKEND and inherited config/backend
ok - C2 spawn: a bare harness-only secondmate-harness file launches with no model/effort flag (backward-compat)
ok - C3 spawn: config/secondmate-harness's model token threads --model into the launch and meta
ok - C4 spawn: config/secondmate-harness's model+effort tokens thread into the launch and meta
ok - C5 spawn: an explicit --model overrides config/secondmate-harness's model token; the file's effort token still applies
ok - C6 spawn: an explicit --effort overrides config/secondmate-harness's effort token; the file's model token still applies
ok - C7 spawn: an explicit --harness starts with clean model/effort defaults
ok - C8 spawn: an explicit --harness still honors explicit model/effort flags
ok - C9 spawn: the harness fallback chain still resolves with no tokens; crew/scout launches are unaffected by this feature
ok - B7 bootstrap sweep pushes, re-converges, and mirrors absence; never inherits secondmate-harness
ok - B8 bootstrap sweep propagates config even when the home's tracked files are already current
ok - B9 bootstrap sweep defers new inherited config until the home ignores it
ok - B10 bootstrap sweep materializes and inherits the startup-memory default while fast-forwarding
ok - B12b backend inheritance: present values and primary absence converge exactly
ok - B11 bootstrap sweep surfaces config propagation failures
ok - B11 bootstrap rereads completed config writes after partial propagation
ok - B12 config-push propagates via shared live discovery, reports items, rereads on change only, and does not fast-forward
ok - B13 config-push reports dirty, non-allowing, and invalid homes without failing warnings-only runs
ok - B14 config-push exits nonzero on real propagation errors
ok - B14 config-push rereads completed config writes after partial propagation
ok - B15 config reread is per-home, exact-byte, ordered, and pointer-only
ok - B16 config reread isolation, ABSENT, generation safety, send failure, and retry

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff --stat --name-only a1f63638e5c5f87b12d5ab81d1eac72d4bbedea5..5bd5bb7d60f4dd0da467ef5871e0f6d3926a1171
• bin/fm-session-start.sh
• bash tests/fm-trace-context-lib.test.sh
• bash tests/fm-trace-context-spawn.test.sh
• bash tests/fm-session-start.test.sh
• bash tests/fm-secondmate-harness.test.sh
• bash tests/fm-documentation-audiences.test.sh
• bash tests/fm-backend-cmux.test.sh
• bash tests/fm-backend-zellij.test.sh
• bash tests/fm-test-run.test.sh
• Inspected the three #1303 overlap surfaces with rg -n 'startup-memory-budget|trace-context' bin/fm-config-inherit-lib.sh docs/configuration.md tests/fm-secondmate-harness.test.sh
• Checked evidence logs for failure markers and confirmed git status --short remained clean

⚠️ **Document** - 1 warning

• ⚠️ docs/trace-context.md:25 - docs/trace-context.md claims coverage across every harness but omits the fork's verified pi-signed harness. Adding pi-signed would fix the authoritative trace-context guide, but would violate the explicit requirement that every feature-only PR-995 file remain byte-identical. Recommend preserving the required exact port unless the captain authorizes this one-word documentation divergence; declining leaves this sentence inaccurate for pi-signed.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.