@plurnk/plurnk-service 0.29.0 → 0.35.0

package/dist/core/Engine.js

@@ -5,6 +5,10 @@ import EntryCrud from "../schemes/_entry-crud.js";
 import EntryManifest from "../schemes/_entry-manifest.js";
 import GitMembership from "./git-membership.js";
 import GitState from "./git-state.js";
+import Fork from "./fork.js";
+import RunCap from "./run-cap.js";
+import SessionSettings from "./session-settings.js";
+import { decodePathParens } from "./path-decode.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
 import { LineMarkerOps, MimetypeBinary, editedSpan } from "../content/index.js";
 import { readFile } from "node:fs/promises";
@@ -59,14 +63,12 @@ const readMaxCommands = () => {
 };
 // PLURNK_MANIFEST_ITEMS — the turn-0 manifest preview. null = off (no foist);
 // -1 = the full manifest; positive N = the first N items. 0 / unset = off.
+const normalizeManifestItems = (n) => (!Number.isFinite(n) || n === 0 ? null : n < 0 ? -1 : n);
 const readManifestItems = () => {
     const raw = process.env.PLURNK_MANIFEST_ITEMS;
     if (raw === undefined || raw.length === 0)
         return null;
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n === 0)
-        return null;
-    return n < 0 ? -1 : n;
+    return normalizeManifestItems(Number.parseInt(raw, 10));
 };
 // Resolution timeout — proposed entries auto-cancel if nothing arrives
 // within this window. SPEC.md §engine-rails (proposal lifecycle) + §methods (loop.resolve).
@@ -81,16 +83,16 @@ const readProposalTimeoutMs = () => {
     return n;
 };
 const pathnameFromPath = (path) => {
-    if (path.kind === "url")
-        return path.pathname;
-    return path.raw;
+    if (path.kind === "regex")
+        return path.raw; // regex source — parens are syntax, never encoded
+    return decodePathParens(path.kind === "url" ? path.pathname : path.raw); // #239 item 4
 };
 // Default turn.status when ops were emitted but no SEND. Model is implicitly
 // continuing; loop.status stays 102 either way (only SEND broadcast advances
 // loop terminal). No strike, no telemetry.
 const TURN_STATUS_IMPLICIT_CONTINUE = 102;
 // Status assigned to a turn that emitted NO ops at all. Strike-worthy; the
-// action routes through telemetry.errors[] (§telemetry).
+// action routes through telemetry.errors[] (§telemetry, §telemetry-no-error-scheme — never an error:// scheme).
 const TURN_STATUS_NO_OPS = 422;
 // Rail #38: action-entry statuses that DON'T accumulate strikes. Model adapted
 // to a finding (not_found, op_not_supported); no penalty. Rummy parallel:
@@ -127,7 +129,7 @@ const fingerprintOp = (stmt) => {
         }
         const lm = stmt.lineMarker;
         if (lm !== null && lm !== undefined)
-            parts.push(`L:${lm.first},${lm.last ?? ""}`);
+            parts.push(`L:${lm.marks.join(",")}`);
         return parts.length > 0 ? `|${parts.join("|")}` : "";
     };
     if (path === null) {
@@ -239,6 +241,8 @@ class Engine {
     #loopAborts = new Map();
     #streamEventNotify;
     #wakeRunNotify;
+    #injectRun;
+    #cancelRun;
     // Telemetry event fan-out: every TelemetryEvent pushed to the loop's
     // buffer is also broadcast live to the connected client(s) on the
     // session. Without this, the client sees `loop/terminated` with a
@@ -247,11 +251,13 @@ class Engine {
     #telemetryEventNotify;
     // Cached plurnk GBNF — read once on the first constrained generate (#189).
     #gbnfCache = null;
-    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, telemetryEventNotify, tokenize }) {
+    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, injectRun, cancelRun, telemetryEventNotify, tokenize }) {
         this.#db = db;
         this.#schemes = schemes;
         this.#streamEventNotify = streamEventNotify;
         this.#wakeRunNotify = wakeRunNotify;
+        this.#injectRun = injectRun;
+        this.#cancelRun = cancelRun;
         this.#telemetryEventNotify = telemetryEventNotify;
         // Default to empty discovery — standalone Engine construction (in
         // tests) gets no handlers, and content flows through the framework's
@@ -315,6 +321,7 @@ class Engine {
         // both sides per the grammar 0.17.0 TelemetryEvent protocol.
         this.#telemetryEventNotify?.(sessionId, { loopId, event });
     }
+    // Telemetry drains as it's read into the packet — each event surfaces once. §telemetry-drain-on-read
     #drainTelemetry(loopId) {
         const buf = this.#telemetryBuffer.get(loopId);
         if (buf === undefined)
@@ -343,7 +350,7 @@ class Engine {
         }
         return slice.join("\n");
     }
