@ouro.bot/cli 0.1.0-alpha.82 → 0.1.0-alpha.84

package/changelog.json

@@ -1,6 +1,21 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.84",
+      "changes": [
+        "Safe workspace routing now covers repo-local shell commands too, so agents that discover a harness friction through `shell` land in the dedicated worktree instead of wandering in the shared checkout.",
+        "The new `safe_workspace` tool and prompt guidance make the chosen workspace path, branch, and first concrete repo action explicit before the first edit, tightening the visible OODA loop."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.83",
+      "changes": [
+        "Visible OODA loop substrate: persistent return obligations now surface where work is happening, whether the agent is still investigating, and what still needs to come back to the originating session.",
+        "Coding-session provenance now carries the originating human-facing session and obligation through spawn, persistence, and feedback, so hidden coding work is legible in active work instead of disappearing behind a tool session.",
+        "Runtime closure is explicit after self-fix updates: `ouro up` now prints a changelog follow-up command, and the runtime prompt reminds the agent to report that it updated and review what changed before treating the loop as closed."
+      ]
+    },
     {
       "version": "0.1.0-alpha.82",
       "changes": [

package/dist/heart/active-work.js

@@ -5,6 +5,7 @@ exports.buildActiveWorkFrame = buildActiveWorkFrame;
 exports.formatActiveWorkFrame = formatActiveWorkFrame;
 const runtime_1 = require("../nerves/runtime");
 const state_machine_1 = require("./bridges/state-machine");
+const obligations_1 = require("./obligations");
 const target_resolution_1 = require("./target-resolution");
 function activityPriority(source) {
     return source === "friend-facing" ? 0 : 1;
@@ -31,6 +32,23 @@ function hasSharedObligationPressure(input) {
         && input.currentObligation.trim().length > 0) || input.mustResolveBeforeHandoff
         || summarizeLiveTasks(input.taskBoard).length > 0;
 }
+function activeObligationCount(obligations) {
+    return (obligations ?? []).filter((ob) => (0, obligations_1.isOpenObligationStatus)(ob.status)).length;
+}
+function formatObligationSurface(obligation) {
+    if (!obligation.currentSurface?.label)
+        return "";
+    switch (obligation.status) {
+        case "investigating":
+            return ` (working in ${obligation.currentSurface.label})`;
+        case "waiting_for_merge":
+            return ` (waiting at ${obligation.currentSurface.label})`;
+        case "updating_runtime":
+            return ` (updating via ${obligation.currentSurface.label})`;
+        default:
+            return ` (${obligation.currentSurface.label})`;
+    }
+}
 function suggestBridgeForActiveWork(input) {
     const targetCandidates = (input.targetCandidates ?? [])
         .filter((candidate) => {
@@ -87,9 +105,10 @@ function buildActiveWorkFrame(input) {
         : [];
     const liveTaskNames = summarizeLiveTasks(input.taskBoard);
     const activeBridgePresent = input.bridges.some(isActiveBridge);
+    const openObligations = activeObligationCount(input.pendingObligations);
     const centerOfGravity = activeBridgePresent
         ? "shared-work"
-        : (input.inner.status === "running" || input.inner.hasPending || input.mustResolveBeforeHandoff)
+        : (input.inner.status === "running" || input.inner.hasPending || input.mustResolveBeforeHandoff || openObligations > 0)
             ? "inward-work"
             : "local-turn";
     const frame = {
@@ -129,6 +148,7 @@ function buildActiveWorkFrame(input) {
             bridges: frame.bridges.length,
             liveTasks: frame.taskPressure.liveTaskNames.length,
             liveSessions: frame.friendActivity.otherLiveSessionsForCurrentFriend.length,
+            pendingObligations: openObligations,
             hasBridgeSuggestion: frame.bridgeSuggestion !== null,
         },
     });
@@ -204,6 +224,19 @@ function formatActiveWorkFrame(frame) {
         lines.push("");
         lines.push(targetCandidatesBlock);
     }
+    if ((frame.pendingObligations ?? []).length > 0) {
+        lines.push("");
+        lines.push("## return obligations");
+        for (const obligation of frame.pendingObligations) {
+            if (!(0, obligations_1.isOpenObligationStatus)(obligation.status))
+                continue;
+            let obligationLine = `- [${obligation.status}] ${obligation.origin.friendId}/${obligation.origin.channel}/${obligation.origin.key}: ${obligation.content}${formatObligationSurface(obligation)}`;
+            if (obligation.latestNote?.trim()) {
+                obligationLine += `\n  latest: ${obligation.latestNote.trim()}`;
+            }
+            lines.push(obligationLine);
+        }
+    }
     // Bridge suggestion
     if (frame.bridgeSuggestion) {
         lines.push("");

package/dist/heart/commitments.js

@@ -2,17 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveCommitments = deriveCommitments;
 exports.formatCommitments = formatCommitments;
+const obligations_1 = require("./obligations");
 const runtime_1 = require("../nerves/runtime");
+function describeActiveObligation(obligation) {
+    if (obligation.status === "pending") {
+        return `i owe ${obligation.origin.friendId}: ${obligation.content}`;
+    }
+    const surface = obligation.currentSurface?.label;
+    const statusText = obligation.status.replaceAll("_", " ");
+    if (surface) {
+        return `i owe ${obligation.origin.friendId}: ${obligation.content} (${statusText} in ${surface})`;
+    }
+    return `i owe ${obligation.origin.friendId}: ${obligation.content} (${statusText})`;
+}
 function deriveCommitments(activeWorkFrame, innerJob, pendingObligations) {
     const committedTo = [];
     const completionCriteria = [];
     const safeToIgnore = [];
     // Persistent obligations from the obligation store
     if (pendingObligations && pendingObligations.length > 0) {
+        let hasAdvancedObligation = false;
         for (const ob of pendingObligations) {
-            committedTo.push(`i owe ${ob.origin.friendId}: ${ob.content}`);
+            if (!(0, obligations_1.isOpenObligationStatus)(ob.status))
+                continue;
+            committedTo.push(describeActiveObligation(ob));
+            if (ob.status !== "pending")
+                hasAdvancedObligation = true;
         }
         completionCriteria.push("fulfill my outstanding obligations");
+        if (hasAdvancedObligation) {
+            completionCriteria.push("close my active obligation loops");
+        }
     }
     // Obligation (from current turn -- kept for backward compat)
     if (typeof activeWorkFrame.currentObligation === "string" && activeWorkFrame.currentObligation.trim().length > 0) {

package/dist/heart/daemon/daemon-cli.js

@@ -1828,6 +1828,11 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
                     await deps.installCliVersion(updateResult.latestVersion);
                     deps.activateCliVersion(updateResult.latestVersion);
                     deps.writeStdout(`ouro updated to ${updateResult.latestVersion} (was ${currentVersion})`);
+                    const changelogCommand = (0, ouro_version_manager_1.buildChangelogCommand)(currentVersion, updateResult.latestVersion);
+                    /* v8 ignore next -- buildChangelogCommand is non-null when an actual newer version is installed @preserve */
+                    if (changelogCommand) {
+                        deps.writeStdout(`review changes with: ${changelogCommand}`);
+                    }
                     pendingReExec = true;
                 }
                 /* v8 ignore start -- update check error: tested via daemon-cli-update-flow.test.ts @preserve */
@@ -1873,6 +1878,11 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
         /* v8 ignore start -- CLI update detection: tested via daemon-cli-version-detect.test.ts @preserve */
         if (previousCliVersion && previousCliVersion !== currentVersion) {
             deps.writeStdout(`ouro updated to ${currentVersion} (was ${previousCliVersion})`);
+            const changelogCommand = (0, ouro_version_manager_1.buildChangelogCommand)(previousCliVersion, currentVersion);
+            /* v8 ignore next -- buildChangelogCommand is non-null when previous/current runtime versions differ @preserve */
+            if (changelogCommand) {
+                deps.writeStdout(`review changes with: ${changelogCommand}`);
+            }
         }
         /* v8 ignore stop */
         if (updateSummary.updated.length > 0) {

package/dist/heart/daemon/ouro-version-manager.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOuroCliHome = getOuroCliHome;
 exports.getCurrentVersion = getCurrentVersion;
 exports.getPreviousVersion = getPreviousVersion;
+exports.buildChangelogCommand = buildChangelogCommand;
 exports.listInstalledVersions = listInstalledVersions;
 exports.installVersion = installVersion;
 exports.activateVersion = activateVersion;
@@ -73,6 +74,12 @@ function getPreviousVersion(deps) {
         return null;
     }
 }
+function buildChangelogCommand(previousVersion, currentVersion) {
+    if (!previousVersion || !currentVersion || previousVersion === currentVersion) {
+        return null;
+    }
+    return `ouro changelog --from ${previousVersion}`;
+}
 function listInstalledVersions(deps) {
     const cliHome = getOuroCliHome(deps.homeDir);
     /* v8 ignore next -- dep default: tests always inject @preserve */

package/dist/heart/obligations.js

@@ -33,9 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOpenObligationStatus = isOpenObligationStatus;
+exports.isOpenObligation = isOpenObligation;
 exports.createObligation = createObligation;
 exports.readObligations = readObligations;
 exports.readPendingObligations = readPendingObligations;
+exports.advanceObligation = advanceObligation;
 exports.fulfillObligation = fulfillObligation;
 exports.findPendingObligationForOrigin = findPendingObligationForOrigin;
 const fs = __importStar(require("fs"));
@@ -52,7 +55,14 @@ function generateId() {
     const random = Math.random().toString(36).slice(2, 10);
     return `${timestamp}-${random}`;
 }
+function isOpenObligationStatus(status) {
+    return status !== "fulfilled";
+}
+function isOpenObligation(obligation) {
+    return isOpenObligationStatus(obligation.status);
+}
 function createObligation(agentRoot, input) {
+    const now = new Date().toISOString();
     const id = generateId();
     const obligation = {
         id,
@@ -60,7 +70,8 @@ function createObligation(agentRoot, input) {
         ...(input.bridgeId ? { bridgeId: input.bridgeId } : {}),
         content: input.content,
         status: "pending",
-        createdAt: new Date().toISOString(),
+        createdAt: now,
+        updatedAt: now,
     };
     const dir = obligationsDir(agentRoot);
     fs.mkdirSync(dir, { recursive: true });
@@ -107,9 +118,9 @@ function readObligations(agentRoot) {
     return obligations;
 }
 function readPendingObligations(agentRoot) {
-    return readObligations(agentRoot).filter((ob) => ob.status === "pending");
+    return readObligations(agentRoot).filter(isOpenObligation);
 }
-function fulfillObligation(agentRoot, obligationId) {
+function advanceObligation(agentRoot, obligationId, update) {
     const filePath = obligationFilePath(agentRoot, obligationId);
     let obligation;
     try {
@@ -119,9 +130,48 @@ function fulfillObligation(agentRoot, obligationId) {
     catch {
         return;
     }
-    obligation.status = "fulfilled";
-    obligation.fulfilledAt = new Date().toISOString();
+    const previousStatus = obligation.status;
+    if (update.status) {
+        obligation.status = update.status;
+        if (update.status === "fulfilled") {
+            obligation.fulfilledAt = new Date().toISOString();
+        }
+    }
+    if (update.currentSurface) {
+        obligation.currentSurface = update.currentSurface;
+    }
+    if (typeof update.latestNote === "string") {
+        obligation.latestNote = update.latestNote;
+    }
+    obligation.updatedAt = new Date().toISOString();
     fs.writeFileSync(filePath, JSON.stringify(obligation, null, 2), "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.obligation_advanced",
+        message: "obligation advanced",
+        meta: {
+            obligationId,
+            previousStatus,
+            status: obligation.status,
+            friendId: obligation.origin.friendId,
+            channel: obligation.origin.channel,
+            key: obligation.origin.key,
+            surfaceKind: obligation.currentSurface?.kind ?? null,
+            surfaceLabel: obligation.currentSurface?.label ?? null,
+        },
+    });
+}
+function fulfillObligation(agentRoot, obligationId) {
+    advanceObligation(agentRoot, obligationId, { status: "fulfilled" });
+    const filePath = obligationFilePath(agentRoot, obligationId);
+    let obligation;
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        obligation = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
         event: "engine.obligation_fulfilled",

package/dist/heart/safe-workspace.js

@@ -37,6 +37,7 @@ exports.resetSafeWorkspaceSelection = resetSafeWorkspaceSelection;
 exports.getActiveSafeWorkspaceSelection = getActiveSafeWorkspaceSelection;
 exports.ensureSafeRepoWorkspace = ensureSafeRepoWorkspace;
 exports.resolveSafeRepoPath = resolveSafeRepoPath;
+exports.resolveSafeShellExecution = resolveSafeShellExecution;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -96,7 +97,7 @@ function createDedicatedWorktree(repoRoot, workspaceRoot, branchSuffix, existsSy
         rmSync(workspaceRoot, { recursive: true, force: true });
     }
     assertGitOk(runGit(repoRoot, ["worktree", "add", "-B", branchName, workspaceRoot, "origin/main"], spawnSync), "git worktree add");
-    return { workspaceRoot, created: true };
+    return { workspaceRoot, created: true, branchName };
 }
 function createScratchClone(workspaceRoot, cloneUrl, existsSync, mkdirSync, rmSync, spawnSync) {
     mkdirSync(path.dirname(workspaceRoot), { recursive: true });
@@ -107,7 +108,11 @@ function createScratchClone(workspaceRoot, cloneUrl, existsSync, mkdirSync, rmSy
         stdio: ["ignore", "pipe", "pipe"],
     });
     assertGitOk(result, "git clone");
-    return { workspaceRoot, created: true };
+    return { workspaceRoot, created: true, branchName: "main" };
+}
+const REPO_LOCAL_SHELL_COMMAND = /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(git|npm|npx|node|pnpm|yarn|bun|rg|sed|cat|ls|find|grep|vitest|tsc|eslint)\b/;
+function looksRepoLocalShellCommand(command) {
+    return REPO_LOCAL_SHELL_COMMAND.test(command.trim());
 }
 function registerCleanupHook(options) {
     if (cleanupHookRegistered)
@@ -160,6 +165,7 @@ function ensureSafeRepoWorkspace(options = {}) {
                 runtimeKind: "clone-main",
                 repoRoot,
                 workspaceRoot: created.workspaceRoot,
+                workspaceBranch: created.branchName,
                 sourceBranch: branch,
                 sourceCloneUrl: canonicalRepoUrl,
                 cleanupAfterMerge: false,
@@ -174,6 +180,7 @@ function ensureSafeRepoWorkspace(options = {}) {
                 runtimeKind: "clone-non-main",
                 repoRoot,
                 workspaceRoot: created.workspaceRoot,
+                workspaceBranch: created.branchName,
                 sourceBranch: branch,
                 sourceCloneUrl: canonicalRepoUrl,
                 cleanupAfterMerge: false,
@@ -189,6 +196,7 @@ function ensureSafeRepoWorkspace(options = {}) {
             runtimeKind: "installed-runtime",
             repoRoot,
             workspaceRoot: created.workspaceRoot,
+            workspaceBranch: created.branchName,
             sourceBranch: null,
             sourceCloneUrl: canonicalRepoUrl,
             cleanupAfterMerge: true,
@@ -205,6 +213,7 @@ function ensureSafeRepoWorkspace(options = {}) {
             runtimeKind: selection.runtimeKind,
             repoRoot: selection.repoRoot,
             workspaceRoot: selection.workspaceRoot,
+            workspaceBranch: selection.workspaceBranch,
             sourceBranch: selection.sourceBranch,
             sourceCloneUrl: selection.sourceCloneUrl,
             cleanupAfterMerge: selection.cleanupAfterMerge,
@@ -226,3 +235,27 @@ function resolveSafeRepoPath(options) {
     const resolvedPath = relativePath ? path.join(selection.workspaceRoot, relativePath) : selection.workspaceRoot;
     return { selection, resolvedPath };
 }
+function resolveSafeShellExecution(command, options = {}) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return { selection: activeSelection, command };
+    }
+    if (activeSelection && command.includes(activeSelection.workspaceRoot)) {
+        return { selection: activeSelection, command, cwd: activeSelection.workspaceRoot };
+    }
+    const repoRoot = path.resolve(options.repoRoot ?? (0, identity_1.getRepoRoot)());
+    const mentionsRepoRoot = command.includes(repoRoot);
+    const shouldRoute = mentionsRepoRoot || looksRepoLocalShellCommand(trimmed);
+    if (!shouldRoute) {
+        return { selection: activeSelection, command };
+    }
+    const selection = ensureSafeRepoWorkspace(options);
+    const rewrittenCommand = mentionsRepoRoot
+        ? command.split(repoRoot).join(selection.workspaceRoot)
+        : command;
+    return {
+        selection,
+        command: rewrittenCommand,
+        cwd: selection.workspaceRoot,
+    };
+}

package/dist/mind/obligation-steering.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findActivePersistentObligation = findActivePersistentObligation;
+exports.renderActiveObligationSteering = renderActiveObligationSteering;
+const runtime_1 = require("../nerves/runtime");
+function findActivePersistentObligation(frame) {
+    if (!frame)
+        return null;
+    return (frame.pendingObligations ?? []).find((ob) => ob.status !== "pending" && ob.status !== "fulfilled") ?? null;
+}
+function renderActiveObligationSteering(obligation) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.obligation_steering_rendered",
+        message: "rendered active obligation steering",
+        meta: {
+            hasObligation: Boolean(obligation),
+            hasSurface: Boolean(obligation?.currentSurface?.label),
+        },
+    });
+    if (!obligation)
+        return "";
+    const name = obligation.origin.friendId;
+    const surfaceLine = obligation.currentSurface?.label
+        ? `\nright now that work is happening in ${obligation.currentSurface.label}.`
+        : "";
+    return `## where my attention is
+i'm already working on something i owe ${name}.${surfaceLine}
+
+i should close that loop before i act like this is a fresh blank turn.`;
+}

package/dist/mind/prompt.js

@@ -52,6 +52,7 @@ exports.buildSystem = buildSystem;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const core_1 = require("../heart/core");
+const ouro_version_manager_1 = require("../heart/daemon/ouro-version-manager");
 const tools_1 = require("../repertoire/tools");
 const skills_1 = require("../repertoire/skills");
 const identity_1 = require("../heart/identity");
@@ -65,6 +66,7 @@ const tasks_1 = require("../repertoire/tasks");
 const session_activity_1 = require("../heart/session-activity");
 const active_work_1 = require("../heart/active-work");
 const commitments_1 = require("../heart/commitments");
+const obligation_steering_1 = require("./obligation-steering");
 // Lazy-loaded psyche text cache
 let _psycheCache = null;
 let _senseStatusLinesCache = null;
@@ -253,6 +255,11 @@ function runtimeInfoSection(channel) {
     const bundleMeta = readBundleMeta();
     if (bundleMeta?.previousRuntimeVersion && bundleMeta.previousRuntimeVersion !== currentVersion) {
         lines.push(`previously: ${bundleMeta.previousRuntimeVersion}`);
+        const changelogCommand = (0, ouro_version_manager_1.buildChangelogCommand)(bundleMeta.previousRuntimeVersion, currentVersion);
+        /* v8 ignore next -- buildChangelogCommand is non-null when previous/current runtime versions differ @preserve */
+        if (changelogCommand) {
+            lines.push(`if i'm closing a self-fix loop, i should tell them i updated and review changes with \`${changelogCommand}\`.`);
+        }
     }
     lines.push(`changelog available at: ${(0, bundle_manifest_1.getChangelogPath)()}`);
     lines.push(`cwd: ${process.cwd()}`);
@@ -460,7 +467,11 @@ function centerOfGravitySteeringSection(channel, options) {
     if (cog === "local-turn")
         return "";
     const job = frame.inner?.job;
+    const activeObligation = (0, obligation_steering_1.findActivePersistentObligation)(frame);
     if (cog === "inward-work") {
+        if (activeObligation) {
+            return (0, obligation_steering_1.renderActiveObligationSteering)(activeObligation);
+        }
         if (job?.status === "queued" || job?.status === "running") {
             const originClause = job.origin
                 ? ` ${job.origin.friendName ?? job.origin.friendId} asked about something and i wanted to give it real thought before responding.`
@@ -554,6 +565,16 @@ tool_choice is set to "required" -- i must call a tool on every turn.
 \`final_answer\` must be the ONLY tool call in that turn. do not combine it with other tool calls.
 do NOT call no-op tools just before \`final_answer\`. if i am done, i call \`final_answer\` directly.`;
 }
+function workspaceDisciplineSection() {
+    return `## repo workspace discipline
+when a shared-harness or local code fix needs repo work, i get the real workspace first with \`safe_workspace\`.
+\`read_file\`, \`write_file\`, and \`edit_file\` already map repo paths into that workspace. shell commands that target the harness run there too.
+
+before the first repo edit, i tell the user in 1-2 short lines:
+- the friction i'm fixing
+- the workspace path/branch i'm using
+- the first concrete action i'm taking`;
+}
 function contextSection(context, options) {
     if (!context)
         return "";
@@ -688,6 +709,7 @@ async function buildSystem(channel = "cli", options, context) {
         toolsSection(channel, options, context),
         mcpToolsSection(options?.mcpManager),
         reasoningEffortSection(options),
+        workspaceDisciplineSection(),
         toolRestrictionSection(context),
         trustContextSection(context),
         mixedTrustGroupSection(context),

package/dist/repertoire/coding/feedback.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatCodingTail = formatCodingTail;
 exports.attachCodingSessionFeedback = attachCodingSessionFeedback;
+const identity_1 = require("../../heart/identity");
+const obligations_1 = require("../../heart/obligations");
 const runtime_1 = require("../../nerves/runtime");
 const TERMINAL_UPDATE_KINDS = new Set(["completed", "failed", "killed"]);
 function clip(text, maxLength = 280) {
@@ -42,7 +44,10 @@ 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 isSafeProgressSnippet(snippet) {
     const wordCount = snippet.split(/\s+/).filter(Boolean).length;
@@ -81,6 +86,44 @@ function formatUpdateMessage(update) {
             return `${label} started`;
     }
 }
+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;
+    try {
+        (0, obligations_1.advanceObligation)((0, identity_1.getAgentRoot)(), obligationId, {
+            status: "investigating",
+            currentSurface: { kind: "coding", label: `${update.session.runner} ${update.session.id}` },
+            latestNote: obligationNoteFromUpdate(update) ?? undefined,
+        });
+    }
+    catch {
+        // Detached feedback should still reach the human even if obligation sync is unavailable.
+    }
+}
 function formatCodingTail(session) {
     const stdout = session.stdoutTail.trim() || "(empty)";
     const stderr = session.stderrTail.trim() || "(empty)";
@@ -119,8 +162,11 @@ function attachCodingSessionFeedback(manager, session, target) {
             });
         });
     };
-    sendMessage(formatUpdateMessage({ kind: "spawned", session }));
+    const spawnedUpdate = { kind: "spawned", session };
+    syncObligationFromUpdate(spawnedUpdate);
+    sendMessage(formatUpdateMessage(spawnedUpdate));
     unsubscribe = manager.subscribe(session.id, async (update) => {
+        syncObligationFromUpdate(update);
         sendMessage(formatUpdateMessage(update));
         if (TERMINAL_UPDATE_KINDS.has(update.kind)) {
             closed = true;

package/dist/repertoire/coding/manager.js

@@ -62,6 +62,7 @@ function isPidAlive(pid) {
 function cloneSession(session) {
     return {
         ...session,
+        originSession: session.originSession ? { ...session.originSession } : undefined,
         stdoutTail: session.stdoutTail,
         stderrTail: session.stderrTail,
         failure: session.failure
@@ -157,6 +158,8 @@ 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,
             status: "spawning",
@@ -482,12 +485,16 @@ 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 ?? "",

package/dist/repertoire/coding/tools.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codingToolDefinitions = void 0;
 const index_1 = require("./index");
+const identity_1 = require("../../heart/identity");
+const obligations_1 = require("../../heart/obligations");
 const runtime_1 = require("../../nerves/runtime");
 const RUNNERS = ["claude", "codex"];
 function requireArg(args, key) {
@@ -130,6 +132,17 @@ exports.codingToolDefinitions = [
                 prompt,
                 taskRef,
             };
+            if (ctx?.currentSession && ctx.currentSession.channel !== "inner") {
+                request.originSession = {
+                    friendId: ctx.currentSession.friendId,
+                    channel: ctx.currentSession.channel,
+                    key: ctx.currentSession.key,
+                };
+                const obligation = (0, obligations_1.findPendingObligationForOrigin)((0, identity_1.getAgentRoot)(), request.originSession);
+                if (obligation) {
+                    request.obligationId = obligation.id;
+                }
+            }
             const scopeFile = optionalArg(args, "scopeFile");
             if (scopeFile)
                 request.scopeFile = scopeFile;
@@ -138,6 +151,15 @@ exports.codingToolDefinitions = [
                 request.stateFile = stateFile;
             const manager = (0, index_1.getCodingSessionManager)();
             const session = await manager.spawnSession(request);
+            if (session.obligationId) {
+                (0, obligations_1.advanceObligation)((0, identity_1.getAgentRoot)(), session.obligationId, {
+                    status: "investigating",
+                    currentSurface: { kind: "coding", label: `${session.runner} ${session.id}` },
+                    latestNote: session.originSession
+                        ? `coding session started for ${session.originSession.channel}/${session.originSession.key}`
+                        : "coding session started",
+                });
+            }
             if (args.runner === "codex" && args.taskRef) {
                 (0, runtime_1.emitNervesEvent)({
                     component: "repertoire",

package/dist/repertoire/tools-base.js

@@ -404,6 +404,29 @@ exports.baseToolDefinitions = [
             return allResults.join("\n");
         },
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "safe_workspace",
+                description: "acquire or inspect the safe harness repo workspace for local edits. returns the real workspace path, branch, and why it was chosen.",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        },
+        handler: () => {
+            const selection = (0, safe_workspace_1.ensureSafeRepoWorkspace)();
+            return [
+                `workspace: ${selection.workspaceRoot}`,
+                `branch: ${selection.workspaceBranch}`,
+                `runtime: ${selection.runtimeKind}`,
+                `cleanup_after_merge: ${selection.cleanupAfterMerge ? "yes" : "no"}`,
+                `note: ${selection.note}`,
+            ].join("\n");
+        },
+    },
     {
         tool: {
             type: "function",
@@ -417,7 +440,14 @@ exports.baseToolDefinitions = [
                 },
             },
         },
-        handler: (a) => (0, child_process_1.execSync)(a.command, { encoding: "utf-8", timeout: 30000 }),
+        handler: (a) => {
+            const prepared = (0, safe_workspace_1.resolveSafeShellExecution)(a.command);
+            return (0, child_process_1.execSync)(prepared.command, {
+                encoding: "utf-8",
+                timeout: 30000,
+                ...(prepared.cwd ? { cwd: prepared.cwd } : {}),
+            });
+        },
     },
     {
         tool: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.82",
+  "version": "0.1.0-alpha.84",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",