@ouro.bot/cli 0.1.0-alpha.595 → 0.1.0-alpha.597

package/dist/repertoire/tools-awaiting.js

@@ -0,0 +1,360 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.awaitingToolDefinitions = void 0;
+exports.setAwaitToolDeps = setAwaitToolDeps;
+exports.resetAwaitToolDeps = resetAwaitToolDeps;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const await_parser_1 = require("../heart/awaiting/await-parser");
+const await_alert_1 = require("../heart/awaiting/await-alert");
+const pending_1 = require("../mind/pending");
+/**
+ * Bundle-root-relative locations.
+ * - `awaiting/<name>.md` — active awaits (status: pending)
+ * - `awaiting/.done/<name>.md` — terminal awaits (resolved/expired/canceled)
+ */
+function awaitingDir(agentRoot) {
+    return path.join(agentRoot, "awaiting");
+}
+function awaitingDoneDir(agentRoot) {
+    return path.join(awaitingDir(agentRoot), ".done");
+}
+function awaitFilePath(agentRoot, name) {
+    return path.join(awaitingDir(agentRoot), `${name}.md`);
+}
+function awaitDoneFilePath(agentRoot, name) {
+    return path.join(awaitingDoneDir(agentRoot), `${name}.md`);
+}
+const VALID_NAME = /^[A-Za-z0-9_-]+$/;
+function validateName(name) {
+    if (!name)
+        return "name is required";
+    if (!VALID_NAME.test(name))
+        return "name must be alphanumeric, underscores, or hyphens";
+    return null;
+}
+function readAwaitDefinition(agentRoot, name) {
+    const filePath = awaitFilePath(agentRoot, name);
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return (0, await_parser_1.parseAwaitFile)(content, filePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Default delivery deps for the await alert path used from the tool.
+ * Mirrors the proactive-outreach pattern: queue to the inner-dialog pending
+ * dir when no live deliverer is registered.
+ */
+function defaultDeliveryDeps(agentName) {
+    const pendingDir = (0, pending_1.getInnerDialogPendingDir)(agentName);
+    return {
+        agentName,
+        queuePending: (message) => {
+            // Mirror the write-as-pending convention from tools-session.
+            fs.mkdirSync(pendingDir, { recursive: true });
+            const filename = `${message.timestamp}-${Math.random().toString(36).slice(2, 10)}.json`;
+            fs.writeFileSync(path.join(pendingDir, filename), JSON.stringify(message, null, 2), "utf-8");
+        },
+    };
+}
+let injected = {};
+function setAwaitToolDeps(deps) {
+    injected = deps;
+}
+function resetAwaitToolDeps() {
+    injected = {};
+}
+function resolveDeliveryDeps(agentName) {
+    if (injected.buildDeliveryDeps)
+        return injected.buildDeliveryDeps(agentName);
+    return defaultDeliveryDeps(agentName);
+}
+function fileAwait(args, agentRoot, agentName, sessionFriendId, sessionChannel) {
+    const nameError = validateName(args.name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    if (!args.condition || !args.condition.trim()) {
+        return JSON.stringify({ error: "condition is required" });
+    }
+    if (!args.cadence || !args.cadence.trim()) {
+        return JSON.stringify({ error: "cadence is required" });
+    }
+    const filePath = awaitFilePath(agentRoot, args.name);
+    if (fs.existsSync(filePath)) {
+        return JSON.stringify({ error: `await "${args.name}" already exists` });
+    }
+    const mode = args.mode === "quick" ? "quick" : "full";
+    const alert = args.alert ?? sessionChannel ?? null;
+    const frontmatter = {
+        condition: args.condition.trim(),
+        cadence: args.cadence.trim(),
+        alert,
+        mode,
+        max_age: args.max_age ?? null,
+        status: "pending",
+        created_at: new Date().toISOString(),
+        filed_from: sessionChannel ?? "unknown",
+        filed_for_friend_id: sessionFriendId ?? null,
+    };
+    const rendered = (0, await_parser_1.renderAwaitFile)(frontmatter, args.body ?? "");
+    fs.mkdirSync(awaitingDir(agentRoot), { recursive: true });
+    fs.writeFileSync(filePath, rendered, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_filed",
+        message: "filed new await",
+        meta: { agent: agentName, name: args.name, cadence: args.cadence, alert },
+    });
+    return JSON.stringify({ filed: args.name, path: filePath });
+}
+function archiveAwait(agentRoot, name, updates) {
+    const source = awaitFilePath(agentRoot, name);
+    /* v8 ignore start -- defensive: callers (resolve/cancel) already verify the file exists via readAwaitDefinition; this guards the file-disappears-between-calls race @preserve */
+    if (!fs.existsSync(source)) {
+        return { ok: false, error: `await "${name}" not found in awaiting/` };
+    }
+    /* v8 ignore stop */
+    const content = fs.readFileSync(source, "utf-8");
+    const current = (0, await_parser_1.parseAwaitFile)(content, source);
+    // merge frontmatter from the parsed file with updates
+    const merged = {
+        condition: current.condition,
+        cadence: current.cadence,
+        alert: current.alert,
+        mode: current.mode,
+        max_age: current.max_age,
+        status: current.status,
+        created_at: current.created_at,
+        filed_from: current.filed_from,
+        filed_for_friend_id: current.filed_for_friend_id,
+        ...updates,
+    };
+    const rendered = (0, await_parser_1.renderAwaitFile)(merged, current.body);
+    fs.mkdirSync(awaitingDoneDir(agentRoot), { recursive: true });
+    fs.writeFileSync(awaitDoneFilePath(agentRoot, name), rendered, "utf-8");
+    fs.unlinkSync(source);
+    // re-parse the archived file so callers see merged fields (e.g. resolution_observation)
+    const archivedContent = fs.readFileSync(awaitDoneFilePath(agentRoot, name), "utf-8");
+    const archived = (0, await_parser_1.parseAwaitFile)(archivedContent, awaitDoneFilePath(agentRoot, name));
+    return { ok: true, file: archived };
+}
+async function resolveAwaitTool(name, verdict, observation, agentRoot, agentName) {
+    const nameError = validateName(name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    const existing = readAwaitDefinition(agentRoot, name);
+    if (!existing) {
+        return JSON.stringify({ error: `await "${name}" not found in awaiting/` });
+    }
+    if (existing.status !== "pending") {
+        return JSON.stringify({ error: `await "${name}" is not pending (status: ${existing.status})` });
+    }
+    if (verdict !== "yes" && verdict !== "no") {
+        return JSON.stringify({ error: "verdict must be 'yes' or 'no'" });
+    }
+    if (!observation || !observation.trim()) {
+        return JSON.stringify({ error: "observation is required" });
+    }
+    if (verdict === "no") {
+        // Update runtime state via recordAwaitCheck-style write
+        const { recordAwaitCheck } = await Promise.resolve().then(() => __importStar(require("../heart/awaiting/await-runtime-state")));
+        recordAwaitCheck(agentRoot, name, observation.trim(), new Date().toISOString());
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.await_check_no",
+            message: "await checked, not yet ready",
+            meta: { agent: agentName, name },
+        });
+        return JSON.stringify({ verdict: "no", recorded: true });
+    }
+    // verdict === "yes" — archive and alert
+    const archive = archiveAwait(agentRoot, name, {
+        status: "resolved",
+        resolved_at: new Date().toISOString(),
+        resolution_observation: observation.trim(),
+    });
+    /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+    if (!archive.ok)
+        return JSON.stringify({ error: archive.error });
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_resolved",
+        message: "await resolved",
+        meta: { agent: agentName, name },
+    });
+    let alert = null;
+    try {
+        alert = await (0, await_alert_1.deliverAwaitAlert)({
+            awaitFile: archive.file,
+            reason: "resolved",
+            observation: observation.trim(),
+            agentRoot,
+            agentName,
+            deliveryDeps: resolveDeliveryDeps(agentName),
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "repertoire",
+            event: "repertoire.await_alert_error",
+            message: "await alert delivery threw",
+            meta: { agent: agentName, name, error: error instanceof Error ? error.message : String(error) },
+        });
+    }
+    return JSON.stringify({
+        verdict: "yes",
+        archived: awaitDoneFilePath(agentRoot, name),
+        alert: alert ? { attempted: alert.attempted, status: alert.delivery?.status ?? null, skipped: alert.skipped ?? null } : null,
+    });
+}
+function cancelAwaitTool(name, reason, agentRoot, agentName) {
+    const nameError = validateName(name);
+    if (nameError)
+        return JSON.stringify({ error: nameError });
+    const existing = readAwaitDefinition(agentRoot, name);
+    if (!existing) {
+        return JSON.stringify({ error: `await "${name}" not found in awaiting/` });
+    }
+    if (existing.status !== "pending") {
+        return JSON.stringify({ error: `await "${name}" is not pending (status: ${existing.status})` });
+    }
+    const updates = {
+        status: "canceled",
+        canceled_at: new Date().toISOString(),
+    };
+    if (reason && reason.trim()) {
+        updates.cancel_reason = reason.trim();
+    }
+    const archive = archiveAwait(agentRoot, name, updates);
+    /* v8 ignore next -- defensive: archiveAwait only fails on the file-disappears-mid-call race already covered by v8 ignore inside archiveAwait @preserve */
+    if (!archive.ok)
+        return JSON.stringify({ error: archive.error });
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.await_canceled",
+        message: "await canceled",
+        meta: { agent: agentName, name },
+    });
+    return JSON.stringify({ canceled: name, archived: awaitDoneFilePath(agentRoot, name) });
+}
+exports.awaitingToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "await_condition",
+                description: "File a one-shot waiting condition. The daemon polls on cadence; on each tick I evaluate the condition and call resolve_await. When the condition becomes true, an alert fires via my outward channel.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Filename stem (alphanumeric/underscore/hyphen). Must be unique." },
+                        condition: { type: "string", description: "Natural-language condition to watch for." },
+                        cadence: { type: "string", description: "Polling cadence (e.g. '5m', '1h')." },
+                        alert: { type: "string", description: "Channel to alert on (e.g. 'bluebubbles', 'teams'). Defaults to filing session's channel." },
+                        mode: { type: "string", description: "'full' or 'quick'. Defaults 'full'." },
+                        max_age: { type: "string", description: "Optional auto-expiry (e.g. '24h')." },
+                        body: { type: "string", description: "Optional notes: why I filed this, what 'ready' looks like." },
+                    },
+                    required: ["name", "condition", "cadence"],
+                },
+            },
+        },
+        handler: (a, ctx) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            return fileAwait({
+                name: a.name,
+                condition: a.condition,
+                cadence: a.cadence,
+                alert: a.alert,
+                mode: a.mode,
+                max_age: a.max_age,
+                body: a.body,
+            }, agentRoot, agentName, ctx?.currentSession?.friendId ?? null, ctx?.currentSession?.channel ?? null);
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "resolve_await",
+                description: "Resolve a pending await with a verdict. verdict='yes' archives and fires the alert. verdict='no' records the observation and continues polling.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Await name (filename stem)." },
+                        verdict: { type: "string", description: "'yes' if the condition is met, 'no' otherwise." },
+                        observation: { type: "string", description: "One-line summary of what I saw this tick." },
+                    },
+                    required: ["name", "verdict", "observation"],
+                },
+            },
+        },
+        handler: async (a) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            return resolveAwaitTool(a.name, a.verdict, a.observation, agentRoot, agentName);
+        },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "cancel_await",
+                description: "Cancel a pending await without alerting. Archives with status: canceled.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Await name (filename stem)." },
+                        reason: { type: "string", description: "Optional cancel reason." },
+                    },
+                    required: ["name"],
+                },
+            },
+        },
+        handler: (a) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            return cancelAwaitTool(a.name, a.reason, agentRoot, agentName);
+        },
+    },
+];