-    async runLoop({ provider, messages, persona = "", requirements = "", sessionId, runId, loopId, maxTurns = 50, maxStrikes = readMaxStrikes(), minCycles = readPositiveInt("PLURNK_MIN_CYCLES", DEFAULT_MIN_CYCLES), maxCyclePeriod = readPositiveInt("PLURNK_MAX_CYCLE_PERIOD", DEFAULT_MAX_CYCLE_PERIOD), origin = "model", signal, onDispatch, }) {
+    async runLoop({ provider, messages, requirements = "", sessionId, runId, loopId, maxTurns = 50, maxStrikes = readMaxStrikes(), minCycles = readPositiveInt("PLURNK_MIN_CYCLES", DEFAULT_MIN_CYCLES), maxCyclePeriod = readPositiveInt("PLURNK_MAX_CYCLE_PERIOD", DEFAULT_MAX_CYCLE_PERIOD), origin = "model", signal, onDispatch, }) {
         const turnIds = [];
         const suddenDeathThreshold = maxTurns - maxStrikes;
         // Per-loop AbortController for scheme-side cancellation propagation.
@@ -385,7 +392,7 @@ class Engine {
                 return { turnIds, finalStatus: row.status, hitMaxTurns: false, reason: "external" };
             }
             if (maxTurns >= 0 && turnIds.length >= maxTurns) {
-                await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "max_turns" });
                 cleanup("forceful", "max_turns");
                 return { turnIds, finalStatus: 499, hitMaxTurns: true, reason: "max_turns" };
             }
@@ -400,13 +407,13 @@ class Engine {
                     await delay(execWaitMs, undefined, { signal });
             }
             const turn = await this.runTurn({
-                provider, messages, persona, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
+                provider, messages, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
                 turnNumber: turnIds.length + 1, maxTurns,
             });
             turnIds.push(turn.turnId);
             // SPEC §grinder: budget hard-stop — packet won't fit even collapsed → abandon.
             if (turn.budgetHardStop) {
-                await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "budget_overflow" });
                 cleanup("forceful", "budget_overflow");
                 return { turnIds, finalStatus: 499, hitMaxTurns: false, reason: "budget_overflow" };
             }
@@ -425,7 +432,7 @@ class Engine {
                 state.turnErrors++;
             // SPEC §grinder: a non-soft grinder fire counts toward the strike streak.
             if (turn.budgetStruck)
-                state.turnErrors++;
+                state.turnErrors++; // a grinder fire bumps the strike streak — §grinder-strike-coupling
             this.#strikeState.set(loopId, state);
             // Rail #38: strike accounting. Three sources strike a turn:
             //  1. recordedFailed — any action-entry at hard failure status
@@ -447,7 +454,7 @@ class Engine {
             if (struck) {
                 state.streak++;
                 if (state.streak >= maxStrikes) {
-                    await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                    await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "strike_threshold" });
                     cleanup("forceful", "strike_threshold");
                     return { turnIds, finalStatus: 499, hitMaxTurns: false, reason: "strike_threshold" };
                 }
@@ -465,7 +472,7 @@ class Engine {
             }
         }
     }
