@openrig/cli 0.3.1 → 0.3.3-rc.0

package/daemon/dist/domain/rigspec-instantiator.js

@@ -240,8 +240,8 @@ export class RigInstantiator {
 }
 // -- Pod-aware instantiator (AgentSpec reboot) --
 import { RigSpecCodec as PodRigSpecCodec } from "./rigspec-codec.js";
-import { RigSpecSchema as PodRigSpecSchema } from "./rigspec-schema.js";
-import { rigPreflight } from "./rigspec-preflight.js";
+import { RigSpecSchema as PodRigSpecSchema, VALID_EDGE_KINDS } from "./rigspec-schema.js";
+import { rigPreflight, preflightValidatedSpec } from "./rigspec-preflight.js";
 import { resolveAgentRef } from "./agent-resolver.js";
 import { resolveNodeConfig } from "./profile-resolver.js";
 import { resolveStartup } from "./startup-resolver.js";
@@ -296,6 +296,57 @@ export class PodRigInstantiator {
         if (!preflight.ready) {
             return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
         }
+        // OPR.0.3.3.24: parse/validate/preflight is the separable FRONT-END; the
+        // persistence CORE (createPod + create-node + edges + events, in one tx)
+        // takes the already-parsed+validated spec so `expand` and the `add_member`
+        // converge op compose it WITHOUT fabricating a synthetic rig spec.
+        return this.materializeValidatedSpec(rigSpec, rigRoot, opts);
+    }
+    /**
+     * materialize with a STRUCTURED front (OPR.0.3.3.24): the YAML-free sibling of
+     * materialize(). Runs the SAME front-end (validate + preflight, via the
+     * preflight CORE using this adapter's fsOps) on an already-built raw spec
+     * OBJECT, then the persistence core - so `expand` (and the add_member op) drop
+     * the synthetic-spec YAML round-trip. Byte-identical to materialize(yaml): same
+     * validate(externalQualifiedIds), same preflight checks, same MaterializeOutcome
+     * error codes (validation_failed / preflight_failed / target_rig_not_found /
+     * materialize_conflict). fsOps stays encapsulated here (the expansion service
+     * has none) - this wrapper is mechanics only, no behaviour/layering change.
+     */
+    async materializeStructured(raw, rigRoot, opts) {
+        const targetRig = opts?.targetRigId ? this.deps.rigRepo.getRig(opts.targetRigId) : null;
+        if (opts?.targetRigId && !targetRig) {
+            return { ok: false, code: "target_rig_not_found", message: `Rig "${opts.targetRigId}" not found` };
+        }
+        const validation = PodRigSpecSchema.validate(raw, {
+            externalQualifiedIds: targetRig?.nodes.map((node) => node.logicalId),
+        });
+        if (!validation.valid) {
+            return { ok: false, code: "validation_failed", errors: validation.errors };
+        }
+        const rigSpec = PodRigSpecSchema.normalize(raw);
+        const preflight = preflightValidatedSpec(rigSpec, {
+            rigRoot,
+            cwdOverride: opts?.cwdOverride,
+            fsOps: this.deps.fsOps,
+            rigNameOverride: targetRig?.rig.name,
+        });
+        if (!preflight.ready) {
+            return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
+        }
+        return this.materializeValidatedSpec(rigSpec, rigRoot, opts);
+    }
+    /**
+     * materialize CORE (OPR.0.3.3.24): the persistence body of materialize, taking
+     * an already-parsed + validated + preflighted PodRigSpec. Creates pods +
+     * member nodes (via the create-node primitive) + edges + events in one
+     * transaction. Parse/validate/preflight is the caller's separable front-end
+     * (materialize() for YAML; expand/add_member build + validate a structured
+     * spec). This is the cut that lets `expand` drop its synthetic-spec hack and
+     * `add_member` reuse the exact create path — create+launch only, no identity
+     * migration.
+     */
+    async materializeValidatedSpec(rigSpec, rigRoot, opts) {
         const persistedEvents = [];
         const nodeResults = [];
         try {
@@ -342,26 +393,17 @@ export class PodRigInstantiator {
                     }));
                     for (const member of pod.members) {
                         const qualifiedId = `${pod.id}.${member.id}`;
-                        const effectiveCwd = resolveLaunchCwd(member.cwd, rigRoot, opts?.cwdOverride);
-                        const node = this.deps.rigRepo.addNode(materializedRigId, qualifiedId, {
-                            runtime: member.runtime,
-                            model: member.model,
-                            codexConfigProfile: member.codexConfigProfile,
-                            cwd: effectiveCwd,
-                            restorePolicy: member.restorePolicy,
+                        const { node, event } = this.createMemberNode({
+                            rigId: materializedRigId,
+                            qualifiedId,
+                            member,
                             podId: podRecord.id,
-                            agentRef: member.agentRef,
-                            profile: member.profile,
-                            label: member.label,
+                            rigRoot,
+                            cwdOverride: opts?.cwdOverride,
                         });
                         logicalIdToNodeId.set(qualifiedId, node.id);
                         nodeResults.push({ logicalId: qualifiedId, status: "materialized" });
-                        persistedEvents.push(this.deps.eventBus.persistWithinTransaction({
-                            type: "node.added",
-                            rigId: materializedRigId,
-                            nodeId: node.id,
-                            logicalId: qualifiedId,
-                        }));
+                        persistedEvents.push(event);
                     }
                 }
                 for (const pod of rigSpec.pods) {
@@ -434,6 +476,17 @@ export class PodRigInstantiator {
             return { ok: false, code: "validation_failed", errors: validation.errors };
         }
         const rigSpec = PodRigSpecSchema.normalize(raw);
+        return this.launchValidatedSpec(rigSpec, rigRoot, targetRigId);
+    }
+    /**
+     * launch CORE (OPR.0.3.3.24): given an already-parsed+validated spec whose
+     * nodes are already materialized, compute launch order and bring each node
+     * live via the launch-binding primitive. Extracted from launchMaterialized so
+     * `expand` (and the add_member op) launch a structured spec WITHOUT a YAML
+     * round-trip; launchMaterialized(yaml) is the parse/validate/normalize front
+     * over it. Behaviour identical (loop body relocated verbatim).
+     */
+    async launchValidatedSpec(rigSpec, rigRoot, targetRigId) {
         const launchOrder = this.computePodLaunchOrder(rigSpec);
         const podWarnings = [];
         const nodeResults = [];
@@ -458,25 +511,15 @@ export class PodRigInstantiator {
                 });
                 continue;
             }