package/dist/repertoire/tools-base.js

@@ -18,6 +18,8 @@ const tools_flight_1 = require("./tools-flight");
 const tools_attachments_1 = require("./tools-attachments");
 const tools_mail_1 = require("./tools-mail");
 const tools_trip_1 = require("./tools-trip");
+const tools_awaiting_1 = require("./tools-awaiting");
+const tools_obligations_1 = require("./tools-obligations");
 // Re-export flow tools for consumers that import them from tools-base
 var tools_flow_1 = require("./tools-flow");
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_flow_1.ponderTool; } });
@@ -51,6 +53,8 @@ exports.baseToolDefinitions = [
     ...tools_attachments_1.attachmentToolDefinitions,
     ...tools_mail_1.mailToolDefinitions,
     ...tools_trip_1.tripToolDefinitions,
+    ...tools_awaiting_1.awaitingToolDefinitions,
+    ...tools_obligations_1.obligationToolDefinitions,
 ];
 // Convenience array of just the tool schemas (no handler/integration metadata).
 // Used by consumers that need the OpenAI function-tool format.

package/dist/repertoire/tools-obligations.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.obligationToolDefinitions = void 0;
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const json_store_1 = require("../arc/json-store");
+const obligations_1 = require("../arc/obligations");
+/**
+ * `let_go` lets the agent release a held work item from its attention loop.
+ *
+ * Two stores need release semantics:
+ *   1. ReturnObligations at `arc/obligations/inner/<id>.json` (status: queued|running|returned|deferred)
+ *      — these are what surface in the "held work items" section of the prompt.
+ *   2. Outer Obligations at `arc/obligations/<id>.json` (status: pending|...|fulfilled)
+ *      — these surface as "i owe <friend>: ..." in the commitments section.
+ *
+ * The pre-existing path to terminal state for both is the `surface` tool, which fulfills
+ * an obligation as a side-effect of delivering a response. When work is resolved EXTERNALLY
+ * (e.g. a PR merged fixed the underlying issue), there is no response to surface — the
+ * agent has no way to clear the item, so it cycles in the prompt every turn.
+ *
+ * `let_go` is the missing primitive: dismissal WITHOUT delivery.
+ */
+function outerObligationsDir(agentRoot) {
+    return path.join(agentRoot, "arc", "obligations");
+}
+function readOuterObligation(agentRoot, id) {
+    return (0, json_store_1.readJsonFile)(outerObligationsDir(agentRoot), id) ?? null;
+}
+function letGo(args, agentRoot, agentName) {
+    if (typeof args.id !== "string" || args.id.trim().length === 0) {
+        return JSON.stringify({ error: "id is required" });
+    }
+    const id = args.id.trim();
+    const reason = typeof args.reason === "string" && args.reason.trim().length > 0
+        ? args.reason.trim()
+        : null;
+    // 1. ReturnObligation (inner) first — these are what slugger sees in "held work items".
+    const ret = (0, obligations_1.readReturnObligation)(agentName, id);
+    if (ret) {
+        if (ret.status === "returned" || ret.status === "deferred") {
+            return JSON.stringify({ kind: "return_obligation", id, already: ret.status });
+        }
+        (0, obligations_1.advanceReturnObligation)(agentName, id, {
+            status: "returned",
+            returnedAt: Date.now(),
+            returnTarget: "surface",
+        });
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.obligation_let_go",
+            message: "agent let go of return obligation",
+            meta: { kind: "return_obligation", id, reason: reason ?? null },
+        });
+        return JSON.stringify({ kind: "return_obligation", let_go: id, reason });
+    }
+    // 2. Outer Obligation — these surface as "i owe ..." in commitments.
+    const outer = readOuterObligation(agentRoot, id);
+    if (outer) {
+        if (outer.status === "fulfilled") {
+            return JSON.stringify({ kind: "obligation", id, already: "fulfilled" });
+        }
+        (0, obligations_1.fulfillObligation)(agentRoot, id);
+        if (reason !== null) {
+            // Persist the dismissal reason as the obligation's latestNote so future-me
+            // can read why this was released (the nerves event also captures it).
+            (0, obligations_1.advanceObligation)(agentRoot, id, { latestNote: reason });
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.obligation_let_go",
+            message: "agent let go of outer obligation",
+            meta: { kind: "obligation", id, reason: reason ?? null },
+        });
+        return JSON.stringify({ kind: "obligation", let_go: id, reason });
+    }
+    return JSON.stringify({ error: `no obligation found with id "${id}"` });
+}
+exports.obligationToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "let_go",
+                description: "release a held work item from my attention. for items that have been resolved externally, no longer apply, or are stale and just cycling in my prompt with nothing to act on. takes the id i see in the 'held work items' section (or any obligation id from arc/obligations/). optional reason is recorded for future me. idempotent — calling on an already-released item returns the existing status, not an error.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "the obligation id — the bracketed id in 'held work items' (e.g. '1775976317954-s5pno43r'), or any obligation file's id from arc/obligations/.",
+                        },
+                        reason: {
+                            type: "string",
+                            description: "optional one-line reason i'm letting go (e.g. 'resolved externally by PR #701').",
+                        },
+                    },
+                    required: ["id"],
+                },
+            },
+        },
+        handler: (args) => {
+            const agentRoot = (0, identity_1.getAgentRoot)();
+            const agentName = (0, identity_1.getAgentName)();
+            return letGo({ id: args.id, reason: args.reason }, agentRoot, agentName);
+        },
+    },
+];

