@ouro.bot/cli 0.1.0-alpha.56 → 0.1.0-alpha.560

package/dist/repertoire/coding/feedback.js

@@ -2,8 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatCodingTail = formatCodingTail;
 exports.attachCodingSessionFeedback = attachCodingSessionFeedback;
+const identity_1 = require("../../heart/identity");
+const socket_client_1 = require("../../heart/daemon/socket-client");
+const obligations_1 = require("../../arc/obligations");
 const runtime_1 = require("../../nerves/runtime");
 const TERMINAL_UPDATE_KINDS = new Set(["completed", "failed", "killed"]);
+const OBLIGATION_WAKE_UPDATE_KINDS = new Set([
+    "waiting_input",
+    "stalled",
+    "completed",
+    "failed",
+    "killed",
+]);
+const PULL_REQUEST_NUMBER_PATTERN = /\bPR\s*#(\d+)\b/i;
+const PULL_REQUEST_URL_PATTERN = /\/pull\/(\d+)(?:\b|\/)?/i;
 function clip(text, maxLength = 280) {
     const trimmed = text.trim();
     if (trimmed.length <= maxLength)
@@ -42,25 +54,114 @@ function lastMeaningfulLine(text) {
     return clip(lines.at(-1));
 }
 function formatSessionLabel(session) {
-    return `${session.runner} ${session.id}`;
+    const origin = session.originSession
+        ? ` for ${session.originSession.channel}/${session.originSession.key}`
+        : "";
+    return `${session.runner} ${session.id}${origin}`;
+}
+function extractPullRequestLabel(snippet) {
+    if (!snippet)
+        return null;
+    const numberMatch = snippet.match(PULL_REQUEST_NUMBER_PATTERN);
+    if (numberMatch)
+        return `PR #${numberMatch[1]}`;
+    const urlMatch = snippet.match(PULL_REQUEST_URL_PATTERN);
+    if (urlMatch)
+        return `PR #${urlMatch[1]}`;
+    return null;
+}
+function isMergedPullRequestSnippet(snippet) {
+    return /\bmerged\b/i.test(snippet) || /\blanded\b/i.test(snippet);
+}
+function deriveObligationMilestone(update) {
+    const snippet = pickUpdateSnippet(update);
+    const pullRequest = extractPullRequestLabel(snippet);
+    if (update.kind === "completed" && snippet && pullRequest && isMergedPullRequestSnippet(snippet)) {
+        return {
+            status: "updating_runtime",
+            currentSurface: { kind: "runtime", label: "ouro up" },
+            currentArtifact: pullRequest,
+            nextAction: "update runtime, verify version/changelog, then re-observe",
+        };
+    }
+    if (update.kind === "completed" && pullRequest) {
+        return {
+            status: "waiting_for_merge",
+            currentSurface: { kind: "merge", label: pullRequest },
+            currentArtifact: pullRequest,
+            nextAction: `wait for checks, merge ${pullRequest}, then update runtime`,
+        };
+    }
+    if (update.kind === "waiting_input") {
+        return {
+            status: "investigating",
+            currentSurface: { kind: "coding", label: `${update.session.runner} ${update.session.id}` },
+            nextAction: `answer ${update.session.runner} ${update.session.id} and continue`,
+        };
+    }
+    if (update.kind === "stalled") {
+        return {
+            status: "investigating",
+            currentSurface: { kind: "coding", label: `${update.session.runner} ${update.session.id}` },
+            nextAction: `unstick ${update.session.runner} ${update.session.id} and continue`,
+        };
+    }
+    if (update.kind === "progress" || update.kind === "spawned" || update.kind === "failed" || update.kind === "killed" || update.kind === "completed") {
+        return {
+            status: "investigating",
+            currentSurface: { kind: "coding", label: `${update.session.runner} ${update.session.id}` },
+        };
+    }
+    return null;
 }
 function isSafeProgressSnippet(snippet) {
+    const normalized = snippet.trim();
     const wordCount = snippet.split(/\s+/).filter(Boolean).length;
-    return (snippet.length <= 80
+    return (normalized.length <= 80
+        && wordCount >= 2
         && wordCount <= 8
-        && !snippet.includes(":")
-        && !snippet.startsWith("**")
-        && !/^Respond with\b/i.test(snippet)
-        && !/^Coding session metadata\b/i.test(snippet)
-        && !/^sessionId\b/i.test(snippet)
-        && !/^taskRef\b/i.test(snippet)
-        && !/^parentAgent\b/i.test(snippet));
+        && /[A-Za-z]{3,}/.test(normalized)
+        && !normalized.includes(":")
+        && !/[{}\[\]();]/.test(normalized)
+        && !normalized.startsWith("**")
+        && !/^Respond with\b/i.test(normalized)
+        && !/^Coding session metadata\b/i.test(normalized)
+        && !/^sessionId\b/i.test(normalized)
+        && !/^taskRef\b/i.test(normalized)
+        && !/^parentAgent\b/i.test(normalized));
 }
 function pickUpdateSnippet(update) {
-    return (lastMeaningfulLine(update.text)
+    const checkpoint = update.session.checkpoint?.trim() || null;
+    return (checkpoint
+        ?? lastMeaningfulLine(update.text)
         ?? lastMeaningfulLine(update.session.stderrTail)
         ?? lastMeaningfulLine(update.session.stdoutTail));
 }
+function renderValue(text) {
+    const trimmed = text?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "(empty)";
+}
+function renderPath(text) {
+    return text && text.trim().length > 0 ? text : "(none)";
+}
+function formatCodingTail(session) {
+    const stdout = renderValue(session.stdoutTail);
+    const stderr = renderValue(session.stderrTail);
+    return [
+        `sessionId: ${session.id}`,
+        `runner: ${session.runner}`,
+        `status: ${session.status}`,
+        `checkpoint: ${renderValue(session.checkpoint ?? undefined)}`,
+        `artifactPath: ${renderPath(session.artifactPath)}`,
+        `workdir: ${session.workdir}`,
+        "",
+        "[stdout]",
+        stdout,
+        "",
+        "[stderr]",
+        stderr,
+    ].join("\n");
+}
 function formatUpdateMessage(update) {
     const label = formatSessionLabel(update.session);
     const snippet = pickUpdateSnippet(update);
@@ -81,26 +182,88 @@ function formatUpdateMessage(update) {
             return `${label} started`;
     }
 }
-function formatCodingTail(session) {
-    const stdout = session.stdoutTail.trim() || "(empty)";
-    const stderr = session.stderrTail.trim() || "(empty)";
-    return [
-        `sessionId: ${session.id}`,
-        `runner: ${session.runner}`,
-        `status: ${session.status}`,
-        `workdir: ${session.workdir}`,
-        "",
-        "[stdout]",
-        stdout,
-        "",
-        "[stderr]",
-        stderr,
-    ].join("\n");
+function formatReportBackMessage(update, baseMessage) {
+    if (!baseMessage)
+        return null;
+    if (!update.session.obligationId || !update.session.originSession) {
+        return baseMessage;
+    }
+    const milestone = deriveObligationMilestone(update);
+    const extraLines = [];
+    if (milestone?.currentArtifact) {
+        extraLines.push(`current artifact: ${milestone.currentArtifact}`);
+    }
+    if (milestone?.nextAction) {
+        extraLines.push(`next: ${milestone.nextAction}`);
+    }
+    return extraLines.length > 0 ? `${baseMessage}\n${extraLines.join("\n")}` : baseMessage;
+}
+function obligationNoteFromUpdate(update) {
+    const snippet = pickUpdateSnippet(update);
+    switch (update.kind) {
+        case "spawned":
+            return update.session.originSession
+                ? `coding session started for ${update.session.originSession.channel}/${update.session.originSession.key}`
+                : "coding session started";
+        case "progress":
+            return snippet ? `coding session progress: ${snippet}` : null;
+        case "waiting_input":
+            return snippet ? `coding session waiting: ${snippet}` : "coding session waiting for input";
+        case "stalled":
+            return snippet ? `coding session stalled: ${snippet}` : "coding session stalled";
+        case "completed":
+            return snippet
+                ? `coding session completed: ${snippet}; merge/update still pending`
+                : "coding session completed; merge/update still pending";
+        case "failed":
+            return snippet ? `coding session failed: ${snippet}` : "coding session failed";
+        case "killed":
+            return "coding session killed";
+    }
+}
+function syncObligationFromUpdate(update) {
+    const obligationId = update.session.obligationId;
+    if (!obligationId)
+        return;
+    const milestone = deriveObligationMilestone(update);
+    try {
+        (0, obligations_1.advanceObligation)((0, identity_1.getAgentRoot)(), obligationId, {
+            status: milestone?.status ?? "investigating",
+            currentSurface: milestone?.currentSurface ?? { kind: "coding", label: `${update.session.runner} ${update.session.id}` },
+            currentArtifact: milestone?.currentArtifact,
+            nextAction: milestone?.nextAction,
+            latestNote: obligationNoteFromUpdate(update) ?? undefined,
+        });
+    }
+    catch {
+        // Detached feedback should still reach the human even if obligation sync is unavailable.
+    }
+}
+async function wakeInnerDialogForObligation(update) {
+    if (!update.session.obligationId || !OBLIGATION_WAKE_UPDATE_KINDS.has(update.kind)) {
+        return;
+    }
+    try {
+        await (0, socket_client_1.requestInnerWake)((0, identity_1.getAgentName)());
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "repertoire",
+            event: "repertoire.coding_feedback_wake_error",
+            message: "coding feedback wake request failed",
+            meta: {
+                sessionId: update.session.id,
+                kind: update.kind,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
 }
 function attachCodingSessionFeedback(manager, session, target) {
     let lastMessage = "";
     let closed = false;
-    let unsubscribe = () => { };
+    let unsubscribe = null;
     const sendMessage = (message) => {
         if (closed || !message || message === lastMessage) {
             return;
@@ -119,16 +282,20 @@ function attachCodingSessionFeedback(manager, session, target) {
             });
         });
     };
-    sendMessage(formatUpdateMessage({ kind: "spawned", session }));
+    const spawnedUpdate = { kind: "spawned", session };
+    syncObligationFromUpdate(spawnedUpdate);
+    sendMessage(formatReportBackMessage(spawnedUpdate, formatUpdateMessage(spawnedUpdate)));
     unsubscribe = manager.subscribe(session.id, async (update) => {
-        sendMessage(formatUpdateMessage(update));
+        syncObligationFromUpdate(update);
+        sendMessage(formatReportBackMessage(update, formatUpdateMessage(update)));
+        await wakeInnerDialogForObligation(update);
         if (TERMINAL_UPDATE_KINDS.has(update.kind)) {
             closed = true;
-            unsubscribe();
+            unsubscribe?.();
         }
     });
     return () => {
         closed = true;
-        unsubscribe();
+        unsubscribe?.();
     };
 }

package/dist/repertoire/coding/manager.js

@@ -39,17 +39,12 @@ const path = __importStar(require("path"));
 const identity_1 = require("../../heart/identity");
 const runtime_1 = require("../../nerves/runtime");
 const spawner_1 = require("./spawner");
-function safeAgentName() {
-    try {
-        return (0, identity_1.getAgentName)();
-    }
-    catch {
-        return "default";
-    }
-}
 function defaultStateFilePath(agentName) {
     return path.join((0, identity_1.getAgentRoot)(agentName), "state", "coding", "sessions.json");
 }
+function defaultArtifactDirPath(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "coding", "sessions");
+}
 function isPidAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -62,6 +57,9 @@ function isPidAlive(pid) {
 function cloneSession(session) {
     return {
         ...session,
+        originSession: session.originSession ? { ...session.originSession } : undefined,
+        checkpoint: session.checkpoint ?? null,
+        artifactPath: session.artifactPath,
         stdoutTail: session.stdoutTail,
         stderrTail: session.stderrTail,
         failure: session.failure
@@ -85,6 +83,46 @@ function appendTail(existing, nextChunk, maxLength = 2000) {
     const combined = `${existing}${nextChunk}`;
     return combined.length <= maxLength ? combined : combined.slice(combined.length - maxLength);
 }
+function compactText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function clipText(text, maxLength = 240) {
+    return text.length <= maxLength ? text : `${text.slice(0, maxLength - 3)}...`;
+}
+function latestMeaningfulLine(text) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => compactText(line))
+        .filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    return clipText(lines.at(-1));
+}
+function fallbackCheckpoint(status, code, signal) {
+    switch (status) {
+        case "waiting_input":
+            return "needs input";
+        case "stalled":
+            return "no recent output";
+        case "completed":
+            return "completed";
+        case "failed":
+            if (code !== null)
+                return `exit code ${code}`;
+            if (signal)
+                return `terminated by ${signal}`;
+            return "failed";
+        case "killed":
+            return "terminated by parent agent";
+        default:
+            return null;
+    }
+}
+function deriveCheckpoint(session) {
+    return (latestMeaningfulLine(session.stderrTail)
+        ?? latestMeaningfulLine(session.stdoutTail)
+        ?? fallbackCheckpoint(session.status, session.lastExitCode, session.lastSignal));
+}
 function isSpawnCodingResult(value) {
     return typeof value === "object" && value !== null && "process" in value;
 }
@@ -122,6 +160,7 @@ class CodingSessionManager {
     maxRestarts;
     defaultStallThresholdMs;
     stateFilePath;
+    artifactDirPath;
     existsSync;
     readFileSync;
     writeFileSync;
@@ -139,8 +178,19 @@ class CodingSessionManager {
         this.writeFileSync = options.writeFileSync ?? fs.writeFileSync;
         this.mkdirSync = options.mkdirSync ?? fs.mkdirSync;
         this.pidAlive = options.pidAlive ?? isPidAlive;
-        this.agentName = options.agentName ?? safeAgentName();
+        // No silent fallback to "default" — if there's no agentName and no
+        // explicit option, getAgentName() throws. The previous `safeAgentName`
+        // helper fell back to "default" and ended up writing coding session
+        // state to `~/AgentBundles/default.ouro/state/coding/sessions.json` on
+        // every vitest run because the coding manager singleton constructs with
+        // `{}`. That leaked real-fs state into the developer's home directory
+        // on every coverage run. Production callers always pass via argv (see
+        // getAgentName); test callers must either pass `agentName` explicitly
+        // or mock `../../heart/identity`.
+        this.agentName = options.agentName ?? (0, identity_1.getAgentName)();
         this.stateFilePath = options.stateFilePath ?? defaultStateFilePath(this.agentName);
+        this.artifactDirPath = options.artifactDirPath
+            ?? (options.stateFilePath ? path.dirname(options.stateFilePath) : defaultArtifactDirPath(this.agentName));
         this.loadPersistedState();
     }
     async spawnSession(request) {
@@ -157,8 +207,12 @@ class CodingSessionManager {
             runner: normalizedRequest.runner,
             workdir: normalizedRequest.workdir,
             taskRef: normalizedRequest.taskRef,
+            originSession: normalizedRequest.originSession ? { ...normalizedRequest.originSession } : undefined,
+            obligationId: normalizedRequest.obligationId,
             scopeFile: normalizedRequest.scopeFile,
             stateFile: normalizedRequest.stateFile,
+            checkpoint: null,
+            artifactPath: this.artifactPathFor(id),
             status: "spawning",
             stdoutTail: "",
             stderrTail: "",
@@ -245,6 +299,7 @@ class CodingSessionManager {
         record.process.kill("SIGTERM");
         record.process = null;
         record.session.status = "killed";
+        record.session.checkpoint = "terminated by parent agent";
         record.session.endedAt = this.nowIso();
         (0, runtime_1.emitNervesEvent)({
             component: "repertoire",
@@ -267,6 +322,7 @@ class CodingSessionManager {
                 continue;
             stalled += 1;
             record.session.status = "stalled";
+            record.session.checkpoint = deriveCheckpoint(record.session);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
                 component: "repertoire",
@@ -292,6 +348,7 @@ class CodingSessionManager {
             record.process = null;
             if (record.session.status === "running" || record.session.status === "spawning") {
                 record.session.status = "killed";
+                record.session.checkpoint = "terminated during manager shutdown";
                 record.session.endedAt = this.nowIso();
             }
         }
@@ -336,6 +393,13 @@ class CodingSessionManager {
             record.session.endedAt = this.nowIso();
             updateKind = "completed";
         }
+        const checkpoint = latestMeaningfulLine(text);
+        if (checkpoint) {
+            record.session.checkpoint = checkpoint;
+        }
+        else if (!record.session.checkpoint) {
+            record.session.checkpoint = deriveCheckpoint(record.session);
+        }
         (0, runtime_1.emitNervesEvent)({
             component: "repertoire",
             event: "repertoire.coding_session_output",
@@ -359,12 +423,14 @@ class CodingSessionManager {
         record.session.lastSignal = signal;
         if (record.session.status === "killed" || record.session.status === "completed") {
             record.session.endedAt = this.nowIso();
+            record.session.checkpoint = deriveCheckpoint(record.session);
             this.persistState();
             return;
         }
         if (code === 0) {
             record.session.status = "completed";
             record.session.endedAt = this.nowIso();
+            record.session.checkpoint = deriveCheckpoint(record.session);
             this.persistState();
             this.notifyListeners(record.session.id, { kind: "completed", session: cloneSession(record.session) });
             return;
@@ -376,6 +442,7 @@ class CodingSessionManager {
         record.session.status = "failed";
         record.session.endedAt = this.nowIso();
         record.session.failure = defaultFailureDiagnostics(code, signal, record.command, record.args, record.stdoutTail, record.stderrTail);
+        record.session.checkpoint = deriveCheckpoint(record.session);
         (0, runtime_1.emitNervesEvent)({
             level: "error",
             component: "repertoire",
@@ -401,6 +468,7 @@ class CodingSessionManager {
         record.session.lastActivityAt = this.nowIso();
         record.session.endedAt = null;
         record.session.failure = null;
+        record.session.checkpoint = `restarted after ${reason}`;
         this.attachProcessListeners(record);
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
@@ -482,15 +550,21 @@ class CodingSessionManager {
             }
             const normalizedRequest = {
                 ...request,
+                originSession: request.originSession ? { ...request.originSession } : undefined,
                 sessionId: request.sessionId ?? session.id,
+                obligationId: request.obligationId,
                 parentAgent: request.parentAgent ?? this.agentName,
             };
             const normalizedSession = {
                 ...session,
                 taskRef: session.taskRef ?? normalizedRequest.taskRef,
+                originSession: session.originSession ?? normalizedRequest.originSession,
+                obligationId: session.obligationId ?? normalizedRequest.obligationId,
                 failure: session.failure ?? null,
                 stdoutTail: session.stdoutTail ?? session.failure?.stdoutTail ?? "",
                 stderrTail: session.stderrTail ?? session.failure?.stderrTail ?? "",
+                checkpoint: typeof session.checkpoint === "string" ? session.checkpoint : null,
+                artifactPath: typeof session.artifactPath === "string" ? session.artifactPath : this.artifactPathFor(session.id),
             };
             if (typeof normalizedSession.pid === "number") {
                 const alive = this.pidAlive(normalizedSession.pid);
@@ -503,6 +577,7 @@ class CodingSessionManager {
                     normalizedSession.pid = null;
                 }
             }
+            normalizedSession.checkpoint = normalizedSession.checkpoint ?? deriveCheckpoint(normalizedSession);
             this.records.set(normalizedSession.id, {
                 request: normalizedRequest,
                 session: normalizedSession,
@@ -542,6 +617,80 @@ class CodingSessionManager {
                 meta: { path: this.stateFilePath, reason: error instanceof Error ? error.message : String(error) },
             });
         }
+        this.persistArtifacts();
+    }
+    artifactPathFor(sessionId) {
+        return path.join(this.artifactDirPath, `${sessionId}.md`);
+    }
+    renderArtifact(record) {
+        const { request, session } = record;
+        const stdout = session.stdoutTail.trim() || "(empty)";
+        const stderr = session.stderrTail.trim() || "(empty)";
+        const lines = [
+            "# Coding Session Artifact",
+            "",
+            "## Session",
+            `id: ${session.id}`,
+            `runner: ${session.runner}`,
+            `status: ${session.status}`,
+            `taskRef: ${session.taskRef ?? "unassigned"}`,
+            `workdir: ${session.workdir}`,
+            `startedAt: ${session.startedAt}`,
+            `lastActivityAt: ${session.lastActivityAt}`,
+            `endedAt: ${session.endedAt ?? "active"}`,
+            `pid: ${session.pid ?? "none"}`,
+            `restarts: ${session.restartCount}`,
+            `checkpoint: ${session.checkpoint ?? "none"}`,
+            `scopeFile: ${session.scopeFile ?? "none"}`,
+            `stateFile: ${session.stateFile ?? "none"}`,
+            "",
+            "## Request",
+            request.prompt,
+            "",
+            "## Stdout Tail",
+            stdout,
+            "",
+            "## Stderr Tail",
+            stderr,
+        ];
+        if (session.failure) {
+            lines.push("", "## Failure", `command: ${session.failure.command}`, `args: ${session.failure.args.join(" ") || "(none)"}`, `code: ${session.failure.code ?? "null"}`, `signal: ${session.failure.signal ?? "null"}`);
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    persistArtifacts() {
+        try {
+            this.mkdirSync(this.artifactDirPath, { recursive: true });
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "repertoire",
+                event: "repertoire.coding_artifact_persist_error",
+                message: "failed preparing coding artifact directory",
+                meta: { path: this.artifactDirPath, reason: error instanceof Error ? error.message : String(error) },
+            });
+            return;
+        }
+        for (const record of this.records.values()) {
+            try {
+                record.session.artifactPath = record.session.artifactPath ?? this.artifactPathFor(record.session.id);
+                this.writeFileSync(record.session.artifactPath, this.renderArtifact(record), "utf-8");
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.coding_artifact_persist_error",
+                    message: "failed writing coding session artifact",
+                    meta: {
+                        id: record.session.id,
+                        path: record.session.artifactPath ?? this.artifactPathFor(record.session.id),
+                        reason: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+        }
     }
 }
 exports.CodingSessionManager = CodingSessionManager;

package/dist/repertoire/coding/spawner.js

@@ -36,8 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.spawnCodingProcess = spawnCodingProcess;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
-function buildCommandArgs(runner, workdir) {
+function buildCommandArgs(runner, workdir, parentAgent) {
     if (runner === "claude") {
         return {
             command: "claude",
@@ -53,25 +55,65 @@ function buildCommandArgs(runner, workdir) {
             ],
         };
     }
+    const agent = parentAgent ?? "unknown";
+    // Use absolute path to ouro-entry.js so MCP works in both dev and installed mode
+    // __dirname at runtime is dist/repertoire/coding/ — go up 2 levels to dist/
+    const distRoot = path.resolve(__dirname, "..", "..");
+    const ouroEntryPath = path.join(distRoot, "heart", "daemon", "ouro-entry.js");
     return {
         command: "codex",
-        args: ["exec", "--skip-git-repo-check", "--cd", workdir],
+        args: [
+            "exec",
+            "--skip-git-repo-check",
+            "--cd",
+            workdir,
+            "--ephemeral",
+            "--json",
+            "-c",
+            `mcp_servers.ouro.command=node`,
+            "-c",
+            `mcp_servers.ouro.args=["${ouroEntryPath}","mcp-serve","--agent","${agent}"]`,
+        ],
     };
 }
+function buildSpawnEnv(baseEnv, homeDir) {
+    const binDir = path.join(homeDir, ".ouro-cli", "bin");
+    const existingPath = baseEnv.PATH ?? "";
+    const pathEntries = existingPath.split(path.delimiter).filter((entry) => entry.length > 0);
+    if (!pathEntries.includes(binDir)) {
+        pathEntries.unshift(binDir);
+    }
+    return {
+        ...baseEnv,
+        PATH: pathEntries.join(path.delimiter),
+    };
+}
+function appendFileSection(sections, label, filePath, deps) {
+    if (!filePath || !deps.existsSync(filePath))
+        return;
+    const content = deps.readFileSync(filePath, "utf-8").trim();
+    if (content.length === 0)
+        return;
+    sections.push(`${label} (${filePath}):\n${content}`);
+}
 function buildPrompt(request, deps) {
     const sections = [];
+    sections.push([
+        "Execution contract:",
+        "- You are a subordinate coding session launched by a parent Ouro agent.",
+        "- Execute the concrete request in the supplied workdir directly.",
+        "- Do not switch into planning/doing workflows, approval gates, or repo-management rituals unless the request explicitly asks for them.",
+        "- Treat the request, scope file, and state file as the authoritative briefing for this session.",
+        "- Prefer direct execution and verification over narration.",
+    ].join("\n"));
     sections.push([
         "Coding session metadata:",
         `sessionId: ${request.sessionId ?? "pending"}`,
         `parentAgent: ${request.parentAgent ?? "unknown"}`,
         `taskRef: ${request.taskRef ?? "unassigned"}`,
     ].join("\n"));
-    if (request.stateFile && deps.existsSync(request.stateFile)) {
-        const stateContent = deps.readFileSync(request.stateFile, "utf-8").trim();
-        if (stateContent.length > 0) {
-            sections.push(`State file (${request.stateFile}):\n${stateContent}`);
-        }
-    }
+    appendFileSection(sections, "Scope file", request.scopeFile, deps);
+    appendFileSection(sections, "State file", request.stateFile, deps);
     sections.push(request.prompt);
     return sections.join("\n\n---\n\n");
 }
@@ -79,8 +121,11 @@ function spawnCodingProcess(request, deps = {}) {
     const spawnFn = deps.spawnFn ?? ((command, args, options) => (0, child_process_1.spawn)(command, args, options));
     const existsSync = deps.existsSync ?? fs.existsSync;
     const readFileSync = deps.readFileSync ?? fs.readFileSync;
+    const homeDir = deps.homeDir ?? os.homedir();
+    const baseEnv = deps.baseEnv ?? process.env;
     const prompt = buildPrompt(request, { existsSync, readFileSync });
-    const { command, args } = buildCommandArgs(request.runner, request.workdir);
+    const { command, args } = buildCommandArgs(request.runner, request.workdir, request.parentAgent);
+    const env = buildSpawnEnv(baseEnv, homeDir);
     (0, runtime_1.emitNervesEvent)({
         component: "repertoire",
         event: "repertoire.coding_spawn_start",
@@ -89,6 +134,7 @@ function spawnCodingProcess(request, deps = {}) {
     });
     const proc = spawnFn(command, args, {
         cwd: request.workdir,
+        env,
         stdio: ["pipe", "pipe", "pipe"],
     });
     proc.stdin.end(`${prompt}\n`);