-            const launched = memberContext.member.agentRef === "builtin:terminal"
-                ? await this.launchExistingTerminalMember({
-                    rigId: targetRigId,
-                    rigSpec,
-                    rigRoot,
-                    pod: memberContext.pod,
-                    member: memberContext.member,
-                    qualifiedId: logicalId,
-                    nodeId: node.id,
-                })
-                : await this.launchExistingAgentMember({
-                    rigId: targetRigId,
-                    rigSpec,
-                    rigRoot,
-                    pod: memberContext.pod,
-                    member: memberContext.member,
-                    qualifiedId: logicalId,
-                    nodeId: node.id,
-                });
+            const launched = await this.launchBinding({
+                rigId: targetRigId,
+                rigSpec,
+                rigRoot,
+                pod: memberContext.pod,
+                member: memberContext.member,
+                qualifiedId: logicalId,
+                nodeId: node.id,
+            });
             if (launched.warnings?.length) {
                 podWarnings.push(...launched.warnings);
             }
@@ -496,6 +539,187 @@ export class PodRigInstantiator {
             },
         };
     }
+    /**
+     * add_member converge op (OPR.0.3.3.24): add a single MEMBER to an EXISTING
+     * pod in a live rig, composing the two extracted primitives — createMemberNode
+     * (create-node) + launchBinding (launch-binding) — WITHOUT createPod and
+     * WITHOUT fabricating a synthetic rig spec.
+     *
+     * Identity-migration-FREE: the new node mints a fresh node id + fresh logical
+     * id + fresh `@rigged_*` at launch; no existing seat's logical id,
+     * continuity_state, queue routing, or session is re-keyed. This is the
+     * source-visible fault line that lets add_member ship while move/fork wait for
+     * the 0.4.0 identity stack.
+     *
+     * Versus materialize: this does NOT call materializeValidatedSpec (which always
+     * createPods and carries the pod-exists conflict guard). It resolves the
+     * EXISTING pod's DB id via `podRepo.getPodByNamespace` and creates the one node
+     * directly under it. The pod-exists guard is lifted (adding to a live pod is
+     * not a conflict); the per-member duplicate-logical-id guard is KEPT (AC-3).
+     */
+    async addMemberToPod(rigId, podNamespace, memberFragment, rigRoot, opts) {
+        // 1. Resolve the rig.
+        const rig = this.deps.rigRepo.getRig(rigId);
+        if (!rig) {
+            return { ok: false, code: "rig_not_found", message: `Rig "${rigId}" not found.` };
+        }
+        // 2. Resolve the EXISTING pod's DB id via getPodByNamespace (the corrected
+        // pod-id source — NOT a pre-computed namespace->podId map). Honest not-found
+        // with the available namespaces so the caller can correct the handle.
+        const pod = this.deps.podRepo.getPodByNamespace(rigId, podNamespace);
+        if (!pod) {
+            const available = this.deps.podRepo.getPodsForRig(rigId).map((p) => p.namespace);
+            const hint = available.length > 0 ? available.join(", ") : "(none)";
+            return {
+                ok: false,
+                code: "pod_not_found",
+                message: `Pod "${podNamespace}" not found in rig "${rig.rig.name}". Existing pods: ${hint}. Check the namespace, or add a new pod with \`rig expand\`.`,
+            };
+        }
+        // 3. Build a minimal one-pod-one-member raw spec around the EXISTING pod so
+        // the new member runs the SAME validate + preflight the materialize front
+        // does — without a whole-rig spec or a YAML round-trip. The member fragment
+        // is embedded raw (spec snake_case shape, as expand's structured path emits);
+        // validate/normalize is the type gate.
+        const rawSpec = {
+            version: "0.2",
+            name: rig.rig.name,
+            pods: [{ id: podNamespace, label: pod.label, members: [memberFragment], edges: [] }],
+            edges: [],
+        };
+        // 4. Validate + normalize. externalQualifiedIds is the existing rig's node
+        // set (matches the materialize front; used for cross-pod edge resolution).
+        const validation = PodRigSpecSchema.validate(rawSpec, {
+            externalQualifiedIds: rig.nodes.map((node) => node.logicalId),
+        });
+        if (!validation.valid) {
+            return { ok: false, code: "validation_failed", errors: validation.errors };
+        }
+        const rigSpec = PodRigSpecSchema.normalize(rawSpec);
+        const member = rigSpec.pods[0].members[0];
+        const qualifiedId = `${podNamespace}.${member.id}`;
+        // 5. KEEP the per-member duplicate-logical-id guard (AC-3). The pod-exists
+        // guard is lifted (we are adding to a live pod on purpose), but minting a
+        // colliding logical id would be a real seat collision — reject it honestly.
+        // (validate's externalQualifiedIds only resolves edge targets; it does NOT
+        // reject a member colliding with an existing node, so this guard is load-bearing.)
+        if (rig.nodes.some((node) => node.logicalId === qualifiedId)) {
+            return {
+                ok: false,
+                code: "member_conflict",
+                message: `Member "${qualifiedId}" already exists in rig "${rig.rig.name}". Pick a different member id, or remove the existing seat first.`,
+            };
+        }
+        // 6. Preflight the new member on the normalized spec (same checks the
+        // materialize front runs, via the core, using this adapter's fsOps).
+        // rigNameOverride suppresses the rig-name-collision check (we are appending
+        // to an existing rig, exactly like expand's structured path).
+        const preflight = preflightValidatedSpec(rigSpec, {
+            rigRoot,
+            cwdOverride: opts?.cwdOverride,
+            fsOps: this.deps.fsOps,
+            rigNameOverride: rig.rig.name,
+        });
+        if (!preflight.ready) {
+            return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
+        }
+        // 7. Validate + resolve any declared pod-local edges BEFORE creating the
+        // node, so a bad edge fails fast with no orphan seat. Two honest failure
+        // classes: (a) DECLARATION validity (non-array / empty fields / a kind
+        // outside the canonical VALID_EDGE_KINDS - mirrors the rigspec pod-local
+        // edge contract, NOT a second looser path) -> validation_failed; (b) live
+        // ENDPOINT resolution against the new member + existing pod-mates ->
+        // edge_unresolved. Edges carry NO runtime behavior yet (the edge-runtime
+        // fence); we persist the declared graph so it is NOT silently dropped (FM2).
+        const rawEdges = opts?.edges;
+        if (rawEdges !== undefined && rawEdges !== null && !Array.isArray(rawEdges)) {
+            return { ok: false, code: "validation_failed", errors: ["edges: must be an array of { from, to, kind }"] };
+        }
+        const declaredEdges = Array.isArray(rawEdges) ? rawEdges : [];
+        const edgeErrors = [];
+        declaredEdges.forEach((edge, i) => {
+            if (typeof edge?.from !== "string" || typeof edge?.to !== "string" || typeof edge?.kind !== "string"
+                || edge.from.trim() === "" || edge.to.trim() === "" || edge.kind.trim() === "") {
+                edgeErrors.push(`edges[${i}]: from, to, and kind are required non-empty strings`);
+                return;
+            }
+            if (!VALID_EDGE_KINDS.has(edge.kind)) {
+                edgeErrors.push(`edges[${i}].kind: must be one of ${[...VALID_EDGE_KINDS].join(", ")} (got "${edge.kind}")`);
+            }
+        });
+        if (edgeErrors.length > 0) {
+            return { ok: false, code: "validation_failed", errors: edgeErrors };
+        }
+        const knownLogicalIds = new Set([...rig.nodes.map((node) => node.logicalId), qualifiedId]);
+        const resolvedEdges = [];
+        for (const edge of declaredEdges) {
+            const from = `${podNamespace}.${edge.from}`;
+            const to = `${podNamespace}.${edge.to}`;
+            if (!knownLogicalIds.has(from) || !knownLogicalIds.has(to)) {
+                const missing = !knownLogicalIds.has(from) ? from : to;
+                return { ok: false, code: "edge_unresolved", message: `Pod-local edge references "${missing}", which is neither the new member "${qualifiedId}" nor an existing seat in rig "${rig.rig.name}". Use member ids within pod "${podNamespace}".` };
+            }
+            resolvedEdges.push({ from, to, kind: edge.kind });
+        }
+        // 8. create-node into the EXISTING pod (pod_id = resolved pod.id) + persist
+        // the resolved pod-local edges, all in one tx so the node row, the
+        // node.added event, and the edges commit atomically (mirroring the
+        // materialize core); subscribers notified after commit.
+        let createdNodeId = "";
+        let createdEvent;
+        const tx = this.db.transaction(() => {
+            const { node, event } = this.createMemberNode({
+                rigId,
+                qualifiedId,
+                member,
+                podId: pod.id,
+                rigRoot,
+                cwdOverride: opts?.cwdOverride,
+            });
+            createdNodeId = node.id;
+            createdEvent = event;
+            if (resolvedEdges.length > 0) {
+                const logicalIdToNodeId = new Map(rig.nodes.map((n) => [n.logicalId, n.id]));
+                logicalIdToNodeId.set(qualifiedId, node.id);
+                for (const edge of resolvedEdges) {
+                    this.deps.rigRepo.addEdge(rigId, logicalIdToNodeId.get(edge.from), logicalIdToNodeId.get(edge.to), edge.kind);
+                }
+            }
+        });
+        tx();
+        if (createdEvent)
+            this.deps.eventBus.notifySubscribers(createdEvent);
+        // 9. launch-binding for the one new node (startup projection + delivery +
+        // readiness + `@rigged_*`). The minimal spec supplies the member/pod/rig
+        // context launchBinding needs; the derived session name is
+        // `${podNamespace}-${member.id}@${rig.name}` — queue-addressable immediately.
+        const launched = await this.launchBinding({
+            rigId,
+            rigSpec,
+            rigRoot,
+            pod: rigSpec.pods[0],
+            member,
+            qualifiedId,
+            nodeId: createdNodeId,
+            cwdOverride: opts?.cwdOverride,
+        });
+        return {
+            ok: true,
+            result: {
+                podId: pod.id,
+                podNamespace,
+                node: {
+                    logicalId: qualifiedId,
+                    nodeId: createdNodeId,
+                    status: launched.status,
+                    error: launched.error,
+                    sessionName: launched.sessionName,
+                },
+                edges: resolvedEdges,
+                warnings: launched.warnings,
+            },
+        };
+    }
     async instantiate(rigSpecYaml, rigRoot, opts) {
         // 1. Parse + validate
         let rigSpec;
@@ -515,7 +739,21 @@ export class PodRigInstantiator {
         if (!preflight.ready) {
             return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
         }
-        // 3. Create rig
+        // 3. Compute launch order from edges (rejects cycles)
+        //
+        // OPR.0.3.2.22 Bug 2: this MUST run BEFORE createRig. Pre-fix, a
+        // cycle in the spec left an orphan stopped-state rig record because
+        // createRig had already committed before the cycle check ran. The
+        // operator-facing consequence was the "ambiguous library-spec vs
+        // restore-target" UX trap on the very next `rig up <builtin>` retry.
+        let launchOrder;
+        try {
+            launchOrder = this.computePodLaunchOrder(rigSpec);
+        }
+        catch (err) {
+            return { ok: false, code: "cycle_error", message: err.message };
+        }
+        // 4. Create rig (after cycle check passes)
         let rigId;
         try {
             const rig = this.deps.rigRepo.createRig(rigSpec.name);
@@ -529,14 +767,6 @@ export class PodRigInstantiator {
         catch (err) {
             return { ok: false, code: "instantiate_error", message: err.message };
         }
-        // 4. Compute launch order from edges (rejects cycles)
-        let launchOrder;
-        try {
-            launchOrder = this.computePodLaunchOrder(rigSpec);
-        }
-        catch (err) {
-            return { ok: false, code: "cycle_error", message: err.message };
-        }
         // 5. Create pods + nodes + edges, then launch in topological order
         const nodeResults = [];
         const nodeIdMap = {}; // "pod.member" -> node DB id
@@ -568,10 +798,15 @@ export class PodRigInstantiator {
         // Sort members by topological launch order
         const orderMap = new Map(launchOrder.map((id, i) => [id, i]));
         memberEntries.sort((a, b) => (orderMap.get(a.qualifiedId) ?? 999) - (orderMap.get(b.qualifiedId) ?? 999));
-        // Prelaunch hook: service gate runs after topology setup, before any node launch
+        // Prelaunch hook: service gate runs after topology setup, before any node launch.
+        //
+        // OPR.0.3.2.22 Bug 2: if the hook fails, roll back the rig record so
+        // the spec name is left free for a clean retry. Pods rely on rigs
+        // via ON DELETE CASCADE so deleting the rig is sufficient.
         if (opts?.prelaunchHook) {
             const hookResult = await opts.prelaunchHook(rigId);
             if (!hookResult.ok) {
+                this.deps.rigRepo.deleteRig(rigId);
                 return { ok: false, code: "service_boot_failed", message: hookResult.message };
             }
         }
@@ -654,6 +889,8 @@ export class PodRigInstantiator {
                 logicalId: qualifiedId,
                 status: launched.status,
                 error: launched.error,
+                evidence: launched.evidence,
+                sessionName: launched.sessionName,
             });
         }
         // Create pod-local edges (after all members created)
@@ -680,9 +917,23 @@ export class PodRigInstantiator {
                 catch { /* best-effort */ }
             }
         }
-        // Check for total failure — kill orphan tmux sessions and clean up rig
-        const allFailed = nodeResults.length > 0 && nodeResults.every((n) => n.status === "failed");
-        if (allFailed) {
+        // OPR.0.3.2.CT (conveyor-trust-minimal-fix):
+        // Distinguish recoverable attention_required (e.g., workspace trust
+        // gate) from terminal failure. ANY attention_required node means
+        // the rig is operator-recoverable — do NOT tear down. Only when
+        // every node is TERMINALLY failed (status === "failed") does the
+        // tear-down run, preserving the existing failure-cleanup behavior.
+        //
+        // For all-attention_required (no successful launch, no terminal
+        // failure), surface an attention_required outcome that carries
+        // the actionable per-node detail. The route returns a 3-part
+        // error pointing the operator at the approve→resume path. Sessions
+        // remain in startup_status='attention_required' so `rig ps` lists
+        // them and tmux panes are NOT killed.
+        const hasAttention = nodeResults.some((n) => n.status === "attention_required");
+        const hasLaunched = nodeResults.some((n) => n.status === "launched");
+        const allTerminal = nodeResults.length > 0 && nodeResults.every((n) => n.status === "failed");
+        if (allTerminal) {
             // Kill orphan tmux sessions
             if (this.deps.tmuxAdapter) {
                 for (const sessionName of launchedSessionNames) {
@@ -699,14 +950,55 @@ export class PodRigInstantiator {
             const details = nodeResults.map((n) => `${n.logicalId}: ${n.error ?? "unknown"}`).join("; ");
             return { ok: false, code: "instantiate_error", message: `all node launches/startups failed — ${details}` };
         }
+        if (hasAttention && !hasLaunched) {
+            // All-attention_required path — rig + sessions PRESERVED; no
+            // tear-down. The operator's path: attach to a session via
+            // `tmux attach -t <session>` and answer the runtime prompt. NO
+            // new trust primitive
+            // introduced (HG-5); reuses the runtime's shipped in-pane
+            // trust-grant prompt.
+            const attentionNodes = nodeResults
+                .filter((n) => n.status === "attention_required")
+                .map((n) => ({
+                logicalId: n.logicalId,
+                sessionName: n.sessionName ?? "",
+                evidence: n.evidence,
+                reason: n.error ?? "node awaiting attention",
+            }));
+            // Emit rig.imported so callers see the rig exists; nodes are
+            // attention_required, not "launched", so `rig ps` shows the
+            // correct lifecycle state.
+            try {
+                this.deps.eventBus.emit({ type: "rig.imported", rigId, specName: rigSpec.name, specVersion: rigSpec.version });
+            }
+            catch { /* best-effort */ }
+            return {
+                ok: false,
+                code: "attention_required",
+                message: `${attentionNodes.length} node${attentionNodes.length === 1 ? "" : "s"} require attention before becoming interactive (rig parked, NOT failed; approve and resume to proceed).`,
+                rigId,
+                attentionNodes,
+            };
+        }
         // Emit rig.imported
         try {
             this.deps.eventBus.emit({ type: "rig.imported", rigId, specName: rigSpec.name, specVersion: rigSpec.version });
         }
         catch { /* best-effort */ }
+        // Carry sessionName + evidence through to InstantiateResult.nodes
+        // so BootstrapOrchestrator can build AttentionNode[] in the mixed
+        // launched+attention_required path (guard verdict
+        // qitem-20260518082933 BLOCKER 1).
+        const resultNodes = nodeResults.map((n) => ({
+            logicalId: n.logicalId,
+            status: n.status,
+            error: n.error,
+            sessionName: n.sessionName,
+            evidence: n.evidence,
+        }));
         return {
             ok: true,
-            result: { rigId, specName: rigSpec.name, specVersion: rigSpec.version, nodes: nodeResults, warnings: podInstantiateWarnings.length > 0 ? podInstantiateWarnings : undefined },
+            result: { rigId, specName: rigSpec.name, specVersion: rigSpec.version, nodes: resultNodes, warnings: podInstantiateWarnings.length > 0 ? podInstantiateWarnings : undefined },
         };
     }
     computePodLaunchOrder(rigSpec) {
@@ -826,6 +1118,50 @@ export class PodRigInstantiator {
         const member = pod?.members.find((entry) => entry.id === memberId);
         return pod && member ? { pod, member } : null;
     }
+    /**
+     * create-node primitive (OPR.0.3.3.24): mint a fresh node row for one member
+     * (fresh stable id + fresh qualified logical id, `pod_id` = the given pod) plus
+     * the matching `node.added` event. Extracted from materialize's loop so the
+     * `add_member` converge op and a de-YAML'd `expand` create a member node
+     * WITHOUT fabricating a synthetic rig spec. Identity-migration-FREE: addNode
+     * mints a brand-new identity; nothing existing re-keys. The caller pushes the
+     * returned `event` into its transaction's persisted-events list.
+     */
+    createMemberNode(input) {
+        const effectiveCwd = resolveLaunchCwd(input.member.cwd, input.rigRoot, input.cwdOverride);
+        const node = this.deps.rigRepo.addNode(input.rigId, input.qualifiedId, {
+            runtime: input.member.runtime,
+            model: input.member.model,
+            codexConfigProfile: input.member.codexConfigProfile,
+            cwd: effectiveCwd,
+            restorePolicy: input.member.restorePolicy,
+            podId: input.podId,
+            agentRef: input.member.agentRef,
+            profile: input.member.profile,
+            label: input.member.label,
+        });
+        const event = this.deps.eventBus.persistWithinTransaction({
+            type: "node.added",
+            rigId: input.rigId,
+            nodeId: node.id,
+            logicalId: input.qualifiedId,
+        });
+        return { node, event };
+    }
+    /**
+     * launch-binding primitive (OPR.0.3.3.24): given an already-created node and
+     * its member context, bring it fully live — harness launch + startup
+     * projection + delivery + readiness + `@rigged_*` metadata. Dispatches the
+     * terminal vs agent launch path. Extracted as an independently-callable
+     * primitive so launchMaterialized's loop, `expand`, and the `add_member`
+     * converge op all launch a node WITHOUT fabricating a synthetic rig spec.
+     * Behaviour is identical to the prior inline dispatch.
+     */
+    async launchBinding(input) {
+        return input.member.agentRef === "builtin:terminal"
+            ? this.launchExistingTerminalMember(input)
+            : this.launchExistingAgentMember(input);
+    }
     async launchExistingAgentMember(input) {
         const resolveResult = input.resolveResult ?? resolveAgentRef(input.member.agentRef, input.rigRoot, this.deps.fsOps);
         if (!resolveResult.ok) {
@@ -854,7 +1190,16 @@ export class PodRigInstantiator {
             return { status: "failed", error: sessionNameErrors.join("; ") };
         }
         const canonicalSessionName = deriveCanonicalSessionName(input.pod.id, input.member.id, input.rigSpec.name);
-        const launchResult = await this.deps.nodeLauncher.launchNode(input.rigId, input.qualifiedId, { sessionName: canonicalSessionName });
+        // Slice 15 — forward per-seat silenceWindowSeconds from the resolved
+        // profile.activity block. NodeLauncher applies the launcher default
+        // (3s) when this is undefined. The seat's tmux monitor-silence is
+        // configured immediately after createSession; SeatActivityService
+        // then reads window_activity to compute terminalActive against this
+        // threshold per poll.
+        const launchResult = await this.deps.nodeLauncher.launchNode(input.rigId, input.qualifiedId, {
+            sessionName: canonicalSessionName,
+            silenceWindowSeconds: configResult.config.activity?.silenceWindowSeconds,
+        });
         if (!launchResult.ok) {
             return { status: "failed", error: launchResult.message };
         }
@@ -920,7 +1265,8 @@ export class PodRigInstantiator {
         else if (input.member.sessionSource?.mode === "agent_image") {
             // PL-016 Item 4: agent_image → resolve via library + dispatch
             // through the native-fork code path so nativeResumeProbe
-            // semantics are preserved (architecture.md § Resume honesty).
+            // semantics are preserved
+            // (docs/as-built/architecture/adapters-and-runtimes.md § Resume honesty).
             const library = this.deps.agentImageLibrary;
             if (!library) {
                 return {
@@ -1028,9 +1374,22 @@ export class PodRigInstantiator {
                 console.warn(`[openrig] agent-image fork_count bump failed for ${consumedAgentImageId}: ${err.message}`);
             }
         }
+        // OPR.0.3.2.CT — preserve the attention_required distinction so
+        // the instantiator can leave a recoverable rig + sessions instead
+        // of zero-collapsing. The session row's startup_status was already
+        // persisted by startupOrchestrator.fail() (see startup-orchestrator.ts
+        // lines 223-225, 241-243).
+        if (startupResult.ok) {
+            return {
+                status: "launched",
+                sessionName: canonicalSessionName,
+                warnings: launchResult.warnings,
+            };
+        }
         return {
-            status: startupResult.ok ? "launched" : "failed",
-            error: startupResult.ok ? undefined : startupResult.errors.join("; "),
+            status: startupResult.startupStatus === "attention_required" ? "attention_required" : "failed",
+            error: startupResult.errors.join("; "),
+            evidence: startupResult.evidence,
             sessionName: canonicalSessionName,
             warnings: launchResult.warnings,
         };