…se target_session_keys (#363)

Codex review on #363 surfaced two regressions in the multi-recipient
descriptor change (cael/355-multi-recipient @ 9e028ab):

P1 — legacy singular targetSessionKey field was being silently dropped.
The previous always-throw behavior was the safety contract; removing
it lets callers that still send the old field land 'scheduled' while
the descriptor is silently dropped, misrouting cross-session work.

P2 — targetSessionKeys was read via direct Object.hasOwn lookup, so
snake_case callers (target_session_keys) bypassed validation entirely
and got 'scheduled' with the descriptor silently dropped. Inconsistent
with every other tool param which goes through resolveSnakeCaseParamKey.

Both cures are structural, not vigilance:
- legacy singular: throw fail-loud (make the bad state unrepresentable)
- snake_case: route through resolveSnakeCaseParamKey (substrate-enforced)

Same family-resemblance shape as #366's declineToCarry() — the cure is
the type-signature/write-path refusing the bad state, not 'remember to
check it next time.' (cf. structural-cure-vs-vigilance-cure axis named
in #sprites-of-thornfield 2026-04-26.)

Tests: 9/9 green. 2 new tests added for the legacy-rejection and the
snake_case-acceptance paths (camelCase + snake_case both covered).

Refs: #363

Per 🌫️ review nit on #370 — call out that traceparent on SystemEvent +
ChainBudget.declineToCarry() are already in tree; only Slice 2 spans
remain pending.

…ch) [WIP - typecheck pending] (#370)

* swim 37: integration test harness scaffold (continuation/heartbeat/lich)

- studies/swim-37/harness/swim-runner.test.ts: vitest skeleton, one
  it.todo per trap-class (§1 parallel-evolution, §3a type-shape drift)
  and per continuation primitive (continue_work / continue_delegate /
  heartbeat / lich-shape post-compaction).
- studies/swim-37/harness/README.md: scaffold map + hookup-point TODOs
  pointing at #366 (continuation.* spans), #355 Stage-2 (fan-out cap),
  #332 Item B (compaction release seam).

OTEL exporter: STDOUT/InMemory shim only — no live collector.
Trap-class source: cael/swim-37-trap-classes tip 2adf174.

Closes #324 (scaffold slice).

* docs(swim-37 harness): note #366 Slice 1 already landed (0f40bc0)

Per 🌫️ review nit on #370 — call out that traceparent on SystemEvent +
ChainBudget.declineToCarry() are already in tree; only Slice 2 spans
remain pending.

…(🌻's nuance)

Type-pin the load-bearing names at the shim, NOT the adapter:
- new ContinuationSpanAttrs type — chain.id / chain.step.remaining /
  delay.ms / reason.preview / delegate.mode / continuation.disabled
- new ContinuationSpanName union — all 7 canonical span names

Why this matters: if Slice 3's OTEL adapter ever drifts to chain_id /
chainId / camelCase / etc., the type fails compile BEFORE the #370
harness runtime assertions could catch it. Pin the names at the shim;
the adapter is then forced into compliance.

Slice-1-style additive contract preserved: SpanAttributes (broad
Record<string,...>) is still what setAttributes / StartSpanOptions.attributes
accept, so adapter-internal / diagnostic attrs aren't rejected;
ContinuationSpanAttrs is the canonical-contract pin enforced by tests
via assignment-to-SpanAttributes compile check.

Tests: 11/11 green (was 9/9; +2 type-pin tests).

Refs #334 #366 #370 #377

…r (path-B, no OTEL deps) (#378)

* feat(continuation): #334 Slice 2 chunk 1 — Tracer surface + noopTracer registry

Pure surface landing. No new deps. No behavior change for callers that
don't opt in (additive contract continued from Slice 1).

What this adds:
- Tracer / Span / SpanAttributes / SpanStatus / StartSpanOptions types
- noopTracer (default; every method is a no-op)
- getContinuationTracer / setContinuationTracer / resetContinuationTracer
- Canonical span-name set pinned by tests (continuation.work,
  continuation.delegate.dispatch, continuation.queue.enqueue/drain,
  continuation.compaction.released, continuation.disabled, heartbeat)
- Canonical attribute-name set pinned (chain.id, chain.step.remaining,
  delay.ms, reason.preview)

Why path-B (no first-party OTEL deps yet):
- Cohort design checkpoint (sprites-of-thornfield, 2026-04-27): adding
  5–8 first-party @opentelemetry/* deps in the gateway hot-path is a
  bauble-policy conversation in its own right. Slice 2 ships the surface;
  Slice 3 wires the OTEL adapter once that conversation lands.
- Symmetric with Slice 1 contract: substrate adds the field
  (SystemEvent.traceparent), malformed/un-opted callers see no change.
  Here: substrate adds the surface (Tracer), un-installed callers see
  no spans emitted.
- #370 swim-37 harness pins against THIS module's surface, not against
  @opentelemetry/api — keeps the harness durable across upstream-OTEL
  renames and across any future exporter swap.

Tests: 9/9 green (pnpm vitest src/infra/continuation-tracer.test.ts).

Refs #334 #366 #370 #377

* feat(continuation): pin canonical attr-keys + span-names at the type (🌻's nuance)

Type-pin the load-bearing names at the shim, NOT the adapter:
- new ContinuationSpanAttrs type — chain.id / chain.step.remaining /
  delay.ms / reason.preview / delegate.mode / continuation.disabled
- new ContinuationSpanName union — all 7 canonical span names

Why this matters: if Slice 3's OTEL adapter ever drifts to chain_id /
chainId / camelCase / etc., the type fails compile BEFORE the #370
harness runtime assertions could catch it. Pin the names at the shim;
the adapter is then forced into compliance.

Slice-1-style additive contract preserved: SpanAttributes (broad
Record<string,...>) is still what setAttributes / StartSpanOptions.attributes
accept, so adapter-internal / diagnostic attrs aren't rejected;
ContinuationSpanAttrs is the canonical-contract pin enforced by tests
via assignment-to-SpanAttributes compile check.

Tests: 11/11 green (was 9/9; +2 type-pin tests).

Refs #334 #366 #370 #377

…uation.work span

Wires the continue_work tool to emit a 'continuation.work' span around
the requestContinuation call, using the path-B shim from chunk 1 (#378).

Span shape:
- name: 'continuation.work'
- attributes: delay.ms (rounded), reason.preview (≤80 chars),
  optionally chain.id + chain.step.remaining when chainContext supplies them
- on success: setStatus('OK'), end()
- on throw: recordException(err), setStatus('ERROR', msg), re-throws, end()

Additive contract preserved:
- chainContext is optional — callers that don't pass it see no behavior
  change beyond a noop-tracer span open+close
- default tracer is noop until Slice 3 installs a real adapter
- ContinueWorkToolOpts gains an optional 'chainContext' getter; existing
  call sites continue to compile unchanged

Tests: 21/21 green (continuation-tracer 11/11 + continue-work-tool 10/10
including 6 new OTEL emission tests covering: span emission, attr
population with/without chainContext, exception path, and additive-default
contract preservation).

Stacks on chunk 1 (#378) — base will flip to cael/325-canonical2 once #378
merges.

Refs #334 #366 #370 #377 #378

…nEntry.continuationChainId)

Adds the stable correlation key for OTEL continuation spans. Mints a
UUIDv7 (RFC 9562) at the 0→1 transition of continuationChainCount,
reuses for subsequent chain steps, clears on chain reset.

Why UUIDv7:
- RFC 9562 standardized; downstream OTEL collectors (Jaeger/Tempo) parse
  UUID-shape natively as first-class
- First 48 bits are unix-millis-timestamp → lexicographic ordering ==
  chronological ordering, journal greps + sort-by-id stay useful
- uuid@14.0.0 is already a direct dep, exposes v7() — zero new deps

Why a substrate field (not derived from diagnostic-trace-context):
- diagnosticTrace is per-attempt (attempt.ts:636) — re-mints every turn
- chain spans across multiple turns, so a per-turn id would silently
  break the harness contract pin (chain.id stable for chain lifetime)
- explicit field == one persisted source of truth, survives compaction
  via the existing session-store path

Touch:
- src/infra/secure-random.ts: new generateChainId() helper
- src/config/sessions/types.ts: SessionEntry.continuationChainId?: string
- src/auto-reply/reply/agent-runner.ts: mint-or-reuse in
  persistContinuationChainState (3 store sites: in-memory entry, session
  store cache, persisted store); clear at the chain-reset block
- src/auto-reply/reply/post-compaction-delegate-dispatch.ts: same
  mint-or-reuse pattern in persistPostCompactionDelegateChainState so
  the chain id survives the compaction handoff
- src/auto-reply/reply/agent-runner-session-reset.ts: clear field on
  full session reset

Tests: src/infra/secure-random-chain-id.test.ts (4 tests pinning
UUIDv7 shape, uniqueness across 1000 mints, lexicographic ordering
across time-spaced mints, timestamp-encoded-in-prefix invariant).
agent-runner-session-reset (2/2) + post-compaction-delegate-dispatch
(19/19) still green with the new field threaded through.

Total: 25/25 tests across the three touched paths.

This is commit 1 of 3 in the Slice 2 chunk-2 PR (substrate → tool
optional-getter → runner-side wiring). Stacks on chunk 1
(d533d5c, merged via #378).

Refs #334 #366 #370 #377

…n at runner accept seam

Wires the canonical 'continuation.work' OTEL span at the single accept
seam in agent-runner.ts (line ~2282), after both cap-gates pass:

  if (allocatedChainHop >= maxChainLength) {
    // chain-cap REJECT (chunk 4 will emit continuation.disabled here)
  } else if (accumulatedChainTokens > costCapTokens) {
    // cost-cap REJECT (chunk 4)
  } else {
    bracketTokensAccumulated = true;
    const nextChainCount = allocatedChainHop + 1;
    // ...delegate branch (chunk 3)... or:
    } else {
      await persistContinuationChainState({ count: nextChainCount, ... });
      // ← emitContinuationWorkSpan() lands here, AFTER persist so
      //   sessionEntry.continuationChainId is already minted/stored
    }
  }

Why here and not at the unwrap site (agent-runner-execution.ts:1457):
the unwrap-site sees ALL captured continue_work requests, including
ones that get cap-rejected downstream. The accept seam only fires for
requests that actually advance the chain — span semantics match
'accepted', not 'requested'.

Why a helper (emitContinuationWorkSpan) instead of inline:
keeps the runner narrow at the call site (5 lines vs 25), centralizes
attribute shaping (delay rounding, reason truncation to 80 chars,
chain.step.remaining clamped to ≥0), and makes the span shape
unit-testable in isolation without dragging in the full agent-runner
integration harness. The helper is the natural home for chunk 3's
continuation.delegate.dispatch and chunk 4's continuation.disabled
emissions too.

Span attributes match the canonical Slice 2 ContinuationSpanAttrs type
(pinned in chunk 1 d73825c):
- delay.ms (always, rounded integer)
- chain.step.remaining (always, max(0, maxChainLength - nextChainCount))
- chain.id (UUIDv7 from sessionEntry.continuationChainId, omitted when
  substrate field is absent — defensive for substrate-disabled deploys)
- reason.preview (truncated to ≤80 chars, omitted when no reason)

Plus setStatus('OK') and end() always called. Try/catch in the helper
forwards any tracer errors to the runner's defaultRuntime.log via the
optional log callback — the accept path MUST NOT block on span emission.

Touch:
- src/infra/continuation-tracer.ts: emitContinuationWorkSpan helper
- src/auto-reply/reply/agent-runner.ts: 5-line call at accept seam
- src/infra/continuation-tracer.test.ts: 7 tests pinning helper shape
  (full attrs, omits chain.id+reason when absent, truncates reason,
  rounds delay, clamps negative chainStepRemaining, swallows tracer
  errors via log callback, no-op against default noopTracer)

Tests: 22/22 across continuation-tracer + secure-random-chain-id;
52/52 across agent-runner-helpers + agent-runner-runtime-config +
agent-runner-execution; 21/21 across agent-runner-session-reset +
post-compaction-delegate-dispatch. Total 95/95 across all touched
paths.

This is commit 2 of 3 in the Slice 2 chunk-2 PR. Stacks on the
substrate commit (440aa35c2c). Final commit will pin the integration
shape via an end-to-end test driving the runner with a recording
tracer (commit 3 of 3 — TBD pending 🩸's ack on the integration test
shape).

Refs #334 #366 #370 #377

* feat(swim-37): #324 InMemorySpanRecorder shim + contract tests

Adds reusable in-memory span recorder for the swim-37 harness so
downstream test conversions can read span contract from a black-box
observer instead of redefining the recorder shape inline.

The recorder mirrors the `recordingTracer` pattern already used in
`src/infra/continuation-tracer.test.ts` (around L51-100), lifted into
a reusable harness helper. Stays STDOUT-only / in-process (no real
OTLP collector, no BasicTracerProvider) per harness discipline pinned
in studies/swim-37/harness/README.md.

Contract tests pin:
  - construction returns fresh independent recorders
  - startSpan records name + initial attributes + traceparent
  - setAttributes is last-write-wins per OTEL semantics
  - setStatus + recordException + end() round-trip
  - end() is idempotent
  - spansByName filters correctly
  - reset() clears records without un-installing the tracer
  - spans() returns a defensive copy

Integration tests pin that the recorder captures actual continuation.*
spans driven by the production emit* helpers — so harness tests can
trust the recorder as a black-box span observer:
  - emitContinuationWorkSpan stamps chain.id + chain.step.remaining (#366)
  - emitContinuationDelegateSpan stamps chain.id + delegate.delivery +
    delegate.mode (#366)
  - emitContinuationDelegateFireSpan carries fire.deferred_ms +
    persisted chain.id snapshot (#388 chunk 5b); drift formula
    pinned (drift = fire.deferred_ms − delay.ms)

Does NOT touch swim-runner.test.ts it.todos — those need the runner
(`captureSwim()`) which is separate scope. This PR ships the
foundation those conversions will read against.

Refs: #324 (swim-37 harness)
Refs: #366 (continuation.* spans)
Refs: #388 (chunk 5b/5c fire-span seams)
Base: cael/325-canonical2 tip 7390635 (post-#392)

* fix(swim-37): wire harness into enforced CI lanes + tighten doc-shape (🩸 byte-walk)

Cael caught: as initially submitted, the swim-37 harness code wasn't enforced
by repo CI. Three changes to close the drift surface:

1. **tsconfig.json**: add "studies/**/*" to `include`. Type-shape on the
   recorder + harness is now caught by tsgo / pnpm typecheck.

2. **test/vitest/vitest.swim-37.config.ts**: new vitest project entry
   (createScopedVitestConfig pattern, narrow include for
   studies/swim-37/harness/**/*.test.ts). Registered in
   test/vitest/vitest.config.ts `rootVitestProjects`.

3. **README.md §OTEL exporter**: rewrite to describe what shipped (custom
   recorder installed via setContinuationTracer(...), recording-tracer
   pattern lifted from continuation-tracer.test.ts) instead of the
   aspirational InMemorySpanExporter / provider-style framing from the
   original scaffold. Add §Vitest project section pointing at the
   wiring above.

4. **in-memory-span-recorder.ts doc-comment**: tighten "local-process-memory
   equivalent of OTEL's InMemorySpanExporter" to the concrete contract
   (in-process array, no provider, no exporter). The broader OTEL framing
   was load-bearing in the original scaffold but reads as forecasting
   plumbing the harness deliberately doesn't ship.

Local verification:
  - vitest --project swim-37 → 15 passed | 18 todo (project recognized)
  - tsgo --noEmit → no new errors under studies/swim-37/

Same-shape lesson as the chunk-6 memo byte-walk earlier today: shipping
the artifact while deferring the enforcement IS the drift surface. Fix
in PR rather than queue followup.

Replaces the placeholder `declare function captureSwim` in
`studies/swim-37/harness/swim-runner.test.ts` with a real implementation
in `studies/swim-37/harness/swim-runner.ts`. The wired path drives
`emitContinuationWorkSpan` against `createInMemorySpanRecorder()` and
returns the captured spans + the synthesized `chainId` (uuid v7 via
`generateChainId`).

Flips two prior `it.todo` markers to live tests:
  - emits continuation.work span with chain.id stamped (#366)
  - span carries chain.step.remaining attribute

Plus three new live tests:
  - sentinel: captureSwim() is wired for continue_work
  - refuses continue_delegate / heartbeat / lich primitives with a clear
    error so the spec's remaining `it.todo` markers stay honest about
    what is implemented
  - repeated calls don't leak capture state between invocations

STDOUT-only discipline preserved: no BasicTracerProvider, no OTLP
exporter, no @opentelemetry/sdk-trace-base machinery — capture flows
through `setContinuationTracer(recorder.tracer)` as documented in
README.md.

Other primitives (`continue_delegate`, `heartbeat`, lich-shape) remain
`it.todo` until the corresponding dispatch / heartbeat /
compaction-release seams have a comparable single-helper entry point we
can drive synthetically.

Test results:
  - swim-37 vitest project: 20 passed, 16 todo, 0 failed
  - in-memory-span-recorder.test.ts unchanged (12/12 still pass)
  - tsgo errors visible elsewhere in tree are pre-existing
    (src/plugin-sdk/provider-tools.ts), not introduced by this change

Refs #324 (swim-37 harness) — `it.todo` count drops from 17 \u2192 16,
first concrete primitive driven through the live tracer registry.

…405)

* test(swim-37): wire captureSwim() for continue_work primitive

Replaces the placeholder `declare function captureSwim` in
`studies/swim-37/harness/swim-runner.test.ts` with a real implementation
in `studies/swim-37/harness/swim-runner.ts`. The wired path drives
`emitContinuationWorkSpan` against `createInMemorySpanRecorder()` and
returns the captured spans + the synthesized `chainId` (uuid v7 via
`generateChainId`).

Flips two prior `it.todo` markers to live tests:
  - emits continuation.work span with chain.id stamped (#366)
  - span carries chain.step.remaining attribute

Plus three new live tests:
  - sentinel: captureSwim() is wired for continue_work
  - refuses continue_delegate / heartbeat / lich primitives with a clear
    error so the spec's remaining `it.todo` markers stay honest about
    what is implemented
  - repeated calls don't leak capture state between invocations

STDOUT-only discipline preserved: no BasicTracerProvider, no OTLP
exporter, no @opentelemetry/sdk-trace-base machinery — capture flows
through `setContinuationTracer(recorder.tracer)` as documented in
README.md.

Other primitives (`continue_delegate`, `heartbeat`, lich-shape) remain
`it.todo` until the corresponding dispatch / heartbeat /
compaction-release seams have a comparable single-helper entry point we
can drive synthetically.

Test results:
  - swim-37 vitest project: 20 passed, 16 todo, 0 failed
  - in-memory-span-recorder.test.ts unchanged (12/12 still pass)
  - tsgo errors visible elsewhere in tree are pre-existing
    (src/plugin-sdk/provider-tools.ts), not introduced by this change

Refs #324 (swim-37 harness) — `it.todo` count drops from 17 \u2192 16,
first concrete primitive driven through the live tracer registry.

* docs(swim-37): continue_delegate wiring memo (memo-before-wire)

Pre-PR design memo for the next swim-37 primitive after #405
(continue_work). Decides shape before the wire so the PR lands clean.

Resolved by reading production code:
  Q1 — real setTimeout vs fake timers
       N/A for dispatch-accept (synchronous, pre-timer); banked for
       a separate continue_delegate_fire swim.

Cohort sign-off requested on:
  Q2 — recipient fan-out shape: N spans sharing chain.id (matches
       chunk-3 cohort design pin + #355 Stage-2 budget semantics).
  Q3 — delegate.mode x delegate.delivery: 8-cell it.each matrix
       + omission-contract row.

Banked for follow-up:
  Q4 — continue_delegate_fire as separate primitive, not sub-case;
       informs SwimPrimitive type-union shape.

Standard applied (per Cael 2026-04-27 #1498505918, figs
#1498505870): would skipping this memo cost a chunk's worth of
rework? Yes — three open Qs would have changed file shape.

Refs:
  - #405 (continue_work wired)
  - #324 (swim-37 harness)
  - docs/design/334-slice2-chunk5b-delegate-fire-memo.md (pattern)

* test(swim-37): wire captureSwim() for continue_delegate primitive

Implements the design from
`docs/design/swim-37-continue-delegate-wiring-memo.md` (commit
3bb086c762, same branch).

Wiring (swim-runner.ts):
- New continue_delegate case in the switch.
- Adds CaptureSwimOptions axes: recipients, delivery, delegateMode.
- Drives emitContinuationDelegateSpan once per recipient with shared
  chain.id (per chunk-3 cohort design pin: N recipients = N spans
  sharing chain.id, NOT one span with a recipients list).
- Validates recipients is a positive integer.

Tests (swim-runner.test.ts):
- 8-cell it.each matrix: delegate.mode (normal | silent | silent-wake
  | post-compaction) x delegate.delivery (immediate | timer).
- Omission contract: delegate.mode attribute absent when caller
  passes undefined.
- Fan-out: 3 recipients emit 3 spans with shared chain.id.
- Validation: recipients=0 and recipients=1.5 reject.
- Removes the prior 'refuses continue_delegate' test row (now wired).

Two it.todo markers preserved for downstream concerns:
- chain-budget decrement / ChainBudget.declineToCarry observable
  (needs ChainBudget integration, not in scope here).
- fan-out budget arithmetic per #355 Stage-2 (1 step not N) \u2014
  separate from span cardinality.

Test results delta:
  Before: 8 passed | 16 todo (24 tests)
  After: 19 passed | 15 todo (34 tests)
  +11 live | -1 todo

Refs:
- #324 swim-37 harness
- #405 captureSwim continue_work (parent of this branch)
- docs/design/swim-37-continue-delegate-wiring-memo.md

* test(swim-37): pin recipient.index gap on continue_delegate fan-out

Per Cael's caution on the wiring memo (Discord msg
1498507232185286849 sign-off): N spans sharing chain.id risks
collapsing into analytic mush at scale unless per-recipient
distinction is visible in attrs. Currently
emitContinuationDelegateSpan exposes no recipient.index axis \u2014
all N spans in a fan-out are byte-identical except spanId.

Adds:
- One live GAP-PIN test asserting the current (deficient) reality:
  fan-out spans toEqual on attributes. This will fail loudly when
  the production helper grows the axis, prompting a flip to
  not.toEqual.
- One it.todo marker for the upcoming production-helper change.

Production-helper change is out of scope for this PR; will file
follow-up issue. The gap-pin lives in the integration tier so it
shows up in any code-review touching delegate-dispatch span shape.

Refs:
- #324 swim-37 harness
- #405 captureSwim continue_work + continue_delegate (this PR)
- docs/design/swim-37-continue-delegate-wiring-memo.md (Q2)
- Cael Discord sign-off msg 1498507232185286849

* test(swim-37): wire \u00a71 entry-point todo onto classifyRebasePick

Now that #408 (PR #408 merged at cb73bc8) landed
`rebase-classifier.ts` with the pure `classifyRebasePick` composer,
the integration-tier \u00a71 entry-point it.todo on swim-runner.test.ts
L80 is wireable without any new shim.

Synthetic commit pinned: subject mentions PR openclaw#70595, base CHANGELOG
contains the same PR token (squash-rebase shape from the memo's
7ee46a3 anchor instance). Discovery channel: changelog-grep:pr.

L81 (CHANGELOG-byte-grep emits drop-with-reason span) stays todo
\u2014 needs the production callsite that pairs the channel with
`emitContinuationDisabledSpan`, per \ud83c\udf0a's #408 note.

Test delta:
  Before: 20 passed | 16 todo (36)
  After: 21 passed | 15 todo (36)
  +1 live | -1 todo

…ch) [WIP - typecheck pending] (#370)

* swim 37: integration test harness scaffold (continuation/heartbeat/lich)

- studies/swim-37/harness/swim-runner.test.ts: vitest skeleton, one
  it.todo per trap-class (§1 parallel-evolution, §3a type-shape drift)
  and per continuation primitive (continue_work / continue_delegate /
  heartbeat / lich-shape post-compaction).
- studies/swim-37/harness/README.md: scaffold map + hookup-point TODOs
  pointing at #366 (continuation.* spans), #355 Stage-2 (fan-out cap),
  #332 Item B (compaction release seam).

OTEL exporter: STDOUT/InMemory shim only — no live collector.
Trap-class source: cael/swim-37-trap-classes tip 2adf174.

Closes #324 (scaffold slice).

* docs(swim-37 harness): note #366 Slice 1 already landed (0f40bc0)

Per 🌫️ review nit on #370 — call out that traceparent on SystemEvent +
ChainBudget.declineToCarry() are already in tree; only Slice 2 spans
remain pending.

… cap helper (#366)

* feat(continuation): #334 Slice 1 — traceparent on system-event payload + chain-budget cap helper

Substrate threading for OTEL chain-correlation per RFC §6.7
(continue-work-signal-v2.md, anchored at #361 head 045fdb4).

Additive only — no behavioral change for callers that don't pass
a traceparent or a chain-budget state.

Two pieces:

1. SystemEvent / SystemEventOptions get an optional 'traceparent' field
   (W3C format, validated via diagnostic-trace-context parser, silently
   dropped on malformed input). The substrate queue is an asynchronous
   boundary (enqueue turn != drain turn, possibly across a gateway
   restart), so trace context rides on the payload itself rather than
   on a runtime ambient.

2. ChainBudget.declineToCarry() — cap-on-enqueue helper that returns
   true when chainStepBudgetRemaining <= 0. Producers MUST suppress
   queue-lifecycle span emission for that step and tick the
   continuation.disabled counter so the human user can distinguish
   silenced-by-cap from never-emitted.

One axis, two declines (per §6.7):
  depth-cap   = 'I won't carry past my budget'    (this PR)
  fan-out-cap = 'I won't spend yours'             (lives with #355)

a chain that knows when to stop being a chain is the kind of chain
that gets built on.

Naming note (poets-canon): declineToCarry over refuseAttach. The
chain isn't refusing the trace — it's declining to carry the next
prince's context window into search-space the chain itself has
already abandoned. Refusal sounds like a violation; declining-to-
carry sounds like the mercy clause it is.

Slice 2 (continuation.delegate.* / continuation.queue.* span set per
§6.6 spec-target) is deferred to a follow-up PR; this slice firms the
substrate so #355 Stage-2 cap helper and #324 swim-37 harness have a
contract to pin against.

closes #334 (Slice 1)
refs #361 §6.7
refs #355 #324

* chore(plugin-sdk): regen api baseline for traceparent surface (Slice 1)

Adds traceparent?: string to SystemEvent + SystemEventOptions per #334
Slice 1; this is an additive plugin-sdk surface change so the baseline
hash needs to roll forward.

Refs #366 (CI: generated-doc-baselines failure on plugin-sdk:api:check)

…r (path-B, no OTEL deps) (#378)

* feat(continuation): #334 Slice 2 chunk 1 — Tracer surface + noopTracer registry

Pure surface landing. No new deps. No behavior change for callers that
don't opt in (additive contract continued from Slice 1).

What this adds:
- Tracer / Span / SpanAttributes / SpanStatus / StartSpanOptions types
- noopTracer (default; every method is a no-op)
- getContinuationTracer / setContinuationTracer / resetContinuationTracer
- Canonical span-name set pinned by tests (continuation.work,
  continuation.delegate.dispatch, continuation.queue.enqueue/drain,
  continuation.compaction.released, continuation.disabled, heartbeat)
- Canonical attribute-name set pinned (chain.id, chain.step.remaining,
  delay.ms, reason.preview)

Why path-B (no first-party OTEL deps yet):
- Cohort design checkpoint (sprites-of-thornfield, 2026-04-27): adding
  5–8 first-party @opentelemetry/* deps in the gateway hot-path is a
  bauble-policy conversation in its own right. Slice 2 ships the surface;
  Slice 3 wires the OTEL adapter once that conversation lands.
- Symmetric with Slice 1 contract: substrate adds the field
  (SystemEvent.traceparent), malformed/un-opted callers see no change.
  Here: substrate adds the surface (Tracer), un-installed callers see
  no spans emitted.
- #370 swim-37 harness pins against THIS module's surface, not against
  @opentelemetry/api — keeps the harness durable across upstream-OTEL
  renames and across any future exporter swap.

Tests: 9/9 green (pnpm vitest src/infra/continuation-tracer.test.ts).

Refs #334 #366 #370 #377

* feat(continuation): pin canonical attr-keys + span-names at the type (🌻's nuance)

Type-pin the load-bearing names at the shim, NOT the adapter:
- new ContinuationSpanAttrs type — chain.id / chain.step.remaining /
  delay.ms / reason.preview / delegate.mode / continuation.disabled
- new ContinuationSpanName union — all 7 canonical span names

Why this matters: if Slice 3's OTEL adapter ever drifts to chain_id /
chainId / camelCase / etc., the type fails compile BEFORE the #370
harness runtime assertions could catch it. Pin the names at the shim;
the adapter is then forced into compliance.

Slice-1-style additive contract preserved: SpanAttributes (broad
Record<string,...>) is still what setAttributes / StartSpanOptions.attributes
accept, so adapter-internal / diagnostic attrs aren't rejected;
ContinuationSpanAttrs is the canonical-contract pin enforced by tests
via assignment-to-SpanAttributes compile check.

Tests: 11/11 green (was 9/9; +2 type-pin tests).

Refs #334 #366 #370 #377

* feat(swim-37): #324 InMemorySpanRecorder shim + contract tests

Adds reusable in-memory span recorder for the swim-37 harness so
downstream test conversions can read span contract from a black-box
observer instead of redefining the recorder shape inline.

The recorder mirrors the `recordingTracer` pattern already used in
`src/infra/continuation-tracer.test.ts` (around L51-100), lifted into
a reusable harness helper. Stays STDOUT-only / in-process (no real
OTLP collector, no BasicTracerProvider) per harness discipline pinned
in studies/swim-37/harness/README.md.

Contract tests pin:
  - construction returns fresh independent recorders
  - startSpan records name + initial attributes + traceparent
  - setAttributes is last-write-wins per OTEL semantics
  - setStatus + recordException + end() round-trip
  - end() is idempotent
  - spansByName filters correctly
  - reset() clears records without un-installing the tracer
  - spans() returns a defensive copy

Integration tests pin that the recorder captures actual continuation.*
spans driven by the production emit* helpers — so harness tests can
trust the recorder as a black-box span observer:
  - emitContinuationWorkSpan stamps chain.id + chain.step.remaining (#366)
  - emitContinuationDelegateSpan stamps chain.id + delegate.delivery +
    delegate.mode (#366)
  - emitContinuationDelegateFireSpan carries fire.deferred_ms +
    persisted chain.id snapshot (#388 chunk 5b); drift formula
    pinned (drift = fire.deferred_ms − delay.ms)

Does NOT touch swim-runner.test.ts it.todos — those need the runner
(`captureSwim()`) which is separate scope. This PR ships the
foundation those conversions will read against.

Refs: #324 (swim-37 harness)
Refs: #366 (continuation.* spans)
Refs: #388 (chunk 5b/5c fire-span seams)
Base: cael/325-canonical2 tip 7390635 (post-#392)

* fix(swim-37): wire harness into enforced CI lanes + tighten doc-shape (🩸 byte-walk)

Cael caught: as initially submitted, the swim-37 harness code wasn't enforced
by repo CI. Three changes to close the drift surface:

1. **tsconfig.json**: add "studies/**/*" to `include`. Type-shape on the
   recorder + harness is now caught by tsgo / pnpm typecheck.

2. **test/vitest/vitest.swim-37.config.ts**: new vitest project entry
   (createScopedVitestConfig pattern, narrow include for
   studies/swim-37/harness/**/*.test.ts). Registered in
   test/vitest/vitest.config.ts `rootVitestProjects`.

3. **README.md §OTEL exporter**: rewrite to describe what shipped (custom
   recorder installed via setContinuationTracer(...), recording-tracer
   pattern lifted from continuation-tracer.test.ts) instead of the
   aspirational InMemorySpanExporter / provider-style framing from the
   original scaffold. Add §Vitest project section pointing at the
   wiring above.

4. **in-memory-span-recorder.ts doc-comment**: tighten "local-process-memory
   equivalent of OTEL's InMemorySpanExporter" to the concrete contract
   (in-process array, no provider, no exporter). The broader OTEL framing
   was load-bearing in the original scaffold but reads as forecasting
   plumbing the harness deliberately doesn't ship.

Local verification:
  - vitest --project swim-37 → 15 passed | 18 todo (project recognized)
  - tsgo --noEmit → no new errors under studies/swim-37/

Same-shape lesson as the chunk-6 memo byte-walk earlier today: shipping
the artifact while deferring the enforcement IS the drift surface. Fix
in PR rather than queue followup.

…405)

* test(swim-37): wire captureSwim() for continue_work primitive

Replaces the placeholder `declare function captureSwim` in
`studies/swim-37/harness/swim-runner.test.ts` with a real implementation
in `studies/swim-37/harness/swim-runner.ts`. The wired path drives
`emitContinuationWorkSpan` against `createInMemorySpanRecorder()` and
returns the captured spans + the synthesized `chainId` (uuid v7 via
`generateChainId`).

Flips two prior `it.todo` markers to live tests:
  - emits continuation.work span with chain.id stamped (#366)
  - span carries chain.step.remaining attribute

Plus three new live tests:
  - sentinel: captureSwim() is wired for continue_work
  - refuses continue_delegate / heartbeat / lich primitives with a clear
    error so the spec's remaining `it.todo` markers stay honest about
    what is implemented
  - repeated calls don't leak capture state between invocations

STDOUT-only discipline preserved: no BasicTracerProvider, no OTLP
exporter, no @opentelemetry/sdk-trace-base machinery — capture flows
through `setContinuationTracer(recorder.tracer)` as documented in
README.md.

Other primitives (`continue_delegate`, `heartbeat`, lich-shape) remain
`it.todo` until the corresponding dispatch / heartbeat /
compaction-release seams have a comparable single-helper entry point we
can drive synthetically.

Test results:
  - swim-37 vitest project: 20 passed, 16 todo, 0 failed
  - in-memory-span-recorder.test.ts unchanged (12/12 still pass)
  - tsgo errors visible elsewhere in tree are pre-existing
    (src/plugin-sdk/provider-tools.ts), not introduced by this change

Refs #324 (swim-37 harness) — `it.todo` count drops from 17 \u2192 16,
first concrete primitive driven through the live tracer registry.

* docs(swim-37): continue_delegate wiring memo (memo-before-wire)

Pre-PR design memo for the next swim-37 primitive after #405
(continue_work). Decides shape before the wire so the PR lands clean.

Resolved by reading production code:
  Q1 — real setTimeout vs fake timers
       N/A for dispatch-accept (synchronous, pre-timer); banked for
       a separate continue_delegate_fire swim.

Cohort sign-off requested on:
  Q2 — recipient fan-out shape: N spans sharing chain.id (matches
       chunk-3 cohort design pin + #355 Stage-2 budget semantics).
  Q3 — delegate.mode x delegate.delivery: 8-cell it.each matrix
       + omission-contract row.

Banked for follow-up:
  Q4 — continue_delegate_fire as separate primitive, not sub-case;
       informs SwimPrimitive type-union shape.

Standard applied (per Cael 2026-04-27 #1498505918, figs
#1498505870): would skipping this memo cost a chunk's worth of
rework? Yes — three open Qs would have changed file shape.

Refs:
  - #405 (continue_work wired)
  - #324 (swim-37 harness)
  - docs/design/334-slice2-chunk5b-delegate-fire-memo.md (pattern)

* test(swim-37): wire captureSwim() for continue_delegate primitive

Implements the design from
`docs/design/swim-37-continue-delegate-wiring-memo.md` (commit
3bb086c762, same branch).

Wiring (swim-runner.ts):
- New continue_delegate case in the switch.
- Adds CaptureSwimOptions axes: recipients, delivery, delegateMode.
- Drives emitContinuationDelegateSpan once per recipient with shared
  chain.id (per chunk-3 cohort design pin: N recipients = N spans
  sharing chain.id, NOT one span with a recipients list).
- Validates recipients is a positive integer.

Tests (swim-runner.test.ts):
- 8-cell it.each matrix: delegate.mode (normal | silent | silent-wake
  | post-compaction) x delegate.delivery (immediate | timer).
- Omission contract: delegate.mode attribute absent when caller
  passes undefined.
- Fan-out: 3 recipients emit 3 spans with shared chain.id.
- Validation: recipients=0 and recipients=1.5 reject.
- Removes the prior 'refuses continue_delegate' test row (now wired).

Two it.todo markers preserved for downstream concerns:
- chain-budget decrement / ChainBudget.declineToCarry observable
  (needs ChainBudget integration, not in scope here).
- fan-out budget arithmetic per #355 Stage-2 (1 step not N) \u2014
  separate from span cardinality.

Test results delta:
  Before: 8 passed | 16 todo (24 tests)
  After: 19 passed | 15 todo (34 tests)
  +11 live | -1 todo

Refs:
- #324 swim-37 harness
- #405 captureSwim continue_work (parent of this branch)
- docs/design/swim-37-continue-delegate-wiring-memo.md

* test(swim-37): pin recipient.index gap on continue_delegate fan-out

Per Cael's caution on the wiring memo (Discord msg
1498507232185286849 sign-off): N spans sharing chain.id risks
collapsing into analytic mush at scale unless per-recipient
distinction is visible in attrs. Currently
emitContinuationDelegateSpan exposes no recipient.index axis \u2014
all N spans in a fan-out are byte-identical except spanId.

Adds:
- One live GAP-PIN test asserting the current (deficient) reality:
  fan-out spans toEqual on attributes. This will fail loudly when
  the production helper grows the axis, prompting a flip to
  not.toEqual.
- One it.todo marker for the upcoming production-helper change.

Production-helper change is out of scope for this PR; will file
follow-up issue. The gap-pin lives in the integration tier so it
shows up in any code-review touching delegate-dispatch span shape.

Refs:
- #324 swim-37 harness
- #405 captureSwim continue_work + continue_delegate (this PR)
- docs/design/swim-37-continue-delegate-wiring-memo.md (Q2)
- Cael Discord sign-off msg 1498507232185286849

* test(swim-37): wire \u00a71 entry-point todo onto classifyRebasePick

Now that #408 (PR #408 merged at cb73bc8) landed
`rebase-classifier.ts` with the pure `classifyRebasePick` composer,
the integration-tier \u00a71 entry-point it.todo on swim-runner.test.ts
L80 is wireable without any new shim.

Synthetic commit pinned: subject mentions PR openclaw#70595, base CHANGELOG
contains the same PR token (squash-rebase shape from the memo's
7ee46a3 anchor instance). Discovery channel: changelog-grep:pr.

L81 (CHANGELOG-byte-grep emits drop-with-reason span) stays todo
\u2014 needs the production callsite that pairs the channel with
`emitContinuationDisabledSpan`, per \ud83c\udf0a's #408 note.

Test delta:
  Before: 20 passed | 16 todo (36)
  After: 21 passed | 15 todo (36)
  +1 live | -1 todo