package/dist/senses/await-turn-message.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAwaitTurnMessage = buildAwaitTurnMessage;
+const runtime_1 = require("../nerves/runtime");
+function formatElapsed(ms) {
+    if (ms < 60_000)
+        return "<1m ago";
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+function relativeAge(lastCheckedAt, now) {
+    if (!lastCheckedAt)
+        return null;
+    const lastMs = new Date(lastCheckedAt).getTime();
+    if (!Number.isFinite(lastMs))
+        return null;
+    return formatElapsed(now().getTime() - lastMs);
+}
+function buildAwaitTurnMessage(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.await_turn_message_built",
+        message: "built await tick message",
+        meta: { awaitName: options.awaitName, checkedCount: options.checkedCount },
+    });
+    const lines = [];
+    lines.push(`await tick: ${options.awaitName} — ${options.condition}`);
+    if (options.body && options.body.trim().length > 0) {
+        lines.push("");
+        lines.push("what would count as ready:");
+        lines.push(options.body.trim());
+    }
+    const age = relativeAge(options.lastCheckedAt, options.now);
+    const obs = options.lastObservation && options.lastObservation.trim().length > 0
+        ? `last observation: "${options.lastObservation.trim()}"`
+        : "last observation: (none yet)";
+    if (options.checkedCount === 0) {
+        lines.push("");
+        lines.push("history: never checked. this is my first look.");
+    }
+    else {
+        lines.push("");
+        lines.push(`history: checked ${options.checkedCount}x so far. last checked ${age ?? "(unknown)"}. ${obs}.`);
+    }
+    if (options.checkpoint) {
+        lines.push("");
+        lines.push(`last checkpoint: ${options.checkpoint}`);
+    }
+    lines.push("");
+    lines.push("look around and decide. if the condition is met, call resolve_await with verdict='yes' and a one-line observation. otherwise call resolve_await with verdict='no' and a one-line observation of what i saw this tick.");
+    return lines.join("\n");
+}

