akemon 0.2.23 → 0.2.25

package/dist/engine-peripheral.js

@@ -13,6 +13,9 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import { join, dirname, isAbsolute } from "path";
 import { callAgent } from "./relay-client.js";
 import { SIG, sig } from "./types.js";
+import { updateMetrics, pushExecMs } from "./metrics.js";
+import { sendFailureEvent } from "./relay-client.js";
+import { resolveEngineConfig, } from "./engine-routing.js";
 export const LLM_ENGINES = new Set(["claude", "codex", "opencode", "gemini", "raw"]);
 // ---------------------------------------------------------------------------
 // EnginePeripheral
@@ -24,11 +27,29 @@ export class EnginePeripheral {
     tags = ["engine", "llm"];
     config;
     bus = null;
-    /** Engine mutual exclusion — only one engine process at a time */
-    busy = false;
-    busySince = 0;
     /** Last execution trace (for error reporting) */
     lastTrace = [];
+    /** Active CLI child processes — tracked so SIGTERM handler can kill them. */
+    activeChildren = new Set();
+    /**
+     * Send SIGKILL to all active child process groups. Called during daemon shutdown.
+     *
+     * NOTE: sends SIGKILL directly (no SIGTERM grace) — safe for stateless
+     * request/response CLIs. Must change to SIGTERM+3s+SIGKILL when Batch 5.1
+     * persistent-session mode lands (sessions need graceful teardown).
+     */
+    killAllChildren() {
+        for (const child of this.activeChildren) {
+            if (!child.pid)
+                continue;
+            console.log(`[engine] shutdown: killing pgid=-${child.pid}`);
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch { }
+        }
+        this.activeChildren.clear();
+    }
     constructor(config) {
         this.config = config;
         this.id = `engine:${config.engine}`;
@@ -70,47 +91,34 @@ export class EnginePeripheral {
         }, this.id);
     }
     // ---------------------------------------------------------------------------
-    // Engine mutex helpers
-    // ---------------------------------------------------------------------------
-    acquire() {
-        if (this.busy)
-            return false;
-        this.busy = true;
-        this.busySince = Date.now();
-        return true;
-    }
-    release() {
-        this.busy = false;
-        this.busySince = 0;
-    }
-    /** Watchdog: reset if stuck for > 10 min */
-    checkStuck() {
-        if (this.busy && this.busySince > 0 && Date.now() - this.busySince > 10 * 60 * 1000) {
-            console.log(`[watchdog] engine stuck for ${Math.round((Date.now() - this.busySince) / 1000)}s, force-resetting`);
-            this.release();
-            return true;
-        }
-        return false;
-    }
-    // ---------------------------------------------------------------------------
     // Unified engine runner
     // ---------------------------------------------------------------------------
