opencode-swarm 7.194.0 → 7.196.0

package/dist/host/v2/session-client.d.ts

@@ -1,5 +1,5 @@
 /**
- * v2 session client shim — issue #3169 Phase 2.
+ * v2 session client shim — issue #3169 Phase 2 (+ Phase 3 lane sessions).
  *
  * A narrow `OpencodeClient` subset implementing exactly the v1 session surface
  * Epic's dispatch paths use (`session.create/prompt/abort/delete` plus `get`,
@@ -14,27 +14,36 @@
  * findings on @opencode/cli 2.0.26):
  *
  *   - `create({body:{parentID,title}, query:{directory}})` validates placement
- *     BEFORE creating anything: v2 child sessions inherit the parent's
- *     directory and ignore the requested one (Phase 0 C1 catch), so a divergent
- *     or unverifiable placement fails closed with a typed `{data: null,
- *     error}` result — routing worktree isolation to its existing degradation
- *     path instead of silently running a "lane" session in the project root.
- *     A passing precheck mints a placeholder id; the real v2 session is
- *     created at PROMPT time, when the v1 prompt body supplies the create-time
- *     options (agent/model/permissions) the published `SessionCreateInput`
- *     expects (issue R2: one session per dispatch contains the per-session
- *     shift).
+ *     BEFORE creating anything. Phase 3: a CONFIRMED parent-directory divergence
+ *     (the worktree-isolation lane shape — a lane worktree directory always
+ *     differs from the parent's project root) now takes the EAGER path: a REAL
+ *     parentless host session created immediately in the requested directory
+ *     (Phase 0 C1: parented children inherit the parent's directory; parentless
+ *     creates honor the requested one), placement verified post-create (echo,
+ *     `get` fallback) with a remove-and-fail-closed guard, and the requested
+ *     `parentID` REMEMBERED plugin-side and overlaid onto `get` results so
+ *     `prWorkflowSessionResolver`'s first-hop controller resolution
+ *     (`pr-workflow-session-resolver.ts`) and `lookupParentSessionIDForTaskRoute`
+ *     stay v1-faithful for parentless lane children (the host-side link is what
+ *     the v2 host cannot carry here). A real id is returned — the native
+ *     `subagent` tool resumes it by id (Phase 0 C7). Unverifiable parent
+ *     placement still fails closed with the Phase 2 typed error (live-verification
+ *     item), and same-directory/parentless creates keep the deferred placeholder
+ *     (the real create there must carry prompt-time options — permissions are
+ *     create-time-only on v2).
  *   - `prompt({path:{id}, body:{agent,model?,system?,tools,parts}, signal?})`
- *     emulates the v1 BLOCKING call: real create (carrying agent/model and the
- *     read-only denial map as `effect:'deny'` permissions) → one sessionID-
- *     scoped `context` hook that replaces `event.system` (fence-aware: parts
- *     carrying the `<swarm_system_directive` provenance fence survive, per
- *     #2526) and deletes denied keys from `event.tools` → `prompt` → bounded
- *     `wait` → `context()` translated into the v1 `{data:{info,parts}}`
- *     envelope so `dispatchEphemeralAgent` and `readProviderMessageError`
- *     work unchanged. A prompt addressed to a non-placeholder (real) session
- *     id takes a direct path without re-creating — the pr-event-delivery wake
- *     prompt shape.
+ *     emulates the v1 BLOCKING call over three arms keyed on the registry:
+ *     (1) an EAGER record → full treatment on the real session — `switchAgent` +
+ *     `switchModel`, a sessionID-scoped `context` hook (fence-aware system
+ *     replacement preserving `<swarm_system_directive` parts, denied-tool
+ *     deletion from `event.tools`), epoch-scoped error clear, `prompt` →
+ *     bounded `wait` → `context()`; (2) a deferred/already-prompted PLACEHOLDER
+ *     → real create carrying agent/model + the read-only denial map as
+ *     `effect:'deny'` permissions, then the same hook/prompt/wait/context
+ *     sequence, with the #3186 PRR-002 retire-and-recreate on re-prompts;
+ *     (3) a foreign real id → the direct path (agent switch only). All three
+ *     translate into the v1 `{data:{info,parts}}` envelope so
+ *     `dispatchEphemeralAgent` and `readProviderMessageError` work unchanged.
  *   - Provider failures are EVENT-SOURCED on v2 (Phase 0 C4: no error text in
  *     `context()`), so the event pump records `session.error` /
  *     `session.execution.failed` payloads here (`recordV2SessionErrorFromEnvelope`,
@@ -42,15 +51,25 @@
  *     translation surfaces them as the v1 `info.error` shape. A failed outcome
  *     without recorded detail yields a bounded `provider.unknown` error
  *     instead of a silent empty success.
- *   - `abort` maps to `interrupt`, `delete` to `remove`, `get` to the v2 get
- *     (unresolved placeholders read as `{data: null}` — never prompted means
- *     gone, satisfying `teardownEphemeralSessionVerified`).
+ *   - `abort` maps to `interrupt`, `delete` to `remove` (eager records are
+ *     pruned after the removal resolves — the id is real, so a later `get`
+ *     still resolves through to a host that reports the session gone), and
+ *     `get` maps `{path:{id}}` onto `ctx.session.get({sessionID})` returning
+ *     `{data: info}` — verified teardown through the shim resolves.
+ *
+ * Registry (invariant 8): placeholder and eager records share ONE bounded map
+ * (cap 64, FIFO). Placeholder residue is intentionally not pruned (keep-for-get);
+ * that residue shares the cap, so a live eager record can be evicted after 64
+ * later insertions of any kind — a disclosed, bounded degradation (its next
+ * prompt takes the direct path and the parentID overlay stops applying), pinned
+ * in tests/unit/host/v2/session-client-lane-3169.test.ts.
  *
  * Deferred-work marker: NONE. The unverified live-host behaviors this design
  * rests on are recorded as deferrals in the trace (context-hook firing for
  * plugin-created sessions, permission vocabulary honor, `context()` entry
- * shapes, `wait` on failed prompts, `get(parent).location` availability) with
- * the owning follow-up on #3169.
+ * shapes, `wait` on failed prompts, `get(parent).location` availability,
+ * parentless subagent resume + parentID overlay — LVD-1..LVD-4) with the owning
+ * follow-up on #3169.
  *
  * C6 await convention: every `await` lives inside a `deferredV2Session*`
  * function declaration or `const deferredV2SessionX = async (` binding — the