-    async runTurn({ provider, messages, persona = "", requirements = "", sessionId, runId, loopId, origin = "model", signal, onDispatch, turnNumber = 1, maxTurns = 50, }) {
+    async runTurn({ provider, messages, requirements = "", sessionId, runId, loopId, origin = "model", signal, onDispatch, turnNumber = 1, maxTurns = 50, }) {
         // === Turn-as-container model ===
         //
         // Turn rows are created at runTurn OPEN (status=102, placeholder
@@ -497,12 +504,15 @@ class Engine {
         // otherwise.
         let nextActionIndex = 1;
         if (seq === 1) {
-            // Operator doc READs (PLURNK_MD_<ALIAS>). The docs were materialized
+            // Operator doc READs (PLURNK_MD_<ALIAS>, §actor-boundary-doc-injection). The docs were materialized
             // as plurnk:///<entry> entries by the plurnk run (loop_run, via the
             // §actor-boundary keystone); foist a READ of each into THIS turn-0 so the model
             // reads them inline. It sees only the READ — the materializing EDIT
             // lives in the plurnk run's log, never the model's.
-            for (const doc of Paths.docs()) {
+            // #231 — env docs (PLURNK_MD_*) UNION the session's client docs; foist a READ of
+            // each materialized plurnk:///<alias>.md (loop_run materialized the same set).
+            const { mdDocs } = await SessionSettings.read(this.#db, sessionId);
+            for (const doc of await SessionSettings.resolveDocs(mdDocs)) {
                 const docTarget = {
                     kind: "url", raw: `plurnk:///${doc.entryName}`, scheme: "plurnk",
                     username: null, password: null, hostname: null, port: null,
@@ -531,10 +541,17 @@ class Engine {
                     target: promptPath, lineMarker: null,
                     body: promptRow.prompt, position: { line: 1, column: 1 },
                 };
+                let promptLogId;
                 await this.dispatch({
                     statement: promptStmt, sessionId, runId, loopId, turnId,
-                    sequence: nextActionIndex, origin: "plurnk", onDispatch,
+                    sequence: nextActionIndex, origin: "plurnk",
+                    onDispatch: (id) => { promptLogId = id; onDispatch?.(id); },
                 });
+                // §prompt-fold (User Note 6): the prompt EDIT duplicates
+                // packet.user.prompt (its own section), so fold it — logged for
+                // forensics, collapsed in the model's log, re-OPENable.
+                if (promptLogId !== undefined)
+                    await this.#db.engine_fold_log_entry.run({ id: promptLogId });
                 nextActionIndex++;
             }
         }
@@ -573,7 +590,9 @@ class Engine {
         // manifest is JSON); off by default. AFTER the manifest write so the READ hits
         // it, not a 404; same plurnk-origin foist as the operator docs.
         if (seq === 1) {
-            const manifestItems = readManifestItems();
+            // #231 — a session's client-chosen manifestItems REPLACES the env default outright.
+            const { manifestItems: sessionMI } = await SessionSettings.read(this.#db, sessionId);
+            const manifestItems = sessionMI !== null ? normalizeManifestItems(sessionMI) : readManifestItems();
             if (manifestItems !== null) {
                 const manifestRead = {
                     op: "READ", suffix: "", signal: null, lineMarker: null,
@@ -604,14 +623,14 @@ class Engine {
         // queries log_entries scoped to the run — the prompt entry just
         // written (if turn 1) is part of that query result.
         let requestPacket = await this.#buildRequestPacket({
-            initialMessages: messages, persona, requirements, runId, loopId,
+            initialMessages: messages, requirements, runId, loopId,
             currentTurnSeq: seq, provider, gitStatus,
         });
         // SPEC §grinder — budget grinder, pre-LLM: reclaim window on actual overflow.
         const enforced = await this.#enforceBudget({
             packet: requestPacket, provider, runId, loopId, turnId, sessionId, turnNumber,
             rebuild: (telemetryErrors) => this.#buildRequestPacket({
-                initialMessages: messages, persona, requirements, runId, loopId,
+                initialMessages: messages, requirements, runId, loopId,
                 currentTurnSeq: seq, provider, telemetryErrors, gitStatus,
             }),
         });
@@ -632,14 +651,14 @@ class Engine {
         // The 0.28.0 EOS-forcing root terminates the turn at the status SEND, but a
         // grammar can't bound degeneration *inside* a statement body — this caps the
         // decode at the free window so a runaway can't reach the context wall.
-        const genCeiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
+        const genCeiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling); // provider.contextSize, the immutable identity, read by the budget — §provider-surface-identity
         const maxTokens = genCeiling === null ? undefined : Math.max(1, genCeiling - requestPacket.system.tokens - requestPacket.user.tokens);
-        const response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens });
+        const response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired
         // Engine splits wire-level response: emission (content, reasoning,
         // parsed ops) → packet.assistant per Packet.json §assistant;
         // call-metadata (usage, finishReason, model) → Turn columns per
         // Turn.json. Mixing the two on packet.assistant was the wrong layer.
-        const { packetAssistant, callMetadata, parseErrors } = this.#splitResponse(response);
+        const { packetAssistant, callMetadata, parseErrors } = this.#splitResponse(response); // raw assistant content is opaque — split, never interpreted — §provider-guarantees-assistantraw-opaque
         // Surface parse errors to the model's NEXT packet so it can self-
         // correct. Without this, malformed emissions (e.g. a READ matcher
         // body starting with `//` being interpreted as xpath) silently
@@ -685,7 +704,7 @@ class Engine {
             usage_prompt: usage.prompt,
             usage_completion: usage.completion,
             usage_cached: usage.cached,
-            usage_cost_pico: provider.costFor(usage),
+            usage_cost_pico: provider.costFor(usage), // §provider-surface-costfor
             finish_reason: finishReason,
             model,
         });
@@ -699,7 +718,8 @@ class Engine {
         // entries (avoids bloating forensics with hundreds of identical refusals)
         // and the model gets a single telemetry signal next packet so it knows
         // its emission was truncated.
-        const maxCommands = readMaxCommands();
+        // #232 — a session's maxCommands is a tighten-only ceiling: min() the env ceiling.
+        const maxCommands = Math.min(readMaxCommands(), (await SessionSettings.read(this.#db, sessionId)).maxCommands ?? Number.POSITIVE_INFINITY);
         const opsToDispatch = packetAssistant.ops.slice(0, maxCommands);
         const droppedCount = opsCount - opsToDispatch.length;
         const statuses = [];
@@ -820,9 +840,12 @@ class Engine {
     // and §user) BEFORE the provider call. The same packet object is then
     // completed with assistant + assistantRaw after the model responds, so
     // the stored packet and the wire payload share one source of truth.
-    async #buildRequestPacket({ initialMessages, persona: defaultPersona, requirements, runId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
+    async #buildRequestPacket({ initialMessages, requirements, runId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
-        const system_definition = byRole("system");
+        // plurnk.md (grammar/dialects) THEN the scheme catalogue: grammar 0.49+ is
+        // scheme-agnostic, so the service teaches what schemes exist + what they do
+        // at packet-time (grammar#239 item 7). SchemeRegistry.teach() assembles it.
+        const system_definition = `${byRole("system")}\n\n${this.#schemes.teach()}`;
         // user.prompt sources from the loop's most recent prompt entry first
         // (plurnk:///prompt/<loop_id>/<N> for the highest N written to date).
         // This is what inject + the turn-1 foist write into. Falls back to
@@ -832,13 +855,8 @@ class Engine {
         const prompt = (latestPromptRow !== undefined && typeof latestPromptRow.content === "string" && latestPromptRow.content.length > 0)
             ? latestPromptRow.content
             : byRole("user");
-        // Resolve persona cascade: loops.persona > runs.persona >
-        // sessions.persona > caller-supplied default. SQL coalesces in one
-        // query; null result means no DB override exists, use the default.
-        const row = await this.#db.engine_resolve_persona.get({ loop_id: loopId });
-        const persona = (row?.persona !== undefined && row?.persona !== null) ? row.persona : defaultPersona;
         // Requirements is engine-sourced, NOT threaded from callers — that threading is
-        // exactly how it went missing (loop_run/Daemon read sysprompt + persona but never
+        // exactly how it went missing (callers read the sysprompt but never the
         // requirements). Read Paths.defaultRequirements (PLURNK_REQUIREMENTS env →
         // requirements.md) fresh each build so edits take effect; a non-empty param wins.
         const requirementsText = requirements.length > 0 ? requirements : await readFile(Paths.defaultRequirements, "utf8");
@@ -849,7 +867,7 @@ class Engine {
         // form — wire-payload tokens may differ slightly because chat-
         // template scaffolding adds bytes, but the subtotal tracks "what
         // the model has to process" closely enough for budget diagnostics.
-        const countTokens = (t) => provider.countTokens(t);
+        const countTokens = (t) => provider.countTokens(t); // §provider-surface-counttokens
         // Budget readout (SPEC.md §tokenomics). Two-pass: measure the wire-rendered
         // index/log sections (budget-independent), install the readout with a
         // tokensFree placeholder, measure the assembled total, resolve free,
@@ -859,21 +877,21 @@ class Engine {
         // headline omitted, section lines still shown).
         const ceiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
         const scratch = {
-            system: { system_definition, persona, log },
+            system: { system_definition, log },
             user: { prompt, telemetry: { budget: "", errors: telemetryErrors, git: gitStatus }, tools: this.#collectTools(), system_requirements: requirementsText },
         };
         const sections = PacketWire.measureBudgetSections(scratch, countTokens);
         scratch.user.telemetry.budget = this.#renderBudget(sections, ceiling);
         const total = countTokens(PacketWire.renderSystemContent(scratch.system)) + countTokens(PacketWire.renderUserContent(scratch.user));
-        const tokensFree = ceiling === null ? null : Math.max(0, ceiling - total);
-        const percent = ceiling === null ? null : Math.round((total / ceiling) * 100);
+        const tokensFree = ceiling === null ? null : Math.max(0, ceiling - total); // free floors at 0 on overshoot — §tokenomics-over-budget-floor
+        const percent = ceiling === null ? null : Math.round((total / ceiling) * 100); // usage as % of the ceiling — §tokenomics-context-percent
         const budget = tokensFree === null
             ? scratch.user.telemetry.budget
             : scratch.user.telemetry.budget
                 .replace(TOKEN_USAGE_PLACEHOLDER, String(total))
                 .replace(TOKEN_PERCENT_PLACEHOLDER, String(percent))
                 .replace(TOKENS_FREE_PLACEHOLDER, String(tokensFree));
-        const system = { tokens: 0, system_definition, persona, log };
+        const system = { tokens: 0, system_definition, log };
         const user = { tokens: 0, prompt, telemetry: { budget, errors: telemetryErrors, git: gitStatus }, tools: scratch.user.tools, system_requirements: requirementsText };
         system.tokens = countTokens(PacketWire.renderSystemContent(system));
         user.tokens = countTokens(PacketWire.renderUserContent(user));
@@ -896,10 +914,12 @@ class Engine {
                 for (const t of sections.log.byTurn)
                     lines.push(`| ${t.turn} | ${t.tokens} |`);
             }
-            // The heaviest individual entries — the FOLD targets behind the
-            // weight (§tokenomics {§tokenomics-largest-entries}).
+            // The heaviest individual log items — the FOLD targets behind the weight
+            // (§tokenomics {§tokenomics-largest-entries}). "items", not "entries": the readout
+            // lists log:/// rows (log items), distinct from catalog entries (plurnk.md: "EDIT
+            // is only for entries. Do not attempt to edit log items.").
             if (sections.log.largest.length > 0) {
-                lines.push("Heaviest entries:", "| entry | tokens |", "|---|--:|");
+                lines.push("Heaviest items:", "| item | tokens |", "|---|--:|");
                 for (const e of sections.log.largest)
                     lines.push(`| ${e.path} | ${e.tokens} |`);
             }
@@ -912,10 +932,11 @@ class Engine {
     // contributor (gated by PLURNK_PLAN); each available executor tag then
     // contributes its self-documenting example (plurnk-execs#7), retiring the
     // blind EXEC.
+    // The capability sheet — the live tool surface (PLAN + wired executor tags). §tools-capability-sheet
     #collectTools() {
         const tools = [];
-        if (process.env.PLURNK_PLAN === "1") {
-            tools.push("* Begin every response with <<PLAN:planning and reasoning:PLAN");
+        if (process.env.PLURNK_PLAN === "1") { // <<PLAN advertised only when PLAN is enabled — §tools-plan-gated
+            tools.push("* Begin every response with <<PLAN:...:PLAN");
         }
         // Each available runtime tag contributes its self-documenting example —
         // the example carries syntax + purpose, so there's no prose line. Tags
@@ -925,18 +946,37 @@ class Engine {
         // no backticks — see packet-wire.ts).
         if (this.#executors !== undefined) {
             for (const tag of this.#executors.availableRuntimes()) {
-                const example = this.#executors.entry(tag)?.example;
-                if (example)
-                    tools.push(`* ${example}`);
+                const entry = this.#executors.entry(tag);
+                if (entry?.example)
+                    tools.push(`* ${entry.example}`);
+                // #note12 — link the executor's fuller doc (materialized at plurnk:///docs/<tag>);
+                // its token cost rides that manifest entry, so no inline recount here.
+                if (entry?.documentation)
+                    tools.push(`* docs for ${tag}: plurnk:///docs/${tag}`);
             }
         }
         return tools;
     }
+    // #note12 — the daughter-provided reference docs (schemes' + execs' `documentation`),
+    // materialized at plurnk:///docs/<name> by loop_run (like operator docs) so the
+    // catalogue's doc-links READ and the manifest carries each doc's token cost.
+    docEntries() {
+        const out = this.#schemes.docs();
+        if (this.#executors !== undefined) {
+            for (const tag of this.#executors.availableRuntimes()) {
+                const doc = this.#executors.entry(tag)?.documentation;
+                if (doc !== undefined && doc.length > 0)
+                    out.push({ name: tag, content: doc });
+            }
+        }
+        return out;
+    }
     // SPEC §grinder — the budget grinder. Runs pre-LLM (in runTurn, after the packet
     // is built, before provider.generate); fires only on actual overflow. Two
     // passes, re-measuring between. Folds (never deletes) — the prior turn's logs,
     // then the catalog except the manifest lifeline. The strike it raises and the
     // hard-stop it can signal are returned to runLoop, which owns abandonment.
+    // §grinder-overflow-only — fires only on actual overflow, never speculatively
     async #enforceBudget({ packet, provider, runId, loopId, turnId, sessionId, turnNumber, rebuild }) {
         const ceiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling);
         const measure = (p) => p.system.tokens + p.user.tokens;
@@ -946,7 +986,7 @@ class Engine {
         const note = (scheme) => { folded.set(scheme, (folded.get(scheme) ?? 0) + 1); };
         // Pass 1 — prior-turn rollback: fold the latest emissions (the ones that
         // pushed it over). No prior turn (turn 1, env overflow) → no-op → pass 2.
-        const priorLogs = await this.#db.engine_grinder_prior_turn_logs.all({ loop_id: loopId, turn_id: turnId });
+        const priorLogs = await this.#db.engine_grinder_prior_turn_logs.all({ loop_id: loopId, turn_id: turnId }); // prior-turn rollback folds the latest emissions — §grinder-layer1-rollback
         for (const le of priorLogs)
             note(le.scheme ?? "log");
         if (priorLogs.length > 0)
@@ -955,17 +995,18 @@ class Engine {
         let current = priorLogs.length > 0 ? await rebuild(errors) : packet;
         if (measure(current) <= ceiling) {
             this.#emitBudgetOverflow(sessionId, loopId, folded);
-            return { packet: current, fit: true, struck: turnNumber > 1 };
+            return { packet: current, fit: true, struck: turnNumber > 1 }; // turn 0/1 overflow is the environment, never a strike — §grinder-soft-turn-0-1
         }
         // Prior-turn rollback is the only budget lever now: entries don't render
         // (no index), so there is no catalog to collapse. If pass 1 didn't fit,
-        // the packet is over and the caller hard-413s.
+        // the packet is over and the caller hard-413s. §grinder-hard-413-abort
         this.#emitBudgetOverflow(sessionId, loopId, folded);
         return { packet: current, fit: measure(current) <= ceiling, struck: turnNumber > 1 };
     }
     // The model-facing budget event (SPEC §grinder, §telemetry): which entries left the
     // window, by scheme — the model's own terms, no mechanism vocabulary. The
     // strike this overflow triggers stays engine-internal (gamification policy).
+    // §grinder-event-model-terms — model-facing terms only; the strike stays engine-internal
     #emitBudgetOverflow(sessionId, loopId, folded) {
         if (folded.size === 0)
             return;
@@ -1061,7 +1102,7 @@ class Engine {
             source: r.source,
         }));
     }
-    // §env-delta — at pre-turn build, surface what changed in the shared world since this
+    // §env-delta (§actor-boundary-no-mutex: runs share without locks; a conflict surfaces as a delta, never prevented) — at pre-turn build, surface what changed in the shared world since this
     // run last looked. No per-run snapshot (§machine-processes "a run is its log"): every
     // edit is already a span-carrying log row, so PULL other actors' EDITs on shared
     // entries since this run's prior turn — real cross-run edits and the plurnk run's
@@ -1084,6 +1125,19 @@ class Engine {
             });
             written++;
         }
+        // §run-scheme — loop-terminations: a sibling's loop reaching terminal surfaces the
+        // same way an entry-change does, carrying its deliverable (the SEND body) or the
+        // abandonment reason. Folded, attributed to the terminated run.
+        const terms = await this.#db.engine_pull_loop_terminations.all({ session_id: sessionId, run_id: runId, since });
+        for (const t of terms) {
+            await this.#db.engine_insert_loop_termination_delta.run({
+                run_id: runId, loop_id: loopId, turn_id: turnId, sequence: fromSequence + written,
+                source: String(t.run_id), pathname: `/${t.run_name}`,
+                rx: t.terminal_message ?? `loop "${t.prompt}" ended (${t.status})`,
+                status: t.status,
+            });
+            written++;
+        }
         return written;
     }
     // §env-delta — the filesystem as an actor. Ambient disk divergences detected at
@@ -1092,11 +1146,12 @@ class Engine {
     // world changed," so the fiction keeps its perspective aligned with what its tooling
     // would show. The fiction lives in the plurnk run's log; every other run pulls it
     // through the one delta path, exactly like a sibling's real edit.
+    // §membership-emi-divergence-signal — disk divergences logged as the plurnk run's source=file EDIT fictions
     async #logFsFictions(sessionId, divergences) {
         if (divergences.length === 0)
             return;
         const run = await this.#db.envelope_get_run_by_name.get({ session_id: sessionId, name: "plurnk" })
-            ?? await this.#db.envelope_insert_run.get({ session_id: sessionId, name: "plurnk", persona: null, origin: "plurnk" });
+            ?? await this.#db.envelope_insert_run.get({ session_id: sessionId, name: "plurnk", origin: "plurnk" });
         if (run === undefined)
             throw new Error("logFsFictions: plurnk run resolution returned no row");
         const loop = await this.#db.envelope_insert_client_loop.get({ run_id: run.id });
@@ -1129,6 +1184,7 @@ class Engine {
             signal: this.#loopAborts.get(loopId)?.signal,
             streamEventNotify: this.#streamEventNotify,
             wakeRunNotify: this.#wakeRunNotify,
+            injectRun: this.#injectRun,
             mimetypes: this.#mimetypes,
             tokenize: this.#tokenize,
             pushTelemetry: (event) => this.#pushTelemetry(sessionId, loopId, event),
@@ -1171,10 +1227,10 @@ class Engine {
                     result = await this.#run("exec", statement, schemeCtx);
                 }
                 else {
-                    result = await this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx);
+                    result = await this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx); // §op-methods-op-dispatch
                 }
             }
-            catch (err) {
+            catch (err) { // a scheme exception becomes the op's 500 outcome — §scheme-surface-exception-500
                 result = {
                     status: 500,
                     error: err instanceof Error ? err.message : String(err),
@@ -1183,7 +1239,7 @@ class Engine {
         }
         const logEntryId = await this.#writeLog({ statement, result, runId, loopId, turnId, sequence, origin });
         onDispatch?.(logEntryId);
-        // Proposal lifecycle (SPEC.md §engine-rails + §methods loop.resolve). When a
+        // Proposal lifecycle (SPEC.md §engine-rails + §methods loop.resolve; §proposal-202-pauses). When a
         // scheme returns status 202, the entry is written as state='proposed';
         // dispatch then PAUSES on a per-entry waiter until resolution
         // arrives via Engine.resolveProposal (from the loop/resolve RPC,
@@ -1208,7 +1264,10 @@ class Engine {
             // YOLO listener auto-resolves) BEFORE awaiting — they may
             // resolve synchronously inside their handlers.
             const target = this.#extractTarget(statement.target);
-            const flags = await this.#loadLoopFlags(loopId);
+            const flags = await this.#loadLoopFlags(loopId); // the loop/proposal notification carries flags (yolo) — §dual-yolo-proposal-carries-flags
+            // #note10 — if the target diverged on disk this turn, the model's EDIT is based
+            // on a stale read; flag it so a YOLO auto-accept rejects instead of clobbering.
+            const diverged = await this.#db.engine_target_diverged_this_turn.get({ run_id: runId, turn_id: turnId, scheme: target.scheme, pathname: target.pathname });
             const event = {
                 logEntryId, sessionId, runId, loopId, turnId,
                 op: statement.op,
@@ -1216,6 +1275,7 @@ class Engine {
                 body: typeof result.body === "string" ? result.body : "",
                 attrs: (result.attrs ?? {}),
                 flags,
+                staleClobberRisk: diverged !== undefined,
             };
             for (const listener of this.#proposalPendingListeners) {
                 try {
@@ -1245,6 +1305,7 @@ class Engine {
         }
         return result;
     }
+    // On accept, run the scheme's applyResolution — File writes disk, Exec spawns. §proposal-accept-applies
     async #runApplyResolution(statement, originalResult, resolution, ids) {
         const { sessionId, runId, loopId, turnId } = ids;
         if (resolution.decision !== "accept")
@@ -1406,7 +1467,7 @@ class Engine {
                 // transitions to cancelled with outcome='timeout'.
                 if (this.#pendingProposals.has(logEntryId)) {
                     this.#pendingProposals.delete(logEntryId);
-                    resolve({ decision: "cancel", outcome: "timeout" });
+                    resolve({ decision: "cancel", outcome: "timeout" }); // §proposal-timeout-cancels
                 }
             }, timeoutMs);
             this.#pendingProposals.set(logEntryId, { resolve, timeoutHandle });
@@ -1415,8 +1476,8 @@ class Engine {
     async #applyResolution(logEntryId, resolution) {
         // Map decision → terminal state + HTTP-aligned status:
         //   accept  → state='resolved', status=200
-        //   reject  → state='failed',   status=400, outcome='rejected' (default)
-        //   cancel  → state='cancelled',status=499, outcome='loop_aborted' (default)
+        //   reject  → state='failed',   status=400, outcome='rejected' (default) §proposal-reject-fails
+        //   cancel  → state='cancelled',status=499, outcome='loop_aborted' (default) §proposal-cancel-aborts
         // resolution.outcome wins over the default when supplied; this is how
         // veto filters (Phase E.2 proposal.accepting) can specify a more
         // precise outcome string like 'policy_veto' or 'timeout'.
@@ -1462,6 +1523,11 @@ class Engine {
         if (statement.op === "EXEC") {
             return this.#denyIfDisallowed("exec", origin);
         }
+        // A run-fork (COPY src=run://) is gated by run://'s writableBy — its body
+        // is a fork prompt, not a dst path, so the entry-COPY dst-parse below
+        // doesn't apply. §machine-processes
+        if (this.#isRunFork(statement))
+            return this.#denyIfDisallowed("run", origin);
         if (statement.op === "COPY" || statement.op === "MOVE") {
             const dst = statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body;
             const dstScheme = this.#schemeNameOf(dst);
@@ -1492,7 +1558,7 @@ class Engine {
             return null;
         if (manifest.writableBy.includes(origin))
             return null;
-        return { status: 403, error: `writer '${origin}' is not in writableBy for scheme '${schemeName}'` };
+        return { status: 403, error: `writer '${origin}' is not in writableBy for scheme '${schemeName}'` }; // §scheme-surface-writableby-403
     }
     // Per-loop flag gating. Schemes self-declare their flag affinity in
     // their manifest (excludedInAsk / requiresWeb /
@@ -1516,14 +1582,50 @@ class Engine {
                 return null;
             return { status: 403, error: `scheme '${scheme}' is inactive under current loop flags` };
         };
+        if (this.#isRunFork(statement))
+            return check(statement.target); // body is a fork prompt, not a dst path
         if (statement.op === "COPY" || statement.op === "MOVE") {
             return check(statement.target) ?? check(statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body);
         }
         return check(statement.target);
     }
+    // A COPY whose SOURCE is run:// is a run-fork, not an entry-copy — its body
+    // is the fork's seed prompt, not a destination path. The COPY gates and
+    // #handleCopy branch on this so they never parse the prompt as a dst path.
+    #isRunFork(statement) {
+        return statement.op === "COPY" && this.#schemeNameOf(statement.target) === "run";
+    }
+    // COPY(run:///<src>):prompt — fork: deep-copy the source run's log into a new
+    // run (Fork), then start it with the prompt (ctx.injectRun). Source "."/"" =
+    // self (ctx.runId); a name resolves within the session (404 if absent).
+    // §machine-processes-fork-copies-the-log
+    async #handleRunFork(statement, ctx) {
+        const target = statement.target;
+        if (target === null)
+            return { status: 400, error: "run:// fork requires a source run" };
+        const name = pathnameFromPath(target).replace(/^\/+/, "");
+        let srcRunId = ctx.runId;
+        if (name !== "" && name !== ".") {
+            const row = await this.#db.run_resolve_by_name.get({ session_id: ctx.sessionId, name });
+            if (row === undefined)
+                return { status: 404, error: `run:///${name} not found in this session` };
+            srcRunId = row.id;
+        }
+        if (ctx.injectRun === undefined)
+            throw new Error("run fork: injectRun capability absent");
+        const denied = await RunCap.deny(this.#db, ctx.sessionId);
+        if (denied !== null)
+            return denied;
+        const branchRunId = await Fork.fork(this.#db, srcRunId);
+        const branch = await this.#db.fork_get_run.get({ id: branchRunId });
+        await ctx.injectRun({ sessionId: ctx.sessionId, runId: branchRunId, prompt: typeof statement.body === "string" ? statement.body : "" });
+        return { status: 200, body: branch?.name ?? "" };
+    }
     async #handleCopy(statement, ctx) {
         if (statement.op !== "COPY")
             throw new Error("unreachable");
+        if (this.#isRunFork(statement))
+            return await this.#handleRunFork(statement, ctx);
         const srcPath = statement.target;
         // COPY's body is an opaque raw string (grammar §COPY: a dest path OR a run-fork
         // prompt); parse it to the dest path. Non-path bodies (run:// fork prompts) are
@@ -1542,17 +1644,17 @@ class Engine {
         const dstPath = statement.body;
         if (srcPath === null)
             return { status: 400, error: "MOVE requires source path" };
-        // MOVE is relocation only — deletion is KILL's job (§move). The /dev/null
+        // MOVE is relocation only — deletion is KILL's job (§move, §move-dev-null-not-special). The /dev/null
         // and null-body delete-by-MOVE back-compat is retired: no silent debt.
         if (dstPath === null)
-            return { status: 400, error: "MOVE requires a destination; use KILL to delete" };
+            return { status: 400, error: "MOVE requires a destination; use KILL to delete" }; // §move-null-body-400
         const srcSchemeName = this.#schemeNameOf(srcPath);
         if (srcSchemeName === null)
             return { status: 400, error: "MOVE source must be a URL path with a scheme" };
         const srcHandler = this.#schemes.get(srcSchemeName);
         if (srcHandler === undefined || typeof srcHandler.deleteEntry !== "function")
             return { status: 501 };
-        // Relocation: COPY then DELETE source.
+        // Relocation: COPY then DELETE source (§move-relocation-deletes-source).
         const copyResult = await this.#copyOrchestration({ statement, srcPath, dstPath, ctx });
         if (copyResult.status >= 400)
             return copyResult;
@@ -1595,6 +1697,23 @@ class Engine {
                 return { status: 501 };
             return await execHandler.kill(pathnameFromPath(path), ctx);
         }
+        if (schemeName === "run") {
+            // terminate — abort any run by address; whoever holds it may end it.
+            // `.`/"" = self. cancelRun (→ Daemon.cancelDrain) aborts the run's signal
+            // (its loop closes 499); an idle run is a no-op-200, a missing run 404.
+            const name = pathnameFromPath(path).replace(/^\/+/, "");
+            let runId = ctx.runId;
+            if (name !== "" && name !== ".") {
+                const row = await this.#db.run_resolve_by_name.get({ session_id: ctx.sessionId, name });
+                if (row === undefined)
+                    return { status: 404, error: `run:///${name} not found in this session` };
+                runId = row.id;
+            }
+            if (this.#cancelRun === undefined)
+                throw new Error("run kill: cancelRun capability absent");
+            this.#cancelRun(runId);
+            return { status: 200 };
+        }
         const handler = this.#schemes.get(schemeName);
         if (handler === undefined || typeof handler.deleteEntry !== "function")
             return { status: 501 };
@@ -1612,6 +1731,7 @@ class Engine {
             throw new Error("unreachable");
         return { status: 200 };
     }
+    // Same- and cross-scheme COPY share one orchestrator — §copy-cross-scheme-copy §move-cross-scheme-move
     async #copyOrchestration({ statement, srcPath, dstPath, ctx }) {
         const srcSchemeName = this.#schemeNameOf(srcPath);
         const dstSchemeName = this.#schemeNameOf(dstPath);
@@ -1627,7 +1747,7 @@ class Engine {
         const dstPathname = pathnameFromPath(dstPath);
         const srcResult = await srcHandler.readEntry(srcPathname, ctx);
         if (srcResult.status !== 200 || srcResult.entry === null)
-            return { status: 404, error: `COPY/MOVE source not found: ${srcSchemeName}://${srcPathname}` };
+            return { status: 404, error: `COPY/MOVE source not found: ${srcSchemeName}://${srcPathname}` }; // §copy-missing-source-404 §move-missing-source-404
         const entry = srcResult.entry;
         // Destination read — the conflict/no-op verdict is deferred until the
         // to-be-written content is known (after <L> slice + tag resolution below),
@@ -1641,7 +1761,7 @@ class Engine {
         for (const [channelName, channelData] of Object.entries(entry.channels)) {
             const expectedMimetype = dstChannels[channelName];
             if (expectedMimetype !== undefined && expectedMimetype !== channelData.mimetype) {
-                return { status: 415, error: `mimetype mismatch on channel '${channelName}': ${channelData.mimetype} vs ${expectedMimetype}` };
+                return { status: 415, error: `mimetype mismatch on channel '${channelName}': ${channelData.mimetype} vs ${expectedMimetype}` }; // cross-mimetype COPY/MOVE → 415, never coerce — §channel-mimetype-cross-mimetype-415
             }
         }
         // `<L>` source range slicing per SPEC.md §op-invariants (symmetric with READ
@@ -1663,7 +1783,7 @@ class Engine {
             }
             channels = sliced;
         }
-        // Tag resolution: signal = replace; absent/empty = carry from source
+        // Tag resolution: signal = replace (§copy-signal-replaces-source-tags); absent/empty = carry from source (§copy-no-signal-carries-source-tags)
         const tags = (Array.isArray(statement.signal) && statement.signal.length > 0)
             ? statement.signal
             : entry.tags;
@@ -1679,8 +1799,8 @@ class Engine {
                 && writeNames.every((n, i) => n === dstNames[i] && (channels[n]?.content ?? "") === (dstChannels[n]?.content ?? ""));
             const sameTags = [...tags].sort().join("") === [...dstExisting.entry.tags].sort().join("");
             if (sameContent && sameTags)
-                return { status: 304 };
-            return { status: 409, error: `COPY/MOVE destination exists: ${dstSchemeName}://${dstPathname}` };
+                return { status: 304 }; // identical → §copy-noop-304
+            return { status: 409, error: `COPY/MOVE destination exists: ${dstSchemeName}://${dstPathname}` }; // §copy-conflict-409
         }
         const writeResult = await dstHandler.writeEntry(dstPathname, { channels, tags }, ctx);
         // A file dest returns 202 (disk write → §membership review): propagate the
@@ -1696,7 +1816,10 @@ class Engine {
         if (status === null)
             return { status: 400 };
         if (status === 200 || status === 499) {
-            await this.#db.engine_loop_set_status.run({ status, loop_id: loopId });
+            // the loop's terminal message — its deliverable — rides the termination delta.
+            const body = statement.body;
+            const message = body === null ? null : typeof body === "string" ? body : body.raw;
+            await this.#db.engine_loop_set_status.run({ status, loop_id: loopId, message });
         }
         return { status };
     }
@@ -1817,12 +1940,15 @@ class Engine {
     #extractTarget(path) {
         if (path === null)
             return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: null, params: null, fragment: null };
+        // `local` (bare path) and `regex` (grammar 0.46 `#pattern#flags` target) carry no URL parts — store the raw text as the pathname for the log record, scheme=null.
+        if (path.kind === "regex")
+            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: path.raw, params: null, fragment: null }; // regex source — no decode
         if (path.kind === "local")
-            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: path.raw, params: null, fragment: null };
+            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: decodePathParens(path.raw), params: null, fragment: null }; // #239 item 4
         const scheme = path.scheme === "file" ? null : path.scheme;
         return {
             scheme, username: path.username, password: path.password,
-            hostname: path.hostname, port: path.port, pathname: path.pathname,
+            hostname: path.hostname, port: path.port, pathname: decodePathParens(path.pathname), // #239 item 4
             params: JSON.stringify(path.params), fragment: path.fragment,
         };
     }