package/dist/senses/inner-dialog-worker.js

@@ -119,9 +119,9 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
             });
         }
     }
-    async function run(reason, taskId, habitName) {
+    async function run(reason, taskId, habitName, awaitName) {
         if (running) {
-            queue.push({ reason, taskId, habitName });
+            queue.push({ reason, taskId, habitName, awaitName });
             return;
         }
         running = true;
@@ -129,10 +129,11 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
             let nextReason = reason;
             let nextTaskId = taskId;
             let nextHabitName = habitName;
+            let nextAwaitName = awaitName;
             let consecutiveInstinctTurns = reason === "instinct" ? 1 : 0;
             do {
                 try {
-                    await runTurn({ reason: nextReason, taskId: nextTaskId, habitName: nextHabitName });
+                    await runTurn({ reason: nextReason, taskId: nextTaskId, habitName: nextHabitName, awaitName: nextAwaitName });
                 }
                 catch (error) {
                     (0, runtime_1.emitNervesEvent)({
@@ -165,6 +166,7 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
                     nextReason = next.reason;
                     nextTaskId = next.taskId;
                     nextHabitName = next.habitName;
+                    nextAwaitName = next.awaitName;
                     consecutiveInstinctTurns = nextReason === "instinct" ? consecutiveInstinctTurns + 1 : 0;
                     continue;
                 }
@@ -191,6 +193,7 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
                     nextReason = "instinct";
                     nextTaskId = undefined;
                     nextHabitName = undefined;
+                    nextAwaitName = undefined;
                     continue;
                 }
                 break;
@@ -211,6 +214,13 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
             await run("habit", undefined, maybeMessage.habitName);
             return;
         }
+        if (maybeMessage.type === "await") {
+            /* v8 ignore next -- defensive fallback: live await dispatch always sets awaitName @preserve */
+            const awaitName = maybeMessage.awaitName ?? "(unnamed)";
+            recordHabitFireForRecursion(`await:${awaitName}`);
+            await run("await", undefined, undefined, maybeMessage.awaitName);
+            return;
+        }
         if (maybeMessage.type === "heartbeat") {
             // Backward compatibility: heartbeat -> habit/heartbeat
             recordHabitFireForRecursion("heartbeat");