-    async runEngine(task, allowAll, extraAllowedTools) {
-        const { engine, model, workdir } = this.config;
-        if (engine === "raw") {
-            return this.runRawEngine(task);
+    async runEngine(task, allowAll, extraAllowedTools, signal, origin, routing) {
+        const entry = resolveEngineConfig(routing, origin);
+        const cfg = entry ? applyRoutingEntry(this.config, entry) : this.config;
+        if (origin && entry) {
+            console.log(`[engine] using ${cfg.engine}${cfg.model ? `/${cfg.model}` : ""} (origin=${origin})`);
+        }
+        const t0 = Date.now();
+        try {
+            if (cfg.engine === "raw") {
+                return await this.runRawEngine(task, cfg);
+            }
+            const cmd = buildEngineCommand(cfg.engine, cfg.model, allowAll ?? cfg.allowAll, extraAllowedTools);
+            return await runCommand(cmd.cmd, cmd.args, task, cfg.workdir, cmd.stdinMode, signal, this.activeChildren);
+        }
+        finally {
+            pushExecMs(Date.now() - t0);
         }
-        const cmd = buildEngineCommand(engine, model, allowAll ?? this.config.allowAll, extraAllowedTools);
-        return runCommand(cmd.cmd, cmd.args, task, workdir, cmd.stdinMode);
     }
     // ---------------------------------------------------------------------------
     // Raw engine: OpenAI-compatible API with tool call loop
     // ---------------------------------------------------------------------------
-    async runRawEngine(task) {
-        const apiUrl = (this.config.rawApiUrl || "http://localhost:11434/v1") + "/chat/completions";
-        const modelName = this.config.model || "gemma4:4b";
-        const maxRounds = this.config.rawMaxRounds || 20;
-        const apiKey = this.config.rawApiKey || "";
+    async runRawEngine(task, cfg = this.config) {
+        const apiUrl = (cfg.rawApiUrl || "http://localhost:11434/v1") + "/chat/completions";
+        const modelName = cfg.model || "gemma4:4b";
+        const maxRounds = cfg.rawMaxRounds || 20;
+        const apiKey = cfg.rawApiKey || "";
         console.log(`[raw] Task:\n${task}`);
         const trace = [];
         this.lastTrace = trace;
@@ -358,6 +366,25 @@ export const RAW_TOOLS = [
 // ---------------------------------------------------------------------------
 // CLI engine helpers (shared, non-class)
 // ---------------------------------------------------------------------------
+/**
+ * Build a local EngineConfig copy that merges in a routing entry's overrides.
+ * Resolves rawApiKeyEnv → rawApiKey from environment at call time.
+ * Never mutates the base config.
+ */
+function applyRoutingEntry(base, entry) {
+    const override = { engine: entry.engine };
+    if (entry.model !== undefined)
+        override.model = entry.model ?? undefined;
+    if (entry.rawApiUrl !== undefined)
+        override.rawApiUrl = entry.rawApiUrl;
+    if (entry.rawMaxRounds !== undefined)
+        override.rawMaxRounds = entry.rawMaxRounds;
+    if (entry.allowAll !== undefined)
+        override.allowAll = entry.allowAll;
+    if (entry.rawApiKeyEnv)
+        override.rawApiKey = process.env[entry.rawApiKeyEnv] ?? "";
+    return { ...base, ...override };
+}
 function buildEngineCommand(engine, model, allowAll, extraAllowedTools) {
     switch (engine) {
         case "claude": {
@@ -390,7 +417,7 @@ function buildEngineCommand(engine, model, allowAll, extraAllowedTools) {
             return { cmd: engine, args: [], stdinMode: true };
     }
 }
-function runCommand(cmd, args, task, cwd, stdinMode = true) {
+function runCommand(cmd, args, task, cwd, stdinMode = true, signal, activeChildren) {
     return new Promise((resolve, reject) => {
         const { CLAUDECODE, ...cleanEnv } = process.env;
         const finalArgs = stdinMode ? args : [...args, task];
@@ -399,8 +426,39 @@ function runCommand(cmd, args, task, cwd, stdinMode = true) {
             cwd,
             env: cleanEnv,
             stdio: [stdinMode ? "pipe" : "ignore", "pipe", "pipe"],
-            timeout: 300_000,
+            detached: true, // child becomes process-group leader; enables pgid kill
         });
+        if (activeChildren) {
+            activeChildren.add(child);
+            updateMetrics({ engine_children_active: activeChildren.size });
+        }
+        // Abort → SIGTERM to process group, then SIGKILL after grace period.
+        // Using -pid (negative) sends the signal to the entire process group,
+        // so any sub-forks spawned by the CLI are also terminated.
+        let aborted = false;
+        const onAbort = () => {
+            if (aborted || !child.pid)
+                return;
+            aborted = true;
+            console.log(`[${cmd}] aborted, killing pgid=-${child.pid}`);
+            sendFailureEvent("engine_abort", cmd, "engine subprocess aborted via signal");
+            try {
+                process.kill(-child.pid, "SIGTERM");
+            }
+            catch { }
+            setTimeout(() => {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch { }
+            }, 3000).unref();
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        }
         if (stdinMode && child.stdin) {
             child.stdin.on("error", () => { });
             child.stdin.write(task);
@@ -414,12 +472,22 @@ function runCommand(cmd, args, task, cwd, stdinMode = true) {
         child.stderr?.on("data", (chunk) => {
             stderr += chunk.toString();
         });
-        child.on("close", (code) => {
-            console.log(`[${cmd}] exit=${code} stdout=${stdout.length}b stderr=${stderr.length}b`);
+        child.on("close", (code, killSignal) => {
+            signal?.removeEventListener("abort", onAbort);
+            if (activeChildren) {
+                activeChildren.delete(child);
+                updateMetrics({ engine_children_active: activeChildren.size });
+            }
+            child.unref();
+            console.log(`[${cmd}] exit=${code}${killSignal ? ` signal=${killSignal}` : ""} stdout=${stdout.length}b stderr=${stderr.length}b`);
             if (stderr)
                 console.log(`[${cmd}] stderr:\n${stderr}`);
             if (stdout)
                 console.log(`[${cmd}] stdout:\n${stdout}`);
+            if (aborted) {
+                reject(new Error(`${cmd} aborted`));
+                return;
+            }
             const output = stdout.trim();
             if (output) {
                 resolve(output);
@@ -428,6 +496,14 @@ function runCommand(cmd, args, task, cwd, stdinMode = true) {
                 reject(new Error(`${cmd} exited with code ${code}, no stdout`));
             }
         });
-        child.on("error", reject);
+        child.on("error", (err) => {
+            signal?.removeEventListener("abort", onAbort);
+            if (activeChildren) {
+                activeChildren.delete(child);
+                updateMetrics({ engine_children_active: activeChildren.size });
+            }
+            child.unref();
+            reject(err);
+        });
     });
 }

package/dist/engine-queue.js

@@ -0,0 +1,143 @@
+/**
+ * EngineQueue — priority-aware single-slot scheduler for the local engine.
+ *
+ * Only one engine subprocess may run at a time. All modules (orders, digestion,
+ * reflection, script activities, MCP ad-hoc calls, …) go through this queue so
+ * that higher-priority work does not starve behind background busywork.
+ *
+ * Ordering:
+ *   - When the slot is free, acquire() returns immediately.
+ *   - Otherwise callers wait; when the running job releases the slot, the
+ *     highest-priority waiter wins (FIFO within the same priority).
+ *   - If the caller's deadline elapses first, acquire() rejects with
+ *     "Engine busy timeout" and the caller is removed from the queue.
+ *
+ * Priority semantics (keep in sync with types.ts ComputeRequest.priority):
+ *   - high   — user-waiting work (orders, user tasks, direct MCP calls)
+ *   - normal — periodic self-maintenance that must not starve (digestion,
+ *              reflection)
+ *   - low    — background enrichment (platform tasks, script activities,
+ *              long-term, identity compression)
+ */
+import { updateMetrics } from "./metrics.js";
+const PRIORITY_RANK = { high: 3, normal: 2, low: 1 };
+/** Max simultaneous user_manual tasks allowed to hold or wait for a slot.
+ *  Prevents more than this many claude CLI processes from queuing up. */
+const DEFAULT_MAX_USER_MANUAL = 2;
+export class EngineQueue {
+    busy = false;
+    busySince = 0;
+    waiters = [];
+    // User-manual concurrency gate
+    maxUserManualSlots;
+    userManualActive = 0;
+    userManualQueue = [];
+    constructor(maxUserManualSlots = DEFAULT_MAX_USER_MANUAL) {
+        this.maxUserManualSlots = maxUserManualSlots;
+    }
+    /** Acquire a user_manual slot before joining the engine queue.
+     *  Callers MUST call releaseUserManualSlot() in a finally block. */
+    acquireUserManualSlot(deadlineMs) {
+        if (this.userManualActive < this.maxUserManualSlots) {
+            this.userManualActive++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            let timerRef;
+            const entry = {
+                resolve: () => { clearTimeout(timerRef); resolve(); },
+                reject: (err) => { clearTimeout(timerRef); reject(err); },
+            };
+            timerRef = setTimeout(() => {
+                const idx = this.userManualQueue.indexOf(entry);
+                if (idx >= 0)
+                    this.userManualQueue.splice(idx, 1);
+                entry.reject(new Error("User manual slot timeout"));
+            }, deadlineMs);
+            this.userManualQueue.push(entry);
+        });
+    }
+    /** Release a user_manual slot and wake the next waiter. */
+    releaseUserManualSlot() {
+        const next = this.userManualQueue.shift();
+        if (next) {
+            // Transfer slot to the next waiter (active count unchanged)
+            next.resolve();
+        }
+        else {
+            this.userManualActive = Math.max(0, this.userManualActive - 1);
+        }
+    }
+    /** Wait up to `deadlineMs` for the slot, then take it. */
+    acquire(priority, deadlineMs) {
+        if (!this.busy) {
+            this.busy = true;
+            this.busySince = Date.now();
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                priority,
+                enqueuedAt: Date.now(),
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    const idx = this.waiters.indexOf(waiter);
+                    if (idx >= 0) {
+                        this.waiters.splice(idx, 1);
+                        updateMetrics({ engine_queue_depth: this.waiters.length });
+                    }
+                    reject(new Error(`Engine busy timeout (${Math.round(deadlineMs / 60000)} min)`));
+                }, deadlineMs),
+            };
+            this.waiters.push(waiter);
+            updateMetrics({ engine_queue_depth: this.waiters.length });
+        });
+    }
+    /** Release the slot and hand it to the best waiter, if any. */
+    release() {
+        const next = this.pickNext();
+        if (!next) {
+            this.busy = false;
+            this.busySince = 0;
+            return;
+        }
+        this.waiters.splice(this.waiters.indexOf(next), 1);
+        clearTimeout(next.timer);
+        this.busySince = Date.now();
+        updateMetrics({ engine_queue_depth: this.waiters.length });
+        next.resolve();
+    }
+    /** Take the slot synchronously (used by MCP fast-path when !isBusy). */
+    tryAcquire() {
+        if (this.busy)
+            return false;
+        this.busy = true;
+        this.busySince = Date.now();
+        return true;
+    }
+    isBusy() {
+        return this.busy;
+    }
+    queueDepth() {
+        return this.waiters.length;
+    }
+    /** How long has the current holder held the slot, in ms. 0 if free. */
+    heldMs() {
+        return this.busy && this.busySince ? Date.now() - this.busySince : 0;
+    }
+    pickNext() {
+        if (this.waiters.length === 0)
+            return null;
+        let best = this.waiters[0];
+        for (let i = 1; i < this.waiters.length; i++) {
+            const w = this.waiters[i];
+            const wr = PRIORITY_RANK[w.priority];
+            const br = PRIORITY_RANK[best.priority];
+            if (wr > br || (wr === br && w.enqueuedAt < best.enqueuedAt)) {
+                best = w;
+            }
+        }
+        return best;
+    }
+}

package/dist/engine-queue.test.js

@@ -0,0 +1,99 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { EngineQueue } from "./engine-queue.js";
+// Helpers
+const tick = () => new Promise((r) => setImmediate(r));
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+describe("EngineQueue", () => {
+    it("free slot: acquire resolves immediately and isBusy becomes true", async () => {
+        const q = new EngineQueue();
+        assert.equal(q.isBusy(), false);
+        await q.acquire("high", 1000);
+        assert.equal(q.isBusy(), true);
+        q.release();
+        assert.equal(q.isBusy(), false);
+    });
+    it("tryAcquire: succeeds when free, returns false when busy", () => {
+        const q = new EngineQueue();
+        assert.equal(q.tryAcquire(), true);
+        assert.equal(q.isBusy(), true);
+        assert.equal(q.tryAcquire(), false);
+        q.release();
+    });
+    it("priority ordering: high waiter beats normal when slot is released", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000); // take the slot
+        const order = [];
+        const p1 = q.acquire("normal", 2000).then(() => { order.push("normal"); q.release(); });
+        await tick();
+        const p2 = q.acquire("high", 2000).then(() => { order.push("high"); q.release(); });
+        await tick();
+        assert.equal(q.queueDepth(), 2);
+        q.release(); // hand off to highest-priority waiter
+        await Promise.all([p1, p2]);
+        assert.deepEqual(order, ["high", "normal"]);
+    });
+    it("FIFO within same priority: earlier enqueuer wins", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000);
+        const order = [];
+        const p1 = q.acquire("normal", 2000).then(() => { order.push("first"); q.release(); });
+        await sleep(5); // ensure different enqueuedAt timestamps
+        const p2 = q.acquire("normal", 2000).then(() => { order.push("second"); q.release(); });
+        await tick();
+        q.release();
+        await Promise.all([p1, p2]);
+        assert.deepEqual(order, ["first", "second"]);
+    });
+    it("deadline timeout: waiter is removed and rejects with busy-timeout error", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000); // hold the slot
+        let caught = null;
+        const p = q.acquire("low", 30).catch((e) => { caught = e; });
+        await sleep(60); // let the 30ms deadline fire
+        assert.equal(q.queueDepth(), 0, "waiter must be removed after timeout");
+        await p;
+        assert.ok(caught !== null && typeof caught === "object", "should have rejected with an Error");
+        const msg = caught.message;
+        assert.ok(msg.includes("Engine busy timeout"), msg);
+        q.release();
+    });
+    it("release with no waiters makes slot free", () => {
+        const q = new EngineQueue();
+        assert.equal(q.tryAcquire(), true);
+        q.release();
+        assert.equal(q.isBusy(), false);
+        assert.equal(q.heldMs(), 0);
+    });
+    it("queueDepth tracks waiters correctly", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000);
+        assert.equal(q.queueDepth(), 0);
+        const p1 = q.acquire("normal", 2000);
+        await tick();
+        assert.equal(q.queueDepth(), 1);
+        const p2 = q.acquire("low", 2000);
+        await tick();
+        assert.equal(q.queueDepth(), 2);
+        q.release(); // hand to normal (higher priority)
+        await tick();
+        assert.equal(q.queueDepth(), 1);
+        const holder = await p1; // p1 resolved — release it
+        void holder; // suppress unused warning
+        q.release();
+        await p2;
+        q.release();
+        assert.equal(q.queueDepth(), 0);
+    });
+    it("heldMs: returns 0 when free, positive when busy", async () => {
+        const q = new EngineQueue();
+        assert.equal(q.heldMs(), 0);
+        await q.acquire("high", 1000);
+        await sleep(10);
+        assert.ok(q.heldMs() >= 10, `heldMs should be >= 10, got ${q.heldMs()}`);
+        q.release();
+        assert.equal(q.heldMs(), 0);
+    });
+});

