@openrig/cli 0.0.1 → 0.1.1

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

@@ -0,0 +1,1104 @@
+import nodePath from "node:path";
+import { deriveCanonicalSessionName, validateSessionComponents } from "./session-name.js";
+import { LegacyRigSpecSchema as RigSpecSchema } from "./rigspec-schema.js"; // TODO: AS-T08b — migrate to pod-aware RigSpec
+import { LegacyRigSpecCodec as RigSpecCodec } from "./rigspec-codec.js"; // TODO: AS-T08b — migrate to pod-aware RigSpec
+// Only these edge kinds constrain launch order
+const LAUNCH_DEPENDENCY_KINDS = new Set(["delegates_to", "spawned_by"]);
+export class RigInstantiator {
+    db;
+    rigRepo;
+    sessionRegistry;
+    eventBus;
+    nodeLauncher;
+    preflight;
+    tmuxAdapter;
+    constructor(deps) {
+        if (deps.db !== deps.rigRepo.db) {
+            throw new Error("RigInstantiator: rigRepo must share the same db handle");
+        }
+        if (deps.db !== deps.sessionRegistry.db) {
+            throw new Error("RigInstantiator: sessionRegistry must share the same db handle");
+        }
+        if (deps.db !== deps.eventBus.db) {
+            throw new Error("RigInstantiator: eventBus must share the same db handle");
+        }
+        if (deps.db !== deps.nodeLauncher.db) {
+            throw new Error("RigInstantiator: nodeLauncher must share the same db handle");
+        }
+        if (deps.db !== deps.preflight.db) {
+            throw new Error("RigInstantiator: preflight must share the same db handle");
+        }
+        this.db = deps.db;
+        this.rigRepo = deps.rigRepo;
+        this.sessionRegistry = deps.sessionRegistry;
+        this.eventBus = deps.eventBus;
+        this.nodeLauncher = deps.nodeLauncher;
+        this.preflight = deps.preflight;
+        this.tmuxAdapter = deps.tmuxAdapter;
+    }
+    async instantiate(spec) {
+        // 1. Validate
+        const raw = RigSpecCodec.parse(RigSpecCodec.serialize(spec));
+        const validation = RigSpecSchema.validate(raw);
+        if (!validation.valid) {
+            return { ok: false, code: "validation_failed", errors: validation.errors };
+        }
+        // 2. Preflight
+        const preflightResult = await this.preflight.check(spec);
+        if (!preflightResult.ready) {
+            return { ok: false, code: "preflight_failed", errors: preflightResult.errors, warnings: preflightResult.warnings };
+        }
+        // 3. Compute launch order BEFORE materialization (detect cycles early)
+        let launchOrder;
+        try {
+            launchOrder = this.computeLaunchOrder(spec);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: "instantiate_error",
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+        // 4. Atomic DB materialization: rig + nodes + edges
+        let rigId;
+        const nodeIdMap = {}; // logicalId -> DB id
+        try {
+            const txn = this.db.transaction(() => {
+                const rig = this.rigRepo.createRig(spec.name);
+                rigId = rig.id;
+                for (const specNode of spec.nodes) {
+                    const node = this.rigRepo.addNode(rig.id, specNode.id, {
+                        role: specNode.role,
+                        runtime: specNode.runtime,
+                        model: specNode.model,
+                        cwd: specNode.cwd,
+                        surfaceHint: specNode.surfaceHint,
+                        workspace: specNode.workspace,
+                        restorePolicy: specNode.restorePolicy,
+                        packageRefs: specNode.packageRefs,
+                    });
+                    nodeIdMap[specNode.id] = node.id;
+                }
+                for (const specEdge of spec.edges) {
+                    this.rigRepo.addEdge(rig.id, nodeIdMap[specEdge.from], nodeIdMap[specEdge.to], specEdge.kind);
+                }
+            });
+            txn();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: "instantiate_error",
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+        // 5. Launch nodes in topological order
+        const nodeResults = [];
+        const launchedSessionNames = [];
+        const instantiateWarnings = [];
+        for (const logicalId of launchOrder) {
+            const result = await this.nodeLauncher.launchNode(rigId, logicalId);
+            if (result.ok) {
+                nodeResults.push({ logicalId, status: "launched" });
+                launchedSessionNames.push(result.sessionName);
+                if (result.warnings?.length) {
+                    instantiateWarnings.push(...result.warnings);
+                }
+            }
+            else {
+                nodeResults.push({ logicalId, status: "failed", error: result.message });
+            }
+        }
+        // Check for total launch failure — kill orphan sessions and clean up the rig
+        const allFailed = nodeResults.every((n) => n.status === "failed");
+        if (allFailed && nodeResults.length > 0) {
+            // Kill orphan tmux sessions (best-effort)
+            if (this.tmuxAdapter) {
+                for (const sessionName of launchedSessionNames) {
+                    try {
+                        await this.tmuxAdapter.killSession(sessionName);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            try {
+                this.rigRepo.deleteRig(rigId);
+            }
+            catch {
+                // Best-effort cleanup
+            }
+            return {
+                ok: false,
+                code: "instantiate_error",
+                message: "all node launches failed",
+            };
+        }
+        // 6. Propagate restorePolicy to session metadata (best-effort)
+        try {
+            for (const specNode of spec.nodes) {
+                const restorePolicy = specNode.restorePolicy ?? "resume_if_possible";
+                const sessions = this.sessionRegistry.getSessionsForRig(rigId);
+                const nodeDbId = nodeIdMap[specNode.id];
+                const session = sessions.find((s) => s.nodeId === nodeDbId);
+                if (session) {
+                    this.db.prepare("UPDATE sessions SET restore_policy = ? WHERE id = ?")
+                        .run(restorePolicy, session.id);
+                }
+            }
+        }
+        catch {
+            // Best-effort: import succeeded even if restorePolicy propagation fails
+        }
+        // 6. Emit rig.imported (best-effort)
+        try {
+            this.eventBus.emit({
+                type: "rig.imported",
+                rigId: rigId,
+                specName: spec.name,
+                specVersion: spec.version,
+            });
+        }
+        catch {
+            // Best-effort: import succeeded even if event persistence fails
+        }
+        return {
+            ok: true,
+            result: {
+                rigId: rigId,
+                specName: spec.name,
+                specVersion: spec.version,
+                nodes: nodeResults,
+                warnings: instantiateWarnings.length > 0 ? instantiateWarnings : undefined,
+            },
+        };
+    }
+    computeLaunchOrder(spec) {
+        const nodes = spec.nodes;
+        const edges = spec.edges;
+        const inDegree = {};
+        const adjacency = {};
+        for (const node of nodes) {
+            inDegree[node.id] = 0;
+            adjacency[node.id] = [];
+        }
+        for (const edge of edges) {
+            if (!LAUNCH_DEPENDENCY_KINDS.has(edge.kind))
+                continue;
+            let from;
+            let to;
+            if (edge.kind === "delegates_to") {
+                from = edge.from;
+                to = edge.to;
+            }
+            else {
+                // spawned_by: target (parent) before source (child)
+                from = edge.to;
+                to = edge.from;
+            }
+            if (adjacency[from]) {
+                adjacency[from].push(to);
+                inDegree[to] = (inDegree[to] ?? 0) + 1;
+            }
+        }
+        // Topological sort with alphabetical tiebreaker
+        const queue = Object.keys(inDegree)
+            .filter((id) => inDegree[id] === 0)
+            .sort();
+        const order = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            order.push(current);
+            const neighbors = (adjacency[current] ?? []).slice().sort();
+            for (const neighbor of neighbors) {
+                inDegree[neighbor] = (inDegree[neighbor] ?? 1) - 1;
+                if ((inDegree[neighbor] ?? 0) === 0) {
+                    // Insert sorted
+                    let inserted = false;
+                    for (let i = 0; i < queue.length; i++) {
+                        if (queue[i].localeCompare(neighbor) > 0) {
+                            queue.splice(i, 0, neighbor);
+                            inserted = true;
+                            break;
+                        }
+                    }
+                    if (!inserted)
+                        queue.push(neighbor);
+                }
+            }
+        }
+        // Cycle detection: if not all nodes reached, there's a cycle
+        if (order.length !== nodes.length) {
+            const missing = nodes.filter((n) => !order.includes(n.id)).map((n) => n.id);
+            throw new Error(`Dependency cycle detected among nodes: ${missing.join(", ")}`);
+        }
+        return order;
+    }
+}
+// -- 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 { resolveAgentRef } from "./agent-resolver.js";
+import { resolveNodeConfig } from "./profile-resolver.js";
+import { resolveStartup } from "./startup-resolver.js";
+import { planProjection } from "./projection-planner.js";
+import { resolveConcreteHint } from "./runtime-adapter.js";
+/**
+ * Pod-aware rig instantiator. Creates pods, nodes, edges, and runs
+ * startup orchestration per node with resolved agent specs.
+ */
+export class PodRigInstantiator {
+    db;
+    deps;
+    constructor(deps) {
+        if (deps.db !== deps.rigRepo.db)
+            throw new Error("PodRigInstantiator: rigRepo must share the same db handle");
+        if (deps.db !== deps.sessionRegistry.db)
+            throw new Error("PodRigInstantiator: sessionRegistry must share the same db handle");
+        if (deps.db !== deps.eventBus.db)
+            throw new Error("PodRigInstantiator: eventBus must share the same db handle");
+        if (deps.db !== deps.nodeLauncher.db)
+            throw new Error("PodRigInstantiator: nodeLauncher must share the same db handle");
+        this.db = deps.db;
+        this.deps = deps;
+    }
+    async materialize(rigSpecYaml, rigRoot, opts) {
+        let raw;
+        try {
+            raw = PodRigSpecCodec.parse(rigSpecYaml);
+        }
+        catch (err) {
+            return { ok: false, code: "validation_failed", errors: [err.message] };
+        }
+        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 = rigPreflight({
+            rigSpecYaml,
+            rigRoot,
+            fsOps: this.deps.fsOps,
+            rigNameOverride: targetRig?.rig.name,
+            externalQualifiedIds: targetRig?.nodes.map((node) => node.logicalId),
+        });
+        if (!preflight.ready) {
+            return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
+        }
+        const persistedEvents = [];
+        const nodeResults = [];
+        try {
+            let materializedRigId = opts?.targetRigId ?? "";
+            const tx = this.db.transaction(() => {
+                if (!materializedRigId) {
+                    const rig = this.deps.rigRepo.createRig(rigSpec.name);
+                    materializedRigId = rig.id;
+                    persistedEvents.push(this.deps.eventBus.persistWithinTransaction({ type: "rig.created", rigId: materializedRigId }));
+                }
+                const currentRig = this.deps.rigRepo.getRig(materializedRigId);
+                const logicalIdToNodeId = new Map(currentRig.nodes.map((node) => [node.logicalId, node.id]));
+                const existingPodIds = new Set(currentRig.nodes
+                    .map((node) => node.logicalId.includes(".") ? node.logicalId.split(".")[0] : null)
+                    .filter((value) => value !== null));
+                for (const pod of rigSpec.pods) {
+                    if (existingPodIds.has(pod.id)) {
+                        throw { code: "materialize_conflict", message: `Pod id '${pod.id}' already exists in rig '${currentRig.rig.name}'` };
+                    }
+                    for (const member of pod.members) {
+                        const qualifiedId = `${pod.id}.${member.id}`;
+                        if (logicalIdToNodeId.has(qualifiedId)) {
+                            throw { code: "materialize_conflict", message: `Logical ID '${qualifiedId}' already exists in rig '${currentRig.rig.name}'` };
+                        }
+                    }
+                }
+                const podIdMap = {};
+                for (const pod of rigSpec.pods) {
+                    const podRecord = this.deps.podRepo.createPod(materializedRigId, pod.id, pod.label, {
+                        summary: pod.summary,
+                        continuityPolicyJson: pod.continuityPolicy ? JSON.stringify(pod.continuityPolicy) : undefined,
+                    });
+                    podIdMap[pod.id] = podRecord.id;
+                    persistedEvents.push(this.deps.eventBus.persistWithinTransaction({
+                        type: "pod.created",
+                        rigId: materializedRigId,
+                        podId: podRecord.id,
+                        namespace: podRecord.namespace,
+                        label: pod.label,
+                    }));
+                    for (const member of pod.members) {
+                        const qualifiedId = `${pod.id}.${member.id}`;
+                        const node = this.deps.rigRepo.addNode(materializedRigId, qualifiedId, {
+                            runtime: member.runtime,
+                            model: member.model,
+                            cwd: member.cwd,
+                            restorePolicy: member.restorePolicy,
+                            podId: podRecord.id,
+                            agentRef: member.agentRef,
+                            profile: member.profile,
+                            label: member.label,
+                        });
+                        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,
+                        }));
+                    }
+                }
+                for (const pod of rigSpec.pods) {
+                    for (const edge of pod.edges) {
+                        const fromId = logicalIdToNodeId.get(`${pod.id}.${edge.from}`);
+                        const toId = logicalIdToNodeId.get(`${pod.id}.${edge.to}`);
+                        if (!fromId || !toId) {
+                            throw { code: "materialize_conflict", message: `Pod-local edge references missing node: ${pod.id}.${edge.from} -> ${pod.id}.${edge.to}` };
+                        }
+                        this.deps.rigRepo.addEdge(materializedRigId, fromId, toId, edge.kind);
+                    }
+                }
+                for (const edge of rigSpec.edges) {
+                    const fromId = logicalIdToNodeId.get(edge.from);
+                    const toId = logicalIdToNodeId.get(edge.to);
+                    if (!fromId || !toId) {
+                        throw { code: "materialize_conflict", message: `Cross-pod edge references missing node: ${edge.from} -> ${edge.to}` };
+                    }
+                    this.deps.rigRepo.addEdge(materializedRigId, fromId, toId, edge.kind);
+                }
+                if (!opts?.suppressSummaryEvent) {
+                    persistedEvents.push(this.deps.eventBus.persistWithinTransaction({
+                        type: "rig.imported",
+                        rigId: materializedRigId,
+                        specName: rigSpec.name,
+                        specVersion: rigSpec.version,
+                    }));
+                }
+            });
+            tx();
+            for (const event of persistedEvents) {
+                this.deps.eventBus.notifySubscribers(event);
+            }
+            return {
+                ok: true,
+                result: {
+                    rigId: materializedRigId,
+                    specName: rigSpec.name,
+                    specVersion: rigSpec.version,
+                    nodes: nodeResults,
+                },
+            };
+        }
+        catch (err) {
+            if (err && typeof err === "object" && "code" in err && "message" in err) {
+                const typed = err;
+                if (typed.code === "materialize_conflict") {
+                    return { ok: false, code: "materialize_conflict", message: typed.message };
+                }
+            }
+            return { ok: false, code: "materialize_error", message: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async launchMaterialized(rigSpecYaml, rigRoot, targetRigId) {
+        let raw;
+        try {
+            raw = PodRigSpecCodec.parse(rigSpecYaml);
+        }
+        catch (err) {
+            return { ok: false, code: "validation_failed", errors: [err.message] };
+        }
+        const targetRig = this.deps.rigRepo.getRig(targetRigId);
+        if (!targetRig) {
+            return { ok: false, code: "target_rig_not_found", message: `Rig "${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 launchOrder = this.computePodLaunchOrder(rigSpec);
+        const podWarnings = [];
+        const nodeResults = [];
+        for (const logicalId of launchOrder) {
+            const memberContext = this.findMemberContext(rigSpec, logicalId);
+            if (!memberContext) {
+                nodeResults.push({
+                    logicalId,
+                    nodeId: "",
+                    status: "failed",
+                    error: `Unable to resolve member definition for "${logicalId}"`,
+                });
+                continue;
+            }
+            const node = this.deps.rigRepo.getRig(targetRigId)?.nodes.find((entry) => entry.logicalId === logicalId);
+            if (!node) {
+                nodeResults.push({
+                    logicalId,
+                    nodeId: "",
+                    status: "failed",
+                    error: `Node "${logicalId}" not found after materialization`,
+                });
+                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,
+                });
+            if (launched.warnings?.length) {
+                podWarnings.push(...launched.warnings);
+            }
+            nodeResults.push({
+                logicalId,
+                nodeId: node.id,
+                status: launched.status,
+                error: launched.error,
+                sessionName: launched.sessionName,
+            });
+        }
+        return {
+            ok: true,
+            result: {
+                nodes: nodeResults,
+                warnings: podWarnings.length > 0 ? podWarnings : undefined,
+            },
+        };
+    }
+    async instantiate(rigSpecYaml, rigRoot) {
+        // 1. Parse + validate
+        let rigSpec;
+        try {
+            const raw = PodRigSpecCodec.parse(rigSpecYaml);
+            const validation = PodRigSpecSchema.validate(raw);
+            if (!validation.valid) {
+                return { ok: false, code: "validation_failed", errors: validation.errors };
+            }
+            rigSpec = PodRigSpecSchema.normalize(raw);
+        }
+        catch (err) {
+            return { ok: false, code: "validation_failed", errors: [err.message] };
+        }
+        // 2. Preflight
+        const preflight = rigPreflight({ rigSpecYaml, rigRoot, fsOps: this.deps.fsOps });
+        if (!preflight.ready) {
+            return { ok: false, code: "preflight_failed", errors: preflight.errors, warnings: preflight.warnings };
+        }
+        // 3. Create rig
+        let rigId;
+        try {
+            const rig = this.deps.rigRepo.createRig(rigSpec.name);
+            rigId = rig.id;
+        }
+        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
+        const launchedSessionNames = []; // Track for orphan cleanup on total failure
+        const podInstantiateWarnings = [];
+        // Store per-member context for deferred launch
+        const memberContext = new Map();
+        // Phase 1: Create all pods and collect member entries
+        const podIdMap = {}; // pod.id -> DB pod id
+        const memberEntries = [];
+        for (const pod of rigSpec.pods) {
+            let podId;
+            try {
+                const podRecord = this.deps.podRepo.createPod(rigId, pod.id, pod.label, {
+                    summary: pod.summary,
+                    continuityPolicyJson: pod.continuityPolicy ? JSON.stringify(pod.continuityPolicy) : undefined,
+                });
+                podId = podRecord.id;
+                podIdMap[pod.id] = podId;
+            }
+            catch (err) {
+                nodeResults.push(...pod.members.map((m) => ({ logicalId: `${pod.id}.${m.id}`, status: "failed", error: `Pod creation failed: ${err.message}` })));
+                continue;
+            }
+            for (const member of pod.members) {
+                memberEntries.push({ pod, member, podId, qualifiedId: `${pod.id}.${member.id}` });
+            }
+        }
+        // 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));
+        // Phase 2: Process members in launch order
+        for (const { pod, member, podId, qualifiedId } of memberEntries) {
+            // Terminal fast-path: skip agent resolution and profile resolution
+            if (member.agentRef === "builtin:terminal") {
+                const termResult = await this.processTerminalMember(rigId, rigSpec, rigRoot, pod, member, podId, qualifiedId, nodeIdMap, launchedSessionNames, podInstantiateWarnings);
+                nodeResults.push(termResult);
+                continue;
+            }
+            // Resolve agent ref
+            const resolveResult = resolveAgentRef(member.agentRef, rigRoot, this.deps.fsOps);
+            if (!resolveResult.ok) {
+                const msg = resolveResult.code === "validation_failed"
+                    ? resolveResult.errors.join("; ")
+                    : resolveResult.error;
+                nodeResults.push({ logicalId: qualifiedId, status: "failed", error: msg });
+                continue;
+            }
+            // Resolve node config (profile + precedence)
+            const configResult = resolveNodeConfig({
+                baseSpec: resolveResult.resolved,
+                importedSpecs: resolveResult.imports,
+                collisions: resolveResult.collisions,
+                profileName: member.profile,
+                member,
+                pod,
+                rig: rigSpec,
+            });
+            if (!configResult.ok) {
+                nodeResults.push({ logicalId: qualifiedId, status: "failed", error: configResult.errors.join("; ") });
+                continue;
+            }
+            // Create node
+            let nodeId;
+            try {
+                const node = this.deps.rigRepo.addNode(rigId, qualifiedId, {
+                    runtime: member.runtime,
+                    model: member.model,
+                    cwd: member.cwd,
+                    restorePolicy: configResult.config.restorePolicy,
+                    podId,
+                    agentRef: member.agentRef,
+                    profile: member.profile,
+                    label: member.label,
+                    resolvedSpecName: configResult.config.resolvedSpecName,
+                    resolvedSpecVersion: configResult.config.resolvedSpecVersion,
+                    resolvedSpecHash: configResult.config.resolvedSpecHash,
+                });
+                nodeId = node.id;
+                nodeIdMap[qualifiedId] = nodeId;
+            }
+            catch (err) {
+                nodeResults.push({ logicalId: qualifiedId, status: "failed", error: err.message });
+                continue;
+            }
+            const launched = await this.launchExistingAgentMember({
+                rigId,
+                rigSpec,
+                rigRoot,
+                pod,
+                member,
+                qualifiedId,
+                nodeId,
+                resolveResult,
+                configResult,
+            });
+            if (launched.sessionName) {
+                launchedSessionNames.push(launched.sessionName);
+            }
+            if (launched.warnings?.length) {
+                podInstantiateWarnings.push(...launched.warnings);
+            }
+            nodeResults.push({
+                logicalId: qualifiedId,
+                status: launched.status,
+                error: launched.error,
+            });
+        }
+        // Create pod-local edges (after all members created)
+        for (const pod of rigSpec.pods) {
+            for (const edge of pod.edges) {
+                const fromId = nodeIdMap[`${pod.id}.${edge.from}`];
+                const toId = nodeIdMap[`${pod.id}.${edge.to}`];
+                if (fromId && toId) {
+                    try {
+                        this.deps.rigRepo.addEdge(rigId, fromId, toId, edge.kind);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+        // Create cross-pod edges
+        for (const edge of rigSpec.edges) {
+            const fromId = nodeIdMap[edge.from];
+            const toId = nodeIdMap[edge.to];
+            if (fromId && toId) {
+                try {
+                    this.deps.rigRepo.addEdge(rigId, fromId, toId, edge.kind);
+                }
+                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) {
+            // Kill orphan tmux sessions
+            if (this.deps.tmuxAdapter) {
+                for (const sessionName of launchedSessionNames) {
+                    try {
+                        await this.deps.tmuxAdapter.killSession(sessionName);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            try {
+                this.deps.rigRepo.deleteRig(rigId);
+            }
+            catch { /* best-effort */ }
+            const details = nodeResults.map((n) => `${n.logicalId}: ${n.error ?? "unknown"}`).join("; ");
+            return { ok: false, code: "instantiate_error", message: `all node launches/startups failed — ${details}` };
+        }
+        // Emit rig.imported
+        try {
+            this.deps.eventBus.emit({ type: "rig.imported", rigId, specName: rigSpec.name, specVersion: rigSpec.version });
+        }
+        catch { /* best-effort */ }
+        return {
+            ok: true,
+            result: { rigId, specName: rigSpec.name, specVersion: rigSpec.version, nodes: nodeResults, warnings: podInstantiateWarnings.length > 0 ? podInstantiateWarnings : undefined },
+        };
+    }
+    computePodLaunchOrder(rigSpec) {
+        const LAUNCH_DEP_KINDS = new Set(["delegates_to", "spawned_by"]);
+        const allIds = [];
+        const inDegree = {};
+        const adjacency = {};
+        // Collect all qualified member ids
+        for (const pod of rigSpec.pods) {
+            for (const member of pod.members) {
+                const qid = `${pod.id}.${member.id}`;
+                allIds.push(qid);
+                inDegree[qid] = 0;
+                adjacency[qid] = [];
+            }
+        }
+        // Build adjacency from pod-local edges (qualify them) and cross-pod edges (already qualified)
+        for (const pod of rigSpec.pods) {
+            for (const edge of pod.edges) {
+                if (!LAUNCH_DEP_KINDS.has(edge.kind))
+                    continue;
+                const from = `${pod.id}.${edge.kind === "delegates_to" ? edge.from : edge.to}`;
+                const to = `${pod.id}.${edge.kind === "delegates_to" ? edge.to : edge.from}`;
+                if (adjacency[from]) {
+                    adjacency[from].push(to);
+                    inDegree[to] = (inDegree[to] ?? 0) + 1;
+                }
+            }
+        }
+        for (const edge of rigSpec.edges) {
+            if (!LAUNCH_DEP_KINDS.has(edge.kind))
+                continue;
+            const from = edge.kind === "delegates_to" ? edge.from : edge.to;
+            const to = edge.kind === "delegates_to" ? edge.to : edge.from;
+            if (adjacency[from] && adjacency[to]) {
+                adjacency[from].push(to);
+                inDegree[to] = (inDegree[to] ?? 0) + 1;
+            }
+        }
+        // Topological sort with alphabetical tiebreaker
+        const queue = allIds.filter((id) => inDegree[id] === 0).sort();
+        const order = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            order.push(current);
+            for (const neighbor of (adjacency[current] ?? []).sort()) {
+                inDegree[neighbor] -= 1;
+                if (inDegree[neighbor] === 0) {
+                    let inserted = false;
+                    for (let i = 0; i < queue.length; i++) {
+                        if (queue[i].localeCompare(neighbor) > 0) {
+                            queue.splice(i, 0, neighbor);
+                            inserted = true;
+                            break;
+                        }
+                    }
+                    if (!inserted)
+                        queue.push(neighbor);
+                }
+            }
+        }
+        // Cycle detection: if any nodes remain unvisited, the graph has a cycle
+        if (order.length < allIds.length) {
+            const cycled = allIds.filter((id) => !order.includes(id));
+            throw new Error(`Dependency cycle detected among nodes: ${cycled.join(", ")}`);
+        }
+        return order;
+    }
+    async processTerminalMember(rigId, rigSpec, rigRoot, pod, member, podId, qualifiedId, nodeIdMap, launchedSessionNames, warnings) {
+        // Create node with sentinel values
+        let nodeId;
+        try {
+            const node = this.deps.rigRepo.addNode(rigId, qualifiedId, {
+                runtime: member.runtime,
+                model: member.model,
+                cwd: member.cwd,
+                restorePolicy: "checkpoint_only",
+                podId,
+                agentRef: member.agentRef,
+                profile: member.profile,
+                label: member.label,
+            });
+            nodeId = node.id;
+            nodeIdMap[qualifiedId] = nodeId;
+        }
+        catch (err) {
+            return { logicalId: qualifiedId, status: "failed", error: err.message };
+        }
+        const launched = await this.launchExistingTerminalMember({
+            rigId,
+            rigSpec,
+            rigRoot,
+            pod,
+            member,
+            qualifiedId,
+            nodeId,
+        });
+        if (launched.sessionName) {
+            launchedSessionNames.push(launched.sessionName);
+        }
+        if (launched.warnings?.length) {
+            warnings.push(...launched.warnings);
+        }
+        return {
+            logicalId: qualifiedId,
+            status: launched.status,
+            error: launched.error,
+        };
+    }
+    findMemberContext(rigSpec, qualifiedId) {
+        const [podId, memberId] = qualifiedId.split(".", 2);
+        if (!podId || !memberId)
+            return null;
+        const pod = rigSpec.pods.find((entry) => entry.id === podId);
+        const member = pod?.members.find((entry) => entry.id === memberId);
+        return pod && member ? { pod, member } : null;
+    }
+    async launchExistingAgentMember(input) {
+        const resolveResult = input.resolveResult ?? resolveAgentRef(input.member.agentRef, input.rigRoot, this.deps.fsOps);
+        if (!resolveResult.ok) {
+            const msg = resolveResult.code === "validation_failed"
+                ? resolveResult.errors.join("; ")
+                : resolveResult.error;
+            return { status: "failed", error: msg };
+        }
+        const configResult = input.configResult ?? resolveNodeConfig({
+            baseSpec: resolveResult.resolved,
+            importedSpecs: resolveResult.imports,
+            collisions: resolveResult.collisions,
+            profileName: input.member.profile,
+            member: input.member,
+            pod: input.pod,
+            rig: input.rigSpec,
+        });
+        if (!configResult.ok) {
+            return { status: "failed", error: configResult.errors.join("; ") };
+        }
+        this.updateNodeResolvedConfig(input.nodeId, configResult.config);
+        const sessionNameErrors = validateSessionComponents(input.pod.id, input.member.id, input.rigSpec.name);
+        if (sessionNameErrors.length > 0) {
+            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 });
+        if (!launchResult.ok) {
+            return { status: "failed", error: launchResult.message };
+        }
+        try {
+            this.db.prepare("UPDATE sessions SET restore_policy = ? WHERE id = ?")
+                .run(configResult.config.restorePolicy, launchResult.session.id);
+        }
+        catch { /* best-effort */ }
+        const adapter = this.deps.adapters[input.member.runtime];
+        if (!adapter) {
+            return { status: "failed", error: `No adapter for runtime "${input.member.runtime}"`, sessionName: canonicalSessionName, warnings: launchResult.warnings };
+        }
+        const planResult = planProjection({
+            config: configResult.config,
+            collisions: resolveResult.collisions,
+            fsOps: this.deps.fsOps,
+        });
+        if (!planResult.ok) {
+            return { status: "failed", error: planResult.errors.join("; "), sessionName: canonicalSessionName, warnings: launchResult.warnings };
+        }
+        const resolvedFiles = this.buildResolvedStartupFiles(resolveResult.resolved.spec, resolveResult.resolved.sourcePath, resolveResult.resolved.spec.profiles[input.member.profile], input.rigSpec, input.rigRoot, input.pod, input.member);
+        const binding = {
+            id: launchResult.binding.id,
+            nodeId: input.nodeId,
+            tmuxSession: launchResult.binding.tmuxSession,
+            tmuxWindow: null,
+            tmuxPane: null,
+            cmuxWorkspace: null,
+            cmuxSurface: null,
+            updatedAt: "",
+            cwd: input.member.cwd ? (nodePath.isAbsolute(input.member.cwd) ? input.member.cwd : nodePath.resolve(input.rigRoot, input.member.cwd)) : input.rigRoot,
+        };
+        const startupResult = await this.deps.startupOrchestrator.startNode({
+            rigId: input.rigId,
+            nodeId: input.nodeId,
+            sessionId: launchResult.session.id,
+            binding,
+            adapter,
+            plan: planResult.plan,
+            resolvedStartupFiles: resolvedFiles,
+            startupActions: [
+                ...configResult.config.startup.actions,
+                this.buildSessionIdentityAction({
+                    rigName: input.rigSpec.name,
+                    pod: input.pod,
+                    member: input.member,
+                    runtime: input.member.runtime,
+                    sessionName: canonicalSessionName,
+                    resolvedSpecName: configResult.config.resolvedSpecName,
+                }),
+            ],
+            isRestore: false,
+        });
+        return {
+            status: startupResult.ok ? "launched" : "failed",
+            error: startupResult.ok ? undefined : startupResult.errors.join("; "),
+            sessionName: canonicalSessionName,
+            warnings: launchResult.warnings,
+        };
+    }
+    async launchExistingTerminalMember(input) {
+        const sessionNameErrors = validateSessionComponents(input.pod.id, input.member.id, input.rigSpec.name);
+        if (sessionNameErrors.length > 0) {
+            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 });
+        if (!launchResult.ok) {
+            return { status: "failed", error: launchResult.message };
+        }
+        try {
+            this.db.prepare("UPDATE nodes SET restore_policy = ? WHERE id = ?")
+                .run("checkpoint_only", input.nodeId);
+        }
+        catch { /* best-effort */ }
+        try {
+            this.db.prepare("UPDATE sessions SET restore_policy = ? WHERE id = ?")
+                .run("checkpoint_only", launchResult.session.id);
+        }
+        catch { /* best-effort */ }
+        const startup = resolveStartup({
+            specStartup: { files: [], actions: [] },
+            profileStartup: undefined,
+            rigCultureFile: input.rigSpec.cultureFile,
+            rigStartup: input.rigSpec.startup,
+            podStartup: input.pod.startup,
+            memberStartup: input.member.startup,
+            operatorStartup: undefined,
+        });
+        const resolvedFiles = this.buildTerminalResolvedStartupFiles(input.rigSpec, input.rigRoot, input.pod, input.member);
+        const binding = {
+            id: launchResult.binding.id,
+            nodeId: input.nodeId,
+            tmuxSession: launchResult.binding.tmuxSession,
+            tmuxWindow: null,
+            tmuxPane: null,
+            cmuxWorkspace: null,
+            cmuxSurface: null,
+            updatedAt: "",
+            cwd: input.member.cwd ? (nodePath.isAbsolute(input.member.cwd) ? input.member.cwd : nodePath.resolve(input.rigRoot, input.member.cwd)) : input.rigRoot,
+        };
+        const adapter = this.deps.adapters["terminal"];
+        if (!adapter) {
+            return { status: "failed", error: 'No adapter for runtime "terminal"', sessionName: canonicalSessionName, warnings: launchResult.warnings };
+        }
+        const emptyPlan = {
+            entries: [],
+            diagnostics: [],
+            conflicts: [],
+            noOps: [],
+            runtime: "terminal",
+            cwd: input.member.cwd ? (nodePath.isAbsolute(input.member.cwd) ? input.member.cwd : nodePath.resolve(input.rigRoot, input.member.cwd)) : input.rigRoot,
+        };
+        const startupResult = await this.deps.startupOrchestrator.startNode({
+            rigId: input.rigId,
+            nodeId: input.nodeId,
+            sessionId: launchResult.session.id,
+            binding,
+            adapter,
+            plan: emptyPlan,
+            resolvedStartupFiles: resolvedFiles,
+            startupActions: startup.actions,
+            isRestore: false,
+        });
+        return {
+            status: startupResult.ok ? "launched" : "failed",
+            error: startupResult.ok ? undefined : startupResult.errors.join("; "),
+            sessionName: canonicalSessionName,
+            warnings: launchResult.warnings,
+        };
+    }
+    updateNodeResolvedConfig(nodeId, config) {
+        try {
+            this.db.prepare(`UPDATE nodes
+         SET restore_policy = ?,
+             resolved_spec_name = ?,
+             resolved_spec_version = ?,
+             resolved_spec_hash = ?
+         WHERE id = ?`).run(config.restorePolicy, config.resolvedSpecName, config.resolvedSpecVersion, config.resolvedSpecHash, nodeId);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    buildTerminalResolvedStartupFiles(rigSpec, rigRoot, pod, member) {
+        const files = [];
+        // Skip layers 1-2 (agent base, profile) — terminal nodes have no agent spec
+        // Layer 3: Rig culture file
+        if (rigSpec.cultureFile) {
+            files.push({
+                path: rigSpec.cultureFile,
+                absolutePath: nodePath.resolve(rigRoot, rigSpec.cultureFile),
+                ownerRoot: rigRoot,
+                deliveryHint: "auto",
+                required: true,
+                appliesOn: ["fresh_start", "restore"],
+            });
+        }
+        // Layer 4: Rig startup
+        if (rigSpec.startup) {
+            for (const f of rigSpec.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        // Layer 5: Pod startup
+        if (pod.startup) {
+            for (const f of pod.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        // Layer 6: Member startup
+        if (member.startup) {
+            for (const f of member.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        return this.resolveAutoHints(files);
+    }
+    buildResolvedStartupFiles(agentSpec, agentSourcePath, profile, rigSpec, rigRoot, pod, member) {
+        const files = [];
+        // nodePath imported at top level (ESM)
+        // 1. Agent base startup
+        for (const f of agentSpec.startup.files) {
+            files.push({ ...f, absolutePath: nodePath.resolve(agentSourcePath, f.path), ownerRoot: agentSourcePath });
+        }
+        // 2. Profile startup
+        if (profile?.startup) {
+            for (const f of profile.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(agentSourcePath, f.path), ownerRoot: agentSourcePath });
+            }
+        }
+        // 3. Rig culture file
+        if (rigSpec.cultureFile) {
+            files.push({
+                path: rigSpec.cultureFile,
+                absolutePath: nodePath.resolve(rigRoot, rigSpec.cultureFile),
+                ownerRoot: rigRoot,
+                deliveryHint: "auto",
+                required: true,
+                appliesOn: ["fresh_start", "restore"],
+            });
+        }
+        // 4. Rig startup
+        if (rigSpec.startup) {
+            for (const f of rigSpec.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        // 5. Pod startup
+        if (pod.startup) {
+            for (const f of pod.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        // 6. Member startup
+        if (member.startup) {
+            for (const f of member.startup.files) {
+                files.push({ ...f, absolutePath: nodePath.resolve(rigRoot, f.path), ownerRoot: rigRoot });
+            }
+        }
+        // 7. Built-in OpenRig onboarding overlay (appended last, does not replace agent guidance)
+        const onboardingPath = nodePath.resolve(import.meta.dirname, "../../assets/guidance/using-openrig.md");
+        files.push({
+            path: "using-openrig.md",
+            absolutePath: onboardingPath,
+            ownerRoot: nodePath.resolve(import.meta.dirname, "../../assets"),
+            deliveryHint: "guidance_merge",
+            required: false,
+            appliesOn: ["fresh_start", "restore"],
+        });
+        return this.resolveAutoHints(files);
+    }
+    buildSessionIdentityAction(input) {
+        const lines = [
+            "OpenRig session identity:",
+            `- rig: ${input.rigName}`,
+            `- pod: ${input.pod.id}`,
+            `- pod_label: ${input.pod.label}`,
+            `- member: ${input.member.id}`,
+            input.member.label ? `- member_label: ${input.member.label}` : null,
+            `- logical_id: ${input.pod.id}.${input.member.id}`,
+            input.resolvedSpecName ? `- agent_spec: ${input.resolvedSpecName}` : null,
+            `- runtime: ${input.runtime}`,
+            `- session: ${input.sessionName}`,
+            "This is your startup identity hint. For durable identity recovery after compaction, run:",
+            "  rig whoami --json",
+            "That command returns your full topology context: rig, pod, peers, edges, and transcript path.",
+        ].filter((line) => Boolean(line));
+        return {
+            type: "send_text",
+            value: lines.join("\n"),
+            phase: "after_ready",
+            appliesOn: ["fresh_start", "restore"],
+            idempotent: true,
+        };
+    }
+    /**
+     * Resolve any remaining 'auto' delivery hints to concrete hints at plan time.
+     * Uses the shared resolveConcreteHint resolver (single source of truth).
+     * After this, no file should have deliveryHint === 'auto'.
+     */
+    resolveAutoHints(files) {
+        return files.map((f) => {
+            if (f.deliveryHint !== "auto")
+                return f;
+            try {
+                const content = this.deps.fsOps.readFile(f.absolutePath);
+                return { ...f, deliveryHint: resolveConcreteHint(f.path, content) };
+            }
+            catch {
+                // If file can't be read, default to send_text (safest — delivered after harness ready)
+                return { ...f, deliveryHint: "send_text" };
+            }
+        });
+    }
+}
+//# sourceMappingURL=rigspec-instantiator.js.map