@ouro.bot/cli 0.1.0-alpha.724 → 0.1.0-alpha.725

package/dist/heart/habits/habit-scheduler.js

@@ -41,6 +41,7 @@ const habit_runtime_state_1 = require("./habit-runtime-state");
 const cadence_1 = require("../daemon/cadence");
 const habit_policy_1 = require("../../rsvp/habit-policy");
 const WATCH_DEBOUNCE_MS = 200;
+const MAX_CRON_VERIFICATION_ATTEMPTS = 3;
 class HabitScheduler {
     agent;
     habitsDir;
@@ -53,8 +54,10 @@ class HabitScheduler {
     debounceTimer = null;
     parseErrors = [];
     timerFallbacks = new Map();
+    timerFallbackGenerations = new Map();
     degradedHabitNames = new Map();
     periodicTimer = null;
+    habitSnapshots = new Map();
     constructor(options) {
         this.agent = options.agent;
         this.habitsDir = options.habitsDir;
@@ -71,11 +74,7 @@ class HabitScheduler {
             message: "habit scheduler starting",
             meta: { agent: this.agent, habitsDir: this.habitsDir },
         });
-        const habits = this.scanHabits();
-        const jobs = this.buildJobs(habits);
-        this.osCronManager.sync(jobs);
-        this.verifyCronAndCreateFallbacks(jobs);
-        this.fireOverdueHabits(habits);
+        this.runSchedulingCycle();
     }
     reconcile() {
         (0, runtime_1.emitNervesEvent)({
@@ -86,21 +85,36 @@ class HabitScheduler {
         });
         // Clear ALL existing timers FIRST to prevent overlap window
         this.clearAllTimerFallbacks();
-        const habits = this.scanHabits();
-        const jobs = this.buildJobs(habits);
-        this.osCronManager.sync(jobs);
-        this.verifyCronAndCreateFallbacks(jobs);
-        this.fireOverdueHabits(habits);
+        this.runSchedulingCycle();
     }
-    fireOverdueHabits(habits) {
-        for (const habit of habits) {
-            if (habit.status !== "active")
-                continue;
-            if (!habit.cadence)
-                continue;
-            if (this.rejectInvalidRsvpHabit(habit))
+    runSchedulingCycle() {
+        const scannedHabits = this.scanHabits();
+        let state = this.revalidateState({
+            habits: scannedHabits,
+            jobs: this.buildJobs(scannedHabits),
+        });
+        if (!this.syncJobsFailClosed(state.jobs))
+            return;
+        const afterSync = this.revalidateAndCorrectJobs(state);
+        if (afterSync === null)
+            return;
+        state = afterSync;
+        const afterVerification = this.verifyCronAndCreateFallbacks(state);
+        if (afterVerification === null)
+            return;
+        state = afterVerification;
+        const beforeDispatch = this.revalidateAndCorrectJobs(state);
+        if (beforeDispatch === null)
+            return;
+        this.fireOverdueHabits(beforeDispatch);
+    }
+    fireOverdueHabits(state) {
+        for (const expectedJob of state.jobs) {
+            const habit = this.revalidateHabit(expectedJob.taskId);
+            if (habit === null)
                 continue;
-            if (this.rejectReservedCronNamespaceHabit(habit))
+            const currentJob = this.buildJobs([habit]).find((job) => job.id === expectedJob.id);
+            if (!currentJob || !this.jobEqual(expectedJob, currentJob))
                 continue;
             const nowMs = this.deps.now();
             const dueState = (0, cadence_1.evaluateCadenceDue)(habit.cadence, habit.lastRun, nowMs);
@@ -174,14 +188,21 @@ class HabitScheduler {
         if (!job) {
             return { ok: false, message: `unknown habit job: ${jobId}` };
         }
-        this.onHabitFire(job.taskId, trigger, {
-            occurrenceId: this.jobOccurrenceId(job, trigger),
+        const currentHabit = this.revalidateHabit(job.taskId);
+        const currentJob = currentHabit === null
+            ? undefined
+            : this.buildJobs([currentHabit]).find((candidate) => candidate.id === jobId);
+        if (!currentJob) {
+            return { ok: false, message: `unknown habit job: ${jobId}` };
+        }
+        this.onHabitFire(currentJob.taskId, trigger, {
+            occurrenceId: this.jobOccurrenceId(currentJob, trigger),
         });
         (0, runtime_1.emitNervesEvent)({
             component: "daemon",
             event: "daemon.habit_job_triggered",
             message: "habit scheduler job triggered",
-            meta: { agent: job.agent, habitName: job.taskId, jobId, trigger },
+            meta: { agent: currentJob.agent, habitName: currentJob.taskId, jobId, trigger },
         });
         return { ok: true, message: `triggered habit ${jobId}` };
     }
@@ -246,31 +267,69 @@ class HabitScheduler {
             this.scheduleNextReconciliation(intervalMs);
         }, intervalMs);
     }
-    verifyCronAndCreateFallbacks(jobs) {
-        if (!this.execForVerify)
-            return;
-        const verifiedLabels = this.verifyCronEntries();
-        for (const job of jobs) {
-            const label = `bot.ouro.${job.agent}.${job.taskId}`;
-            const isVerified = this.platform === "darwin"
-                ? verifiedLabels.has(label)
-                : verifiedLabels.has(job.taskId);
-            if (!isVerified) {
-                (0, runtime_1.emitNervesEvent)({
-                    component: "daemon",
-                    event: "daemon.habit_cron_verification_failed",
-                    message: `cron verification failed for habit: ${job.taskId}`,
-                    meta: { habitName: job.taskId, agent: job.agent, label },
-                });
-                // Parse cadence from the original habit file for timer interval
-                const habitFile = this.getHabitFile(job.taskId);
-                const ms = habitFile?.cadence ? (0, cadence_1.cadenceFallbackDelayMs)(habitFile.cadence, this.deps.now()) : null;
-                if (ms !== null) {
-                    this.createTimerFallback(job.taskId, habitFile.cadence, ms);
+    verifyCronAndCreateFallbacks(state) {
+        if (!this.execForVerify || state.jobs.length === 0)
+            return state;
+        let currentState = state;
+        for (let attempt = 1; attempt <= MAX_CRON_VERIFICATION_ATTEMPTS; attempt += 1) {
+            const verifiedLabels = this.verifyCronEntries();
+            const revalidatedState = this.revalidateAndCorrectJobs(currentState);
+            if (revalidatedState === null)
+                return null;
+            if (!this.jobsEqual(currentState.jobs, revalidatedState.jobs)) {
+                currentState = revalidatedState;
+                if (currentState.jobs.length === 0)
+                    return currentState;
+                continue;
+            }
+            currentState = revalidatedState;
+            for (const job of currentState.jobs) {
+                const label = `bot.ouro.${job.agent}.${job.taskId}`;
+                const isVerified = this.platform === "darwin"
+                    ? verifiedLabels.has(label)
+                    : verifiedLabels.has(job.taskId);
+                if (!isVerified) {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "daemon",
+                        event: "daemon.habit_cron_verification_failed",
+                        message: `cron verification failed for habit: ${job.taskId}`,
+                        meta: { habitName: job.taskId, agent: job.agent, label },
+                    });
+                    const habitFile = currentState.habits.find((habit) => habit.name === job.taskId);
+                    const cadence = habitFile.cadence;
+                    const ms = (0, cadence_1.cadenceFallbackDelayMs)(cadence, this.deps.now());
+                    if (ms !== null) {
+                        this.createTimerFallback(job.taskId, cadence, ms);
+                        this.degradedHabitNames.set(job.taskId, "cron registration failed — using timer fallback");
+                    }
+                    else {
+                        this.degradedHabitNames.set(job.taskId, "cron registration failed — no timer fallback available");
+                    }
                 }
-                this.degradedHabitNames.set(job.taskId, "cron registration failed — using timer fallback");
             }
+            return currentState;
+        }
+        this.clearAllTimerFallbacks();
+        let cleanupError = null;
+        try {
+            this.osCronManager.removeAll();
+        }
+        catch (error) {
+            cleanupError = this.errorMessage(error);
         }
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "daemon",
+            event: "daemon.habit_cron_verification_unstable",
+            message: "habit scheduler cron verification did not stabilize; fail-closed cleanup attempted",
+            meta: {
+                agent: this.agent,
+                attempts: MAX_CRON_VERIFICATION_ATTEMPTS,
+                jobCount: currentState.jobs.length,
+                cleanupError,
+            },
+        });
+        return null;
     }
     verifyCronEntries() {
         const verified = new Set();
@@ -302,25 +361,156 @@ class HabitScheduler {
         return verified;
     }
     createTimerFallback(habitName, cadence, firstDelayMs) {
+        if (this.timerFallbacks.has(habitName))
+            this.clearTimerFallback(habitName);
+        const generation = this.nextTimerFallbackGeneration(habitName);
         const schedule = () => {
             const delayMs = (0, cadence_1.cadenceFallbackDelayMs)(cadence, this.deps.now()) ?? firstDelayMs;
             const timer = setTimeout(() => {
+                const owner = this.timerFallbacks.get(habitName);
+                if (!owner || owner.handle !== timer || owner.generation !== generation)
+                    return;
+                const currentHabit = this.revalidateHabit(habitName);
+                const currentJob = currentHabit === null
+                    ? undefined
+                    : this.buildJobs([currentHabit]).find((job) => job.taskId === habitName);
+                if (!currentJob || currentHabit?.cadence !== cadence) {
+                    this.clearTimerFallback(habitName);
+                    return;
+                }
                 this.onHabitFire(habitName, "overdue", {
                     occurrenceId: this.timerOccurrenceId(habitName, cadence),
                 });
+                const currentOwner = this.timerFallbacks.get(habitName);
+                if (!currentOwner || currentOwner.handle !== timer || currentOwner.generation !== generation)
+                    return;
                 schedule();
             }, delayMs);
-            this.timerFallbacks.set(habitName, timer);
+            this.timerFallbacks.set(habitName, { handle: timer, cadence, generation });
         };
         schedule();
     }
     clearAllTimerFallbacks() {
-        for (const timer of this.timerFallbacks.values()) {
-            clearTimeout(timer);
-        }
-        this.timerFallbacks.clear();
+        for (const name of [...this.timerFallbacks.keys()])
+            this.clearTimerFallback(name);
         this.degradedHabitNames.clear();
     }
+    clearTimerFallback(name) {
+        const owner = this.timerFallbacks.get(name);
+        clearTimeout(owner.handle);
+        this.timerFallbacks.delete(name);
+        this.degradedHabitNames.delete(name);
+        this.nextTimerFallbackGeneration(name);
+    }
+    nextTimerFallbackGeneration(name) {
+        const generation = (this.timerFallbackGenerations.get(name) ?? 0) + 1;
+        this.timerFallbackGenerations.set(name, generation);
+        return generation;
+    }
+    revalidateState(state) {
+        const habits = [];
+        for (const habit of state.habits) {
+            const currentHabit = this.revalidateHabit(habit.name);
+            if (currentHabit !== null)
+                habits.push(currentHabit);
+        }
+        return { habits, jobs: this.buildJobs(habits) };
+    }
+    revalidateAndCorrectJobs(state) {
+        const currentState = this.revalidateState(state);
+        this.pruneTimerFallbacks(state, currentState);
+        if (this.jobsEqual(state.jobs, currentState.jobs))
+            return currentState;
+        return this.syncJobsFailClosed(currentState.jobs) ? currentState : null;
+    }
+    revalidateHabit(name) {
+        const file = `${name}.md`;
+        const filePath = path.join(this.habitsDir, file);
+        let content;
+        try {
+            content = this.deps.readFile(filePath, "utf-8");
+        }
+        catch (error) {
+            this.habitSnapshots.delete(name);
+            this.recordHabitParseError(file, `habit definition unreadable during scheduler revalidation: ${this.errorMessage(error)}`);
+            return null;
+        }
+        try {
+            const cached = this.habitSnapshots.get(name);
+            const definition = cached?.content === content
+                ? cached.definition
+                : (0, habit_parser_1.parseHabitFile)(content, filePath);
+            this.habitSnapshots.set(name, { content, definition });
+            const habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(path.dirname(this.habitsDir), definition);
+            this.recordDegradedHabitError(file, habit);
+            return habit;
+        }
+        catch (error) {
+            this.habitSnapshots.delete(name);
+            this.recordHabitParseError(file, this.errorMessage(error));
+            return null;
+        }
+    }
+    syncJobsFailClosed(jobs) {
+        try {
+            this.osCronManager.sync(jobs);
+            return true;
+        }
+        catch (error) {
+            this.clearAllTimerFallbacks();
+            let cleanupError = null;
+            try {
+                this.osCronManager.removeAll();
+            }
+            catch (cleanupFailure) {
+                cleanupError = this.errorMessage(cleanupFailure);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "daemon",
+                event: "daemon.habit_scheduler_sync_error",
+                message: "habit scheduler cron synchronization failed; fail-closed cleanup attempted",
+                meta: {
+                    agent: this.agent,
+                    error: this.errorMessage(error),
+                    cleanupError,
+                    jobCount: jobs.length,
+                },
+            });
+            return false;
+        }
+    }
+    pruneTimerFallbacks(previousState, currentState) {
+        for (const [name, owner] of this.timerFallbacks) {
+            const previousJob = previousState.jobs.find((job) => job.taskId === name);
+            const currentJob = currentState.jobs.find((job) => job.taskId === name);
+            const currentHabit = currentState.habits.find((habit) => habit.name === name);
+            if (previousJob
+                && currentJob
+                && currentHabit?.cadence === owner.cadence
+                && this.jobEqual(previousJob, currentJob))
+                continue;
+            this.clearTimerFallback(name);
+        }
+    }
+    jobsEqual(left, right) {
+        if (left.length !== right.length)
+            return false;
+        return left.every((job, index) => this.jobEqual(job, right[index]));
+    }
+    jobEqual(left, right) {
+        return right !== undefined
+            && left.id === right.id
+            && left.agent === right.agent
+            && left.taskId === right.taskId
+            && left.schedule === right.schedule
+            && left.lastRun === right.lastRun
+            && left.command === right.command
+            && left.taskPath === right.taskPath;
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
     scanHabits() {
         let files;
         try {
@@ -328,21 +518,36 @@ class HabitScheduler {
         }
         catch {
             this.parseErrors = [];
+            this.habitSnapshots.clear();
             return [];
         }
         const habits = [];
         const errors = [];
+        const snapshots = new Map();
         for (const file of files) {
             if (!file.endsWith(".md"))
                 continue;
             const filePath = path.join(this.habitsDir, file);
             try {
                 const content = this.deps.readFile(filePath, "utf-8");
-                const habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(path.dirname(this.habitsDir), (0, habit_parser_1.parseHabitFile)(content, filePath));
+                const definition = (0, habit_parser_1.parseHabitFile)(content, filePath);
+                const habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(path.dirname(this.habitsDir), definition);
+                snapshots.set(habit.name, { content, definition });
                 habits.push(habit);
+                if (habit.status === "degraded") {
+                    const error = `habit definition degraded: ${habit.degradedReason}`;
+                    errors.push({ file, error });
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "daemon",
+                        event: "daemon.habit_parse_error",
+                        message: "failed to parse habit file",
+                        meta: { file, error, agent: this.agent },
+                    });
+                }
             }
             catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
+                const errorMessage = this.errorMessage(error);
                 errors.push({ file, error: errorMessage });
                 (0, runtime_1.emitNervesEvent)({
                     level: "error",
@@ -358,6 +563,7 @@ class HabitScheduler {
             }
         }
         this.parseErrors = errors;
+        this.habitSnapshots = snapshots;
         return habits;
     }
     buildJobs(habits) {
@@ -398,6 +604,18 @@ class HabitScheduler {
         this.recordHabitParseError(`${habit.name}.md`, "habit names cannot start with reserved cron namespace 'await.'");
         return true;
     }
+    recordDegradedHabitError(file, habit) {
+        const prefix = "habit definition degraded: ";
+        if (habit.status !== "degraded") {
+            this.parseErrors = this.parseErrors.filter((entry) => entry.file !== file || !entry.error.startsWith(prefix));
+            return;
+        }
+        const error = `${prefix}${habit.degradedReason}`;
+        if (this.parseErrors.some((entry) => entry.file === file && entry.error === error))
+            return;
+        this.parseErrors = this.parseErrors.filter((entry) => entry.file !== file || !entry.error.startsWith(prefix));
+        this.recordHabitParseError(file, error);
+    }
     recordHabitParseError(file, error) {
         if (this.parseErrors.some((existing) => existing.file === file && existing.error === error))
             return;

package/dist/heart/habits/habit-session.js

@@ -254,6 +254,22 @@ function parseExtraRouteSpec(spec) {
     return { recipient: parts[0], channel: parts[1], key: parts[2] };
 }
 async function normalizeHabitPermissionEnvelope(habit, options) {
+    if (habit.status !== "active") {
+        const envelope = {
+            schemaVersion: 1,
+            canMessageOutward: false,
+            returnRoutes: [],
+            deniedTools: ["send_message", "surface"],
+            warnings: [`habit status ${habit.status} is non-executable`],
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.habit_permission_envelope_normalized",
+            message: "habit permission envelope normalized",
+            meta: { agentRoot: options.agentRoot, habitName: habit.name, routes: 0, canMessageOutward: false },
+        });
+        return envelope;
+    }
     const returnRoutes = [];
     const warnings = [];
     if (habit.surface.family) {

package/dist/heart/hatch/hatch-flow.js

@@ -44,6 +44,7 @@ const runtime_1 = require("../../nerves/runtime");
 const auth_flow_1 = require("../auth/auth-flow");
 const provider_models_1 = require("../provider-models");
 const habit_parser_1 = require("../habits/habit-parser");
+const habit_lifecycle_1 = require("../habits/habit-lifecycle");
 const bundle_manifest_1 = require("../../mind/bundle-manifest");
 const record_paths_1 = require("../../mind/record-paths");
 const hatch_specialist_1 = require("./hatch-specialist");
@@ -77,16 +78,17 @@ function writeReadme(dir, purpose) {
     }
 }
 function writeHeartbeatHabit(bundleRoot, now) {
-    const habitsDir = path.join(bundleRoot, "habits");
-    fs.mkdirSync(habitsDir, { recursive: true });
-    const filePath = path.join(habitsDir, "heartbeat.md");
     const content = (0, habit_parser_1.renderHabitFile)({
         title: "Heartbeat check-in",
         cadence: "30m",
         status: "active",
         created: now.toISOString(),
     }, "Run a lightweight heartbeat cycle. Review task board and inbox.\nCheck on pending obligations. Write important durable outputs to Arc or Desk record.");
-    fs.writeFileSync(filePath, content, "utf-8");
+    (0, habit_lifecycle_1.publishNewHabitDefinition)({
+        agentRoot: bundleRoot,
+        habitId: "heartbeat",
+        bytes: content,
+    });
 }
 function writeFriendImprint(bundleRoot, humanName, now) {
     const friendsDir = path.join(bundleRoot, "friends");

package/dist/heart/mailbox/readers/runtime-readers.js

@@ -568,38 +568,37 @@ function readHabitView(agentRoot, options = {}) {
     for (const file of (0, shared_1.safeReaddir)(habitsDir)) {
         if (!file.endsWith(".md"))
             continue;
+        const filePath = path.join(habitsDir, file);
+        let habit;
         try {
-            const filePath = path.join(habitsDir, file);
             const raw = fs.readFileSync(filePath, "utf-8");
-            if (!/^---\r?\n[\s\S]*?\r?\n---/.test(raw))
-                continue;
-            const habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(agentRoot, (0, habit_parser_1.parseHabitFile)(raw, filePath));
-            const cadenceMs = parseCadenceMs(habit.cadence);
-            let isOverdue = false;
-            let overdueMs = null;
-            if (habit.status === "active" && habit.lastRun && cadenceMs) {
-                const elapsed = now.getTime() - Date.parse(habit.lastRun);
-                if (elapsed > cadenceMs) {
-                    isOverdue = true;
-                    overdueMs = elapsed - cadenceMs;
-                }
-            }
-            items.push({
-                name: habit.name,
-                title: habit.title,
-                cadence: habit.cadence,
-                status: habit.status,
-                lastRun: habit.lastRun,
-                bodyExcerpt: (0, shared_1.truncateExcerpt)(habit.body, 120),
-                isDegraded: false,
-                degradedReason: null,
-                isOverdue,
-                overdueMs,
-            });
+            habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(agentRoot, (0, habit_parser_1.parseHabitFile)(raw, filePath));
         }
         catch {
-            // skip unparseable habit files
+            habit = (0, habit_parser_1.createDegradedHabitFile)(filePath, "read_error");
         }
+        const cadenceMs = parseCadenceMs(habit.cadence);
+        let isOverdue = false;
+        let overdueMs = null;
+        if (habit.status === "active" && habit.lastRun && cadenceMs) {
+            const elapsed = now.getTime() - Date.parse(habit.lastRun);
+            if (elapsed > cadenceMs) {
+                isOverdue = true;
+                overdueMs = elapsed - cadenceMs;
+            }
+        }
+        items.push({
+            name: habit.name,
+            title: habit.title,
+            cadence: habit.cadence,
+            status: habit.status,
+            lastRun: habit.lastRun,
+            bodyExcerpt: (0, shared_1.truncateExcerpt)(habit.body, 120),
+            isDegraded: habit.status === "degraded",
+            degradedReason: habit.status === "degraded" ? habit.degradedReason : null,
+            isOverdue,
+            overdueMs,
+        });
     }
     items.sort((a, b) => {
         if (a.isOverdue && !b.isOverdue)

package/dist/heart/orientation-frame.js

@@ -1,11 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLICIT_PRIOR_WORK_RESUME_INSTRUCTION = exports.BACKGROUND_ONLY_INSTRUCTION = void 0;
+exports.priorWorkInstruction = priorWorkInstruction;
+exports.labelPriorWorkSurface = labelPriorWorkSurface;
 exports.extractMessageText = extractMessageText;
 exports.extractOrderedListReferents = extractOrderedListReferents;
 exports.buildOrientationFrame = buildOrientationFrame;
 exports.renderOrientationFrame = renderOrientationFrame;
 const runtime_1 = require("../nerves/runtime");
 const structured_output_1 = require("./structured-output");
+exports.BACKGROUND_ONLY_INSTRUCTION = "Background only; do not execute.";
+exports.EXPLICIT_PRIOR_WORK_RESUME_INSTRUCTION = "Prior work explicitly resumed by the current trigger.";
+function priorWorkInstruction(resumePriorWork) {
+    return resumePriorWork
+        ? exports.EXPLICIT_PRIOR_WORK_RESUME_INSTRUCTION
+        : exports.BACKGROUND_ONLY_INSTRUCTION;
+}
+/**
+ * Put the prior-work authority label directly under a section heading when one
+ * exists, otherwise before the surface. This keeps the label adjacent to the
+ * exact stale-work surface it governs instead of relying on a distant prompt
+ * preamble.
+ */
+function labelPriorWorkSurface(surface, resumePriorWork) {
+    if (!surface)
+        return "";
+    const instruction = priorWorkInstruction(resumePriorWork);
+    const inlineBoldHeading = /^(\*\*[^*]+:\*\*)\s+([\s\S]+)$/.exec(surface);
+    if (inlineBoldHeading) {
+        return `${inlineBoldHeading[1]}\n${instruction}\n${inlineBoldHeading[2]}`;
+    }
+    const newlineIndex = surface.indexOf("\n");
+    const firstLine = newlineIndex === -1 ? surface : surface.slice(0, newlineIndex);
+    if (firstLine.startsWith("## ") || /^\*\*[^*]+:\*\*$/.test(firstLine)) {
+        const remainder = newlineIndex === -1 ? "" : surface.slice(newlineIndex + 1);
+        return [firstLine, instruction, remainder].filter((part) => part.length > 0).join("\n");
+    }
+    return `${instruction}\n${surface}`;
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -221,7 +253,7 @@ function buildOrientationFrame(input) {
 }
 function renderOrientationFrame(frame) {
     const lines = [
-        "## orientation frame",
+        "## Current trigger (authoritative)",
         `channel: ${frame.channel}`,
         `action policy: ${frame.actionPolicy.mode}`,
     ];
@@ -240,6 +272,31 @@ function renderOrientationFrame(frame) {
     if (frame.source) {
         lines.push("source:");
         lines.push(`- kind: ${frame.source.kind}`);
+        if (frame.source.authority === "presentation_only") {
+            lines.push("- source authority: presentation only; never tool authority");
+        }
+        if (frame.source.conversationKind) {
+            lines.push(`- conversation kind: ${frame.source.conversationKind}`);
+        }
+        if (frame.source.event) {
+            lines.push(`- event: ${frame.source.event.kind} (${frame.source.event.sourceEventType}; from me: ${String(frame.source.event.fromMe)})`);
+        }
+        if (frame.source.actor) {
+            const actorLabel = frame.source.actor.displayName?.trim() || frame.source.actor.externalId;
+            lines.push(`- observed actor: ${actorLabel} [${frame.source.actor.provider}:${frame.source.actor.externalId}]`);
+        }
+        if (frame.source.participants) {
+            for (const participant of frame.source.participants) {
+                const participantLabel = participant.displayName?.trim() || participant.externalId;
+                lines.push(`- group participant only: ${participantLabel} [${participant.provider}:${participant.externalId}]`);
+            }
+        }
+        if (frame.source.conversationKind === "group") {
+            lines.push("- participant membership is not evidence that someone spoke, read, requested, or authored a reaction target.");
+        }
+        if (frame.source.target) {
+            lines.push(`- target: ${frame.source.target.messageGuid} (authorship: ${frame.source.target.authorship})`);
+        }
         if (frame.source.lane)
             lines.push(`- lane: ${frame.source.lane}`);
         if (frame.source.defaultReplyTarget)

package/dist/heart/provider-attempt.js

@@ -44,6 +44,9 @@ function httpStatus(error) {
 function delayForAttempt(policy, attempt) {
     return policy.baseDelayMs * Math.pow(policy.backoffMultiplier, attempt - 1);
 }
+function isRetryable(error) {
+    return error.retryable !== false;
+}
 async function runProviderAttempt(input) {
     const policy = normalizePolicy(input.policy);
     const maxAttempts = Math.max(1, Math.floor(policy.maxAttempts));
@@ -74,7 +77,7 @@ async function runProviderAttempt(input) {
                 throw caught;
             const error = toError(caught);
             const classification = classify(caught, input.classifyError);
-            const willRetry = attempt < maxAttempts;
+            const willRetry = isRetryable(error) && attempt < maxAttempts;
             const delayMs = willRetry ? delayForAttempt(policy, attempt) : undefined;
             const record = {
                 attempt,