package/dist/engine-routing.js

@@ -0,0 +1,52 @@
+/**
+ * engine-routing.ts — pure helpers for origin-based engine selection.
+ *
+ * Three exported pure functions (each independently unit-tested):
+ *   resolveEngineConfig  — picks which engine/model to use for a given origin
+ *   deriveChildOrigin    — returns the origin a child/sub-task should carry
+ *   downgradeForRetry    — downgrades any origin to "retry" when a task retries
+ */
+/**
+ * Resolve which engine routing entry to use for a given origin.
+ *
+ * Lookup order:
+ *   1. routing[origin]   (exact match)
+ *   2. routing.default   (fallback)
+ *   3. null              (no routing configured → caller uses base engine config)
+ *
+ * Backward-compatible: if routing is undefined/null, returns null, meaning the
+ * caller should use whatever engine is already in the base EngineConfig.
+ */
+export function resolveEngineConfig(routing, origin) {
+    if (!routing)
+        return null;
+    if (origin) {
+        const exact = routing[origin];
+        if (exact)
+            return exact;
+    }
+    return routing.default ?? null;
+}
+/**
+ * Derive the origin that a child task should carry.
+ *
+ * "Human contamination" rule: human intent does NOT cross agent boundaries.
+ * Regardless of what the parent's origin is, any task spawned for/from another
+ * agent is always "platform" on the receiving side.
+ *
+ * Example: user_manual order → agent A calls agent B via MCP →
+ *          agent B's resulting order has origin "platform", not "user_manual".
+ */
+export function deriveChildOrigin(_parentOrigin) {
+    return "platform";
+}
+/**
+ * Downgrade the origin when a task enters the retry path.
+ *
+ * Retries must not consume the subscription CLI budget even if the original
+ * task was user_manual. Downgrading to "retry" lets the routing table send
+ * them to a cheaper API engine.
+ */
+export function downgradeForRetry(_origin) {
+    return "retry";
+}

package/dist/engine-routing.test.js

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveEngineConfig, deriveChildOrigin, downgradeForRetry, } from "./engine-routing.js";
+// ---------------------------------------------------------------------------
+// resolveEngineConfig
+// ---------------------------------------------------------------------------
+describe("resolveEngineConfig", () => {
+    const claudeEntry = { engine: "claude", model: "claude-opus-4-5" };
+    const rawEntry = { engine: "raw", rawApiUrl: "https://api.deepseek.com/v1", model: "deepseek-chat", rawApiKeyEnv: "DEEPSEEK_API_KEY" };
+    const defaultEntry = { engine: "raw", rawApiUrl: "https://api.anthropic.com/v1", model: "claude-haiku-4-5", rawApiKeyEnv: "ANTHROPIC_API_KEY" };
+    it("returns exact origin entry when routing has that origin", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            platform: rawEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "user_manual");
+        assert.deepEqual(result, claudeEntry);
+    });
+    it("returns platform entry for platform origin", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            platform: rawEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "platform");
+        assert.deepEqual(result, rawEntry);
+    });
+    it("falls back to default when origin not in routing", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            default: defaultEntry,
+        };
+        // self_cycle not in routing → fallback to default
+        const result = resolveEngineConfig(routing, "self_cycle");
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("falls back to default when origin is undefined", () => {
+        const routing = { default: defaultEntry };
+        const result = resolveEngineConfig(routing, undefined);
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("returns null when routing is undefined (backward-compat: use base config)", () => {
+        const result = resolveEngineConfig(undefined, "user_manual");
+        assert.equal(result, null);
+    });
+    it("returns null when routing is null", () => {
+        const result = resolveEngineConfig(null, "user_manual");
+        assert.equal(result, null);
+    });
+    it("returns null when routing has no matching entry and no default", () => {
+        const routing = { user_manual: claudeEntry };
+        // self_cycle not in routing, no default
+        const result = resolveEngineConfig(routing, "self_cycle");
+        assert.equal(result, null);
+    });
+    it("returns null when routing is empty object and origin is undefined", () => {
+        const result = resolveEngineConfig({}, undefined);
+        assert.equal(result, null);
+    });
+    it("retry origin resolves to its own routing entry when configured", () => {
+        const retryEntry = { engine: "raw", rawApiUrl: "https://api.deepseek.com/v1", model: "deepseek-chat" };
+        const routing = {
+            user_manual: claudeEntry,
+            retry: retryEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "retry");
+        assert.deepEqual(result, retryEntry);
+    });
+    it("retry origin falls back to default when no retry entry configured", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "retry");
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("reflection origin resolves correctly", () => {
+        const reflEntry = { engine: "raw", model: "gemma3:4b" };
+        const routing = { reflection: reflEntry, default: defaultEntry };
+        const result = resolveEngineConfig(routing, "reflection");
+        assert.deepEqual(result, reflEntry);
+    });
+});
+// ---------------------------------------------------------------------------
+// downgradeForRetry
+// ---------------------------------------------------------------------------
+describe("downgradeForRetry", () => {
+    const origins = ["user_manual", "self_cycle", "platform", "retry", "reflection"];
+    it("always returns 'retry' regardless of input", () => {
+        for (const origin of origins) {
+            assert.equal(downgradeForRetry(origin), "retry", `downgradeForRetry(${origin}) should be 'retry'`);
+        }
+    });
+    it("user_manual + isRetry=true → 'retry' (not user_manual)", () => {
+        // This is the spec's explicit test case for the downgrade rule
+        const original = "user_manual";
+        const downgraded = downgradeForRetry(original);
+        assert.equal(downgraded, "retry");
+        assert.notEqual(downgraded, "user_manual");
+    });
+});
+// ---------------------------------------------------------------------------
+// deriveChildOrigin
+// ---------------------------------------------------------------------------
+describe("deriveChildOrigin", () => {
+    const origins = ["user_manual", "self_cycle", "platform", "retry", "reflection"];
+    it("always returns 'platform' regardless of parent", () => {
+        for (const origin of origins) {
+            assert.equal(deriveChildOrigin(origin), "platform", `deriveChildOrigin(${origin}) should be 'platform'`);
+        }
+    });
+    it("user_manual parent does NOT propagate to child (anti-contamination rule)", () => {
+        const child = deriveChildOrigin("user_manual");
+        assert.equal(child, "platform");
+        assert.notEqual(child, "user_manual");
+    });
+    it("self_cycle parent → child is platform, not self_cycle", () => {
+        assert.equal(deriveChildOrigin("self_cycle"), "platform");
+    });
+});