@plurnk/plurnk-service 0.3.0 → 0.5.0

package/dist/core/Engine.js

@@ -1,15 +1,18 @@
-import { PlurnkParser } from "@plurnk/plurnk-grammar";
+import { PlurnkParser, PlurnkParseError } from "@plurnk/plurnk-grammar";
 import { Mimetypes, emptyRegistry } from "@plurnk/plurnk-mimetypes";
+import { writeEntry } from "../schemes/_entry-crud.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
+import { sliceLinesRaw, isBinaryMimetype } from "@plurnk/plurnk-schemes";
 // Plain JS module shared with bin/digest.js so wire projection and
 // digest projection are structurally one function. tsconfig.build.json
 // has allowJs:true so this gets copied through to dist/.
 import { packetToWireMessages } from "./packet-wire.js";
-// SCHEMES.md §8: writer must be in target scheme's manifest.writableBy.
+// SPEC §3.6: writer must be in target scheme's manifest.writableBy.
 // SHOW/HIDE/READ/FIND are not gated — they touch visibility metadata or read.
 const MUTATING_OPS = new Set(["EDIT", "SEND", "COPY", "MOVE", "EXEC"]);
 const DEFAULT_PREVIEW_BUDGET = 256;
 const DEFAULT_MAX_STRIKES = 3;
+const DEFAULT_MAX_COMMANDS = 99;
 const readBudget = () => {
     const raw = process.env.PLURNK_ENTRY_SIZE_DEFAULT_TOKENS;
     if (raw === undefined || raw.length === 0)
@@ -28,8 +31,17 @@ const readMaxStrikes = () => {
         return DEFAULT_MAX_STRIKES;
     return n;
 };
+const readMaxCommands = () => {
+    const raw = process.env.PLURNK_MAX_COMMANDS;
+    if (raw === undefined || raw.length === 0)
+        return DEFAULT_MAX_COMMANDS;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return DEFAULT_MAX_COMMANDS;
+    return n;
+};
 // Resolution timeout — proposed entries auto-cancel if nothing arrives
-// within this window. Per AGENTS.md §Phase E.2.
+// within this window. SPEC.md §0.5 (proposal lifecycle) + §13.5 (loop.resolve).
 const PROPOSAL_TIMEOUT_DEFAULT_MS = 300000;
 const readProposalTimeoutMs = () => {
     const raw = process.env.PLURNK_PROPOSAL_TIMEOUT_MS;
@@ -67,17 +79,57 @@ const readPositiveInt = (envVar, fallback) => {
         return fallback;
     return n;
 };
-// Per-op fingerprint: op verb + target URI. Body deliberately excluded so the
-// model writing varied content to the same target still trips. Path kind is
-// included as a discriminator (url vs local). Rummy parallel: scheme +
-// sorted attributes joined by '='.
+// Per-op fingerprint: op verb + target URI, plus an op-specific discriminator
+// where the activity isn't fully captured by target alone:
+//   - EDIT/COPY/MOVE: body excluded — re-writing the same target with varied
+//     content IS cycling (the model is producing different versions of the
+//     same artifact instead of progressing).
+//   - FIND/READ/SHOW/HIDE: body IS the search/selection pattern; varied
+//     matchers on the same target ARE different activities (the model is
+//     exploring different queries, not repeating one).
 const fingerprintOp = (stmt) => {
-    const path = stmt.path;
-    if (path === null)
+    const path = stmt.target;
+    const matcherDiscriminator = () => {
+        // For matcher-bearing ops, the body's `raw` (matcher source) plus
+        // any lineMarker forms the activity discriminator.
+        const parts = [];
+        const body = stmt.body;
+        if (body !== null && typeof body === "object" && typeof body.raw === "string") {
+            parts.push(`body:${body.raw.slice(0, 64)}`);
+        }
+        const lm = stmt.lineMarker;
+        if (lm !== null && lm !== undefined)
+            parts.push(`L:${lm.first},${lm.last ?? ""}`);
+        return parts.length > 0 ? `|${parts.join("|")}` : "";
+    };
+    if (path === null) {
+        // Path-less ops need an activity-defining discriminator other
+        // than `target`. Picked per op so the cycle detector reflects
+        // intent rather than syntax:
+        //   - EXEC: the command body IS the activity. Without a body
+        //     digest, varied shell commands (find / ls / wc) collapse to
+        //     one fingerprint and the detector mislabels exploration
+        //     as a loop.
+        //   - SEND: the status code (signal) IS the activity. Different
+        //     SEND[X] are different intentions; same SEND[X] with
+        //     different message bodies is the same termination signal.
+        if (stmt.op === "EXEC") {
+            const body = typeof stmt.body === "string" ? stmt.body : "";
+            return `EXEC|(no-path)${body.length > 0 ? `|body:${body.slice(0, 64)}` : ""}`;
+        }
+        if (stmt.op === "SEND") {
+            const signal = typeof stmt.signal === "number" ? stmt.signal : "";
+            return `SEND|(no-path)|signal:${signal}`;
+        }
         return `${stmt.op}|(no-path)`;
-    if (path.kind === "url")
-        return `${stmt.op}|${path.scheme}://${path.pathname}`;
-    return `${stmt.op}|local:${path.raw}`;
+    }
+    const base = path.kind === "url"
+        ? `${stmt.op}|${path.scheme}://${path.pathname}`
+        : `${stmt.op}|local:${path.raw}`;
+    if (stmt.op === "FIND" || stmt.op === "READ" || stmt.op === "SHOW" || stmt.op === "HIDE") {
+        return `${base}${matcherDiscriminator()}`;
+    }
+    return base;
 };
 // Per-turn fingerprint: sorted set of per-op fingerprints, joined. Order
 // within a turn doesn't matter — we want the SET of activities.
@@ -123,11 +175,10 @@ export default class Engine {
     // rails (cycle detection #39, etc.) — read and reset at end of each turn.
     // `history` holds per-turn fingerprints for rail #39 cycle detection.
     #strikeState = new Map();
-    // Proposal lifecycle (task #42): pending dispatch pauses waiting for
-    // resolution. Engine.runTurn awaits the promise when a scheme returns
-    // status 202; Engine.resolveProposal feeds the resolution back in. Map
-    // is per-log-entry-id; entries clear on resolution. See AGENTS.md
-    // §Phase E for the broader lifecycle plan.
+    // Proposal lifecycle: pending dispatch pauses waiting for resolution.
+    // Engine.runTurn awaits the promise when a scheme returns status 202;
+    // Engine.resolveProposal feeds the resolution back in. Map is per-log-
+    // entry-id; entries clear on resolution. SPEC.md §0.5 + §13.5 (loop.resolve).
     #pendingProposals = new Map();
     // External observers of proposal lifecycle events. Daemon subscribes
     // here to push `loop/proposal` notifications when an entry enters
@@ -135,9 +186,26 @@ export default class Engine {
     // event emitter — no priority, no veto chain at this layer; filter
     // chains come later if a real consumer needs them.
     #proposalPendingListeners = [];
-    constructor({ db, schemes, mimetypes }) {
+    // Per-loop AbortController for cancellation propagation into scheme
+    // ctx.signal. runLoop creates one at entry, cleans up at end. Engine
+    // cancellation paths (strikes, max_turns, external) abort it.
+    // Streaming schemes (exec) chain their per-spawn controllers off
+    // ctx.signal so cancelled loops tear down their background spawns.
+    #loopAborts = new Map();
+    #streamEventNotify;
+    #wakeRunNotify;
+    // 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
+    // status code but has no way to surface why the loop degraded.
+    // Per-grammar 0.17.0 protocol — see SPEC §15.1.
+    #telemetryEventNotify;
+    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, telemetryEventNotify }) {
         this.#db = db;
         this.#schemes = schemes;
+        this.#streamEventNotify = streamEventNotify;
+        this.#wakeRunNotify = wakeRunNotify;
+        this.#telemetryEventNotify = telemetryEventNotify;
         // Default to empty discovery — standalone Engine construction (in
         // tests) gets no handlers, and content flows through the framework's
         // raw-content fitContent fallback. Daemon-managed Engine receives a
@@ -147,12 +215,16 @@ export default class Engine {
         });
         this.#previewBudget = readBudget();
     }
-    #pushTelemetry(loopId, error) {
+    #pushTelemetry(sessionId, loopId, event) {
         const existing = this.#telemetryBuffer.get(loopId);
         if (existing === undefined)
-            this.#telemetryBuffer.set(loopId, [error]);
+            this.#telemetryBuffer.set(loopId, [event]);
         else
-            existing.push(error);
+            existing.push(event);
+        // Live fan-out: client sees the event the moment it lands in the
+        // model's buffer (not at the next packet build). Same envelope on
+        // both sides per the grammar 0.17.0 TelemetryEvent protocol.
+        this.#telemetryEventNotify?.(sessionId, { loopId, event });
     }
     #drainTelemetry(loopId) {
         const buf = this.#telemetryBuffer.get(loopId);
@@ -161,10 +233,53 @@ export default class Engine {
         this.#telemetryBuffer.delete(loopId);
         return buf;
     }
-    async runLoop({ provider, messages, persona = "", 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, }) {
+    // Pull a ±windowLines context block around `targetLine` (1-based) from
+    // `content`, formatted with N:\t prefixes — same shape the model
+    // already knows from READ output and numbered Index entries. Used to
+    // give parse_error telemetry concrete locality: the model sees what
+    // it wrote on the offending line, not just an abstract error message.
+    //
+    // Lenient: targetLine ≤ 0 clamps to 1; targetLine beyond content
+    // returns whatever overlap exists; empty content returns "".
+    #extractSnippet(content, targetLine, windowLines) {
+        if (content.length === 0)
+            return "";
+        const lines = content.split("\n");
+        const target = Math.max(1, targetLine);
+        const start = Math.max(1, target - windowLines);
+        const end = Math.min(lines.length, target + windowLines);
+        const slice = [];
+        for (let i = start; i <= end; i++) {
+            slice.push(`${i}:\t${lines[i - 1] ?? ""}`);
+        }
+        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, }) {
         const turnIds = [];
         const suddenDeathThreshold = maxTurns - maxStrikes;
-        const cleanup = () => {
+        // Per-loop AbortController for scheme-side cancellation propagation.
+        // Chained from the caller's `signal` so an external abort cascades.
+        const loopAbort = new AbortController();
+        if (signal !== undefined) {
+            if (signal.aborted)
+                loopAbort.abort(signal.reason);
+            else
+                signal.addEventListener("abort", () => loopAbort.abort(signal.reason), { once: true });
+        }
+        this.#loopAborts.set(loopId, loopAbort);
+        // Cleanup splits by termination kind:
+        // - "graceful" (loop emitted SEND[2xx]): in-flight streaming-scheme
+        //   spawns are ALLOWED to outlive the loop. They complete naturally,
+        //   write final channel state, and wake-on-completion (E.4) opens a
+        //   fresh loop in the same run if the model needs to react.
+        // - "forceful" (max_turns, strike_threshold, external cancel,
+        //   non-2xx loop status): fire the loop-level abort so spawns
+        //   tear down immediately.
+        const cleanup = (kind, reason) => {
+            if (kind === "forceful" && !loopAbort.signal.aborted) {
+                loopAbort.abort(reason ?? "loop_forceful_termination");
+            }
+            this.#loopAborts.delete(loopId);
             this.#strikeState.delete(loopId);
             this.#telemetryBuffer.delete(loopId);
         };
@@ -174,16 +289,19 @@ export default class Engine {
             if (row === undefined)
                 throw new Error(`Engine.runLoop: loop ${loopId} not found`);
             if (row.status !== 102) {
-                cleanup();
+                // Status 2xx = graceful (model said done); 4xx/5xx = forceful
+                // (external cancel or upstream failure). The threshold splits
+                // at 400 to match HTTP success/error semantics.
+                cleanup(row.status < 400 ? "graceful" : "forceful", `loop_terminal_${row.status}`);
                 return { turnIds, finalStatus: row.status, hitMaxTurns: false, reason: "external" };
             }
             if (turnIds.length >= maxTurns) {
                 await this.#db.engine_loop_cancel.run({ loop_id: loopId });
-                cleanup();
+                cleanup("forceful", "max_turns");
                 return { turnIds, finalStatus: 499, hitMaxTurns: true, reason: "max_turns" };
             }
             const turn = await this.runTurn({
-                provider, messages, persona, sessionId, runId, loopId, origin, signal, onDispatch,
+                provider, messages, persona, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
                 turnNumber: turnIds.length + 1, maxTurns,
             });
             turnIds.push(turn.turnId);
@@ -195,11 +313,10 @@ export default class Engine {
             const cycle = detectCycle(state.history, minCycles, maxCyclePeriod);
             if (cycle.detected) {
                 state.turnErrors++;
-                this.#pushTelemetry(loopId, {
+                this.#pushTelemetry(sessionId, loopId, {
                     kind: "cycle",
                     period: cycle.period,
                     cycles: cycle.cycles,
-                    message: `repeating pattern detected: ${cycle.cycles}× period-${cycle.period}; vary your approach`,
                 });
             }
             this.#strikeState.set(loopId, state);
@@ -214,15 +331,16 @@ export default class Engine {
             const struck = noOps || recordedFailed || state.turnErrors > 0;
             if (struck) {
                 state.streak++;
-                this.#pushTelemetry(loopId, {
+                const reason = noOps ? "no_ops" : recordedFailed ? "recorded_failure" : "rail";
+                this.#pushTelemetry(sessionId, loopId, {
                     kind: "strike",
                     streak: state.streak,
                     maxStrikes,
-                    reason: noOps ? "no_ops" : recordedFailed ? "recorded_failure" : "rail",
+                    reason,
                 });
                 if (state.streak >= maxStrikes) {
                     await this.#db.engine_loop_cancel.run({ loop_id: loopId });
-                    cleanup();
+                    cleanup("forceful", "strike_threshold");
                     return { turnIds, finalStatus: 499, hitMaxTurns: false, reason: "strike_threshold" };
                 }
             }
@@ -236,15 +354,14 @@ export default class Engine {
             // each turn so the model can wrap up before the hard cancel.
             // Soft: no strike, no loop-status change. SPEC §15.1.
             if (turnIds.length >= suddenDeathThreshold && turnIds.length < maxTurns) {
-                this.#pushTelemetry(loopId, {
+                this.#pushTelemetry(sessionId, loopId, {
                     kind: "sudden_death",
-                    message: `approaching max turns: ${turnIds.length} of ${maxTurns}; emit SEND[200] to complete`,
                     remaining: maxTurns - turnIds.length,
                 });
             }
         }
     }
-    async runTurn({ provider, messages, persona = "", sessionId, runId, loopId, origin = "model", signal, onDispatch, turnNumber = 1, maxTurns = 50, }) {
+    async runTurn({ provider, messages, persona = "", 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
@@ -263,26 +380,30 @@ export default class Engine {
         if (openRow === undefined)
             throw new Error("Engine.runTurn: turn open returned no row");
         const turnId = openRow.id;
-        // Pre-model writes. For the loop's first turn (DB sequence 1),
-        // the user's prompt becomes the first action: a system-origin
-        // EDIT against `plurnk://prompt/<loop_id>` (loop-scoped indexed
-        // entry, body=prompt text). The log row records the EDIT;
-        // content lives at the plurnk:// entry. Model ops dispatch from
-        // sequence=2 onward on the first turn; 1 onward thereafter.
-        // 1-based throughout (migration 019).
+        // Pre-model writes. Each turn opens with a system-origin EDIT
+        // against `plurnk://prompt/<loop_id>/<seq>` IF there's a prompt
+        // for THIS turn the model hasn't seen yet:
+        //   - Turn 1: loop.prompt is the initial user prompt.
+        //   - Turn N>1: only if Engine.inject (or wake-on-completion via
+        //     daemon.inject) wrote a prompt entry for this turn slot
+        //     between turn N-1 and N. Inject writes directly to entries;
+        //     we DON'T re-foist here for N>1.
+        // The log records the EDIT for forensics. Model ops dispatch
+        // from sequence=2 onward on prompt-foisted turns; 1 onward
+        // otherwise.
         let nextActionIndex = 1;
         if (seq === 1) {
             const promptRow = await this.#db.engine_get_loop_prompt.get({ loop_id: loopId });
             if (promptRow !== undefined && typeof promptRow.prompt === "string" && promptRow.prompt.length > 0) {
                 const promptPath = {
-                    kind: "url", raw: `plurnk://prompt/${loopId}`,
+                    kind: "url", raw: `plurnk://prompt/${loopId}/${seq}`,
                     scheme: "plurnk", username: null, password: null,
                     hostname: null, port: null,
-                    pathname: `prompt/${loopId}`, params: {}, fragment: null,
+                    pathname: `prompt/${loopId}/${seq}`, params: {}, fragment: null,
                 };
                 const promptStmt = {
                     op: "EDIT", suffix: "", signal: null,
-                    path: promptPath, lineMarker: null,
+                    target: promptPath, lineMarker: null,
                     body: promptRow.prompt, position: { line: 1, column: 1 },
                 };
                 await this.dispatch({
@@ -296,8 +417,8 @@ export default class Engine {
         // queries log_entries scoped to the run — the prompt entry just
         // written (if turn 1) is part of that query result.
         const requestPacket = await this.#buildRequestPacket({
-            initialMessages: messages, persona, runId, loopId,
-            turnNumber, currentTurnSeq: seq, maxTurns, provider,
+            initialMessages: messages, persona, requirements, runId, loopId,
+            currentTurnSeq: seq, provider,
         });
         const modelMessages = this.#packetToWireMessages(requestPacket);
         const response = await provider.generate({ messages: modelMessages, signal });
@@ -305,7 +426,30 @@ export default class Engine {
         // 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 } = this.#splitResponse(response);
+        const { packetAssistant, callMetadata, parseErrors } = this.#splitResponse(response);
+        // 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
+        // drop, the model sees zero ops dispatched, strike-rail fires,
+        // model has no feedback on WHY its emission didn't take effect.
+        //
+        // Envelope per @plurnk/plurnk-grammar 0.17.0 TelemetryEvent:
+        //   { source, kind, message, position: { type: "content-offset", line, column } }
+        // Plus a `snippet` field (additionalProperties) carrying ±N lines
+        // of the assistant's own content around the error line. Without
+        // the snippet, the model sees "invalid xpath at 1:0" but can't
+        // connect that to what IT wrote — and tends to regenerate the
+        // same broken emission. See edit-todo demo for the canonical case.
+        for (const { message, line, column, source } of parseErrors ?? []) {
+            this.#pushTelemetry(sessionId, loopId, {
+                source: "grammar",
+                kind: "parse_error",
+                message,
+                position: { type: "content-offset", line, column },
+                snippet: this.#extractSnippet(packetAssistant.content, line, 2),
+                parserSource: source,
+            });
+        }
         const opsCount = packetAssistant.ops.length;
         const sendOp = packetAssistant.ops.findLast((op) => op.op === "SEND" && typeof op.signal === "number");
         // Rail #41 (revised): the per-turn requirement is "emit at least one
@@ -330,8 +474,19 @@ export default class Engine {
         });
         // Dispatch model ops starting at nextActionIndex (continues the
         // turn's running counter after any pre-model writes).
+        //
+        // Max-commands cap: a single emission with more than `maxCommands`
+        // ops is the runaway-loop fingerprint observed in pathological cases
+        // (html-attrs demo: 635 ops in one turn). Cap dispatches at the
+        // configured limit; overflow ops are dropped without per-op log
+        // 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();
+        const opsToDispatch = packetAssistant.ops.slice(0, maxCommands);
+        const droppedCount = opsCount - opsToDispatch.length;
         const statuses = [];
-        for (const [i, statement] of packetAssistant.ops.entries()) {
+        for (const [i, statement] of opsToDispatch.entries()) {
             const result = await this.dispatch({
                 statement, sessionId, runId, loopId, turnId,
                 sequence: nextActionIndex + i,
@@ -339,14 +494,21 @@ export default class Engine {
             });
             statuses.push(result.status);
         }
+        if (droppedCount > 0) {
+            this.#pushTelemetry(sessionId, loopId, {
+                kind: "max_commands_exceeded",
+                emitted: opsCount,
+                cap: maxCommands,
+                dropped: droppedCount,
+            });
+        }
         if (opsCount === 0) {
             // Rail #41 (revised): per-turn requirement is "emit at least one
             // op." Zero ops = actionless failure. SEND specifically is not
             // required — any of the 9 grammar ops satisfies. Pushed AFTER
             // #buildPacket so this turn's drain doesn't consume it.
-            this.#pushTelemetry(loopId, {
+            this.#pushTelemetry(sessionId, loopId, {
                 kind: "no_ops",
-                message: "turn ended without emitting any op; emit at least one operation per turn",
             });
         }
         return { turnId, status: turnStatus, statuses, fingerprint: fingerprintTurn(packetAssistant.ops) };
@@ -354,8 +516,9 @@ export default class Engine {
     // Split the wire-level ProviderResponse into the two destinations:
     // packet.assistant gets the model's emission (content, ops, reasoning);
     // Turn columns get the call-metadata (usage, finishReason, model).
-    // PROVIDERS.md §3.3 text-fragment scraping policy lives here — engine
-    // owns the parse and the scraping rule, providers stay grammar-unaware.
+    // SPEC §2.1 / plurnk-providers#1: text-fragment scraping policy lives
+    // here — engine owns the parse and the scraping rule, providers stay
+    // grammar-unaware.
     //
     // Test-fixture escape hatch: the Mock provider may pre-supply `ops` on
     // its assistant payload to skip the parse roundtrip. The wire Provider
@@ -366,6 +529,11 @@ export default class Engine {
         const preParsedOps = assistant.ops;
         const ops = [];
         const textFragments = [];
+        // Full PlurnkParseError context (line/column/source) is preserved
+        // here so runTurn can build TelemetryEvent envelopes per the
+        // grammar 0.17.0 protocol — model needs position info to locate
+        // its own offending content on the next turn.
+        const parseErrors = [];
         if (preParsedOps !== undefined) {
             ops.push(...preParsedOps);
         }
@@ -379,6 +547,16 @@ export default class Engine {
                     if (trimmed.length > 0)
                         textFragments.push(trimmed);
                 }
+                else if (item.kind === "error") {
+                    const err = item.error;
+                    if (err instanceof PlurnkParseError) {
+                        parseErrors.push({ message: err.message, line: err.line, column: err.column, source: err.source });
+                    }
+                    else {
+                        const msg = err?.message ?? "parse error";
+                        parseErrors.push({ message: msg, line: 0, column: 0, source: "parser" });
+                    }
+                }
             }
         }
         const wireReasoning = assistant.reasoning ?? "";
@@ -388,19 +566,25 @@ export default class Engine {
         return {
             packetAssistant: { content: assistant.content, ops, reasoning },
             callMetadata: { usage: assistant.usage, finishReason: assistant.finishReason, model: assistant.model },
+            parseErrors,
         };
     }
     // Assemble the request half of the spec'd packet (Packet.json §system
     // 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.
-    // Per Packet.json: user.prompt is "Copy of loop.prompt — never null on
-    // a continuation turn"; the turn-N-of-M continuation marker rides on
-    // user.system_requirements (per-turn rules), NOT a mutated prompt.
-    async #buildRequestPacket({ initialMessages, persona: defaultPersona, runId, loopId, turnNumber, currentTurnSeq, maxTurns, provider, }) {
+    async #buildRequestPacket({ initialMessages, persona: defaultPersona, requirements, runId, loopId, currentTurnSeq, provider, }) {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
         const system_definition = byRole("system");
-        const prompt = byRole("user");
+        // 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
+        // the runLoop caller's messages.user for tests that bypass the
+        // foist mechanism entirely.
+        const latestPromptRow = await this.#db.drain_get_latest_prompt_body_for_loop.get({ pattern: `prompt/${loopId}/%` });
+        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.
@@ -409,13 +593,6 @@ export default class Engine {
         const index = await this.#buildIndex(runId, loopId);
         const log = await this.#buildLog(runId);
         const telemetryErrors = await this.#buildTelemetryErrors(loopId, currentTurnSeq);
-        // Rummy AgentLoop.js #buildContinuationPrompt: literally
-        // `Turn ${turn}/${maxTurns}`. That's the whole string. The model
-        // can read the action log to see what it already did; it does
-        // not need editorial instructions from us about not repeating.
-        const system_requirements = turnNumber > 1
-            ? `Turn ${turnNumber}/${maxTurns}`
-            : "";
         // Per-section render-cost subtotals via provider's tokenizer.
         // Engine approximates each section by tokenizing its serialized
         // form — wire-payload tokens may differ slightly because chat-
@@ -426,13 +603,13 @@ export default class Engine {
             provider.countTokens(JSON.stringify(index)) +
             provider.countTokens(JSON.stringify(log));
         // user.telemetry.budget — shimmed with section-aggregate table.
-        // Real per-scheme breakdown is on AGENTS.md TODO (provider doesn't
-        // yet expose getContextSize; user-side token count is below).
-        const budget = this.#renderBudgetShim(systemTokens, provider, prompt, system_requirements, telemetryErrors);
+        // Real per-scheme breakdown is the tokenomics chapter (SPEC.md §14.2);
+        // depends on provider.getContextSize and write-time per-row tokens.
+        const budget = this.#renderBudgetShim(systemTokens, provider, prompt, telemetryErrors);
         const userTokens = provider.countTokens(prompt) +
-            provider.countTokens(system_requirements) +
             provider.countTokens(JSON.stringify(telemetryErrors)) +
-            provider.countTokens(budget);
+            provider.countTokens(budget) +
+            provider.countTokens(requirements);
         return {
             system: {
                 tokens: systemTokens,
@@ -445,20 +622,19 @@ export default class Engine {
                 tokens: userTokens,
                 prompt,
                 telemetry: { budget, errors: telemetryErrors },
-                system_requirements,
+                system_requirements: requirements,
             },
         };
     }
-    // user.telemetry.budget — SHIM. Per AGENTS.md §Open: real per-scheme
-    // breakdown + context-window "free/percent-of-total" awaits provider
-    // contract additions (getContextSize). Until then, render the section-
-    // aggregate counts we already compute so the wire's `# Plurnk System
-    // Budget` section is non-empty for picking-apart purposes.
-    #renderBudgetShim(systemTokens, provider, prompt, system_requirements, telemetryErrors) {
+    // user.telemetry.budget — SHIM. Real per-scheme breakdown +
+    // context-window "free/percent-of-total" is SPEC.md §14.2; depends on
+    // provider.getContextSize and write-time per-row tokens. Until then,
+    // render the section-aggregate counts we already compute so the wire's
+    // `# Plurnk System Budget` section is non-empty for picking-apart purposes.
+    #renderBudgetShim(systemTokens, provider, prompt, telemetryErrors) {
         const userPromptTokens = provider.countTokens(prompt);
-        const userReqTokens = provider.countTokens(system_requirements);
         const userErrTokens = provider.countTokens(JSON.stringify(telemetryErrors));
-        const userTokens = userPromptTokens + userReqTokens + userErrTokens;
+        const userTokens = userPromptTokens + userErrTokens;
         const total = systemTokens + userTokens;
         const pct = (n) => total === 0 ? "0.0%" : `${((n / total) * 100).toFixed(1)}%`;
         return [
@@ -511,7 +687,7 @@ export default class Engine {
                 op: r.op,
                 target,
                 status: r.status_rx,
-                message: typeof parsedRx === "object" && parsedRx !== null && "error" in parsedRx
+                error: typeof parsedRx === "object" && parsedRx !== null && "error" in parsedRx
                     ? parsedRx.error
                     : typeof parsedRx === "string" ? parsedRx : "",
             };
@@ -549,19 +725,26 @@ export default class Engine {
             status: r.status_rx,
             rx: r.mimetype_rx === "application/json" ? JSON.parse(r.rx) : r.rx,
             mimetype_rx: r.mimetype_rx,
+            tx: r.mimetype_tx === "application/json" ? JSON.parse(r.tx) : r.tx,
+            mimetype_tx: r.mimetype_tx,
         }));
     }
     async #buildIndex(runId, currentLoopId) {
         const rows = await this.#db.engine_render_index.all({ run_id: runId });
         const tagsStmt = this.#db.engine_entry_tags;
-        // Foist the CURRENT loop's prompt entry out of the index render —
-        // it's materialized in packet.user.prompt instead. Previous loops'
-        // prompt entries stay in the index, addressable for the model to
-        // HIDE if it wants.
-        const foistedPathname = `prompt/${currentLoopId}`;
+        // Foist the CURRENT loop's prompt entries out of the index render —
+        // their bodies are materialized in packet.user.prompt instead. With
+        // multi-turn injection, a loop can have multiple prompt entries at
+        // plurnk://prompt/<loop_id>/<N>; all of them get foisted, leaving
+        // only previous loops' prompts (still addressable for HIDE).
+        const foistedPrefix = `prompt/${currentLoopId}/`;
+        // Backward compat: legacy single-slot path. Tests / older runs may
+        // still have a `prompt/<loop_id>` entry (no trailing /N); foist it too.
+        const foistedExact = `prompt/${currentLoopId}`;
         const entries = new Map();
         for (const row of rows) {
-            if (row.scheme === "plurnk" && row.pathname === foistedPathname)
+            if (row.scheme === "plurnk"
+                && (row.pathname === foistedExact || row.pathname.startsWith(foistedPrefix)))
                 continue;
             let entry = entries.get(row.entry_id);
             if (entry === undefined) {
@@ -611,7 +794,10 @@ export default class Engine {
             db: this.#db,
             sessionId, runId, loopId, turnId,
             writer: origin,
-            signal: undefined,
+            signal: this.#loopAborts.get(loopId)?.signal,
+            streamEventNotify: this.#streamEventNotify,
+            wakeRunNotify: this.#wakeRunNotify,
+            mimetypes: this.#mimetypes,
         };
         let result;
         let denial = this.#checkWritable(statement, origin);
@@ -621,13 +807,13 @@ export default class Engine {
             result = denial;
         }
         else {
-            // SCHEMES.md §7.1 / §8: action-entry-as-outcome. Scheme-handler
+            // SPEC §3.6 + plurnk-schemes#1: action-entry-as-outcome. Scheme-handler
             // exceptions become the action-entry's outcome (status 500), not a
             // thrown bubble. The log_entry is the durable record; engine never
             // skips it. Logging failures (#writeLog throws) are NOT caught —
             // those are system failures.
             try {
-                if (statement.op === "SEND" && statement.path === null) {
+                if (statement.op === "SEND" && statement.target === null) {
                     result = await this.#handleSendBroadcast(statement, loopId);
                 }
                 else if (statement.op === "COPY") {
@@ -636,8 +822,15 @@ export default class Engine {
                 else if (statement.op === "MOVE") {
                     result = await this.#handleMove(statement, schemeCtx);
                 }
+                else if (statement.op === "EXEC") {
+                    // EXEC's target slot is `cwd`, not a scheme address.
+                    // Per plurnk.md the op routes unconditionally to the
+                    // exec scheme; the scheme handler reads runtime
+                    // (signal), cwd (target), and command (body).
+                    result = await this.#run("exec", statement, schemeCtx);
+                }
                 else {
-                    result = await this.#run(this.#schemeNameOf(statement.path), statement, schemeCtx);
+                    result = await this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx);
                 }
             }
             catch (err) {
@@ -649,13 +842,13 @@ export default class Engine {
         }
         const logEntryId = await this.#writeLog({ statement, result, runId, loopId, turnId, sequence, origin });
         onDispatch?.(logEntryId);
-        // Proposal lifecycle (task #42, AGENTS.md §Phase E). When a scheme
-        // returns status 202, the entry is written as state='proposed';
+        // Proposal lifecycle (SPEC.md §0.5 + §13.5 loop.resolve). 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,
-        // YOLO listener, or timeout — Phase E.2/E.3 work). The post-
-        // resolution status replaces 202 in the result the caller sees,
-        // so runTurn never branches on a pending state.
+        // YOLO listener, or timeout). The post-resolution status replaces
+        // 202 in the result the caller sees, so runTurn never branches on
+        // a pending state.
         if (result.status === 202) {
             // Register the resolution waiter SYNCHRONOUSLY before any await
             // yields. A same-tick resolveProposal() (e.g. from a test that
@@ -666,7 +859,7 @@ export default class Engine {
             // Notify external listeners (Daemon broadcasts loop/proposal;
             // YOLO listener auto-resolves) BEFORE awaiting — they may
             // resolve synchronously inside their handlers.
-            const target = this.#extractTarget(statement.path);
+            const target = this.#extractTarget(statement.target);
             const flags = await this.#loadLoopFlags(loopId);
             const event = {
                 logEntryId, sessionId, runId, loopId, turnId,
@@ -698,7 +891,10 @@ export default class Engine {
         const { sessionId, runId, loopId, turnId } = ids;
         if (resolution.decision !== "accept")
             return resolution;
-        const schemeName = this.#schemeNameOf(statement.path);
+        // EXEC routes to the exec scheme regardless of target (cwd, not
+        // a scheme address). All other ops resolve their handler from
+        // statement.target's scheme.
+        const schemeName = statement.op === "EXEC" ? "exec" : this.#schemeNameOf(statement.target);
         if (schemeName === null)
             return resolution;
         const handler = this.#schemes.get(schemeName);
@@ -711,7 +907,9 @@ export default class Engine {
             // operation's artifact visible in the next packet's index.
             const applyCtx = {
                 db: this.#db, sessionId, runId, loopId, turnId,
-                writer: "model", signal: undefined,
+                writer: "model", signal: this.#loopAborts.get(loopId)?.signal,
+                streamEventNotify: this.#streamEventNotify,
+                wakeRunNotify: this.#wakeRunNotify,
             };
             const applyResult = await handler.applyResolution({
                 attrs: (originalResult.attrs ?? {}),
@@ -724,6 +922,14 @@ export default class Engine {
                     body: applyResult.body,
                 };
             }
+            // Propagate applyResolution.outcome onto the accepted resolution
+            // so the log entry's outcome column reflects operational metadata
+            // (e.g. exec's "exit_N"). Without this, only failures get an
+            // outcome on the durable record, and "ran cleanly but with a
+            // notable detail" has nowhere to land.
+            if (applyResult.outcome !== undefined && resolution.outcome === undefined) {
+                return { ...resolution, outcome: applyResult.outcome };
+            }
             return resolution;
         }
         catch (err) {
@@ -754,6 +960,52 @@ export default class Engine {
     pendingProposalIds() {
         return [...this.#pendingProposals.keys()];
     }
+    // Used by wake-on-completion (daemon side): "is there any loop in this
+    // run still accepting turns?" If yes, skip the wake — the active loop
+    // will pick up the channel transition at its next turn boundary. If no,
+    // the daemon opens a fresh loop with the wake prompt.
+    async hasActiveLoopForRun(runId) {
+        const row = await this.#db.engine_count_active_loops_for_run.get({ run_id: runId });
+        return (row?.n ?? 0) > 0;
+    }
+    // Inject a prompt into the run's currently-executing loop. Writes a
+    // plurnk://prompt/<loop_id>/<next-turn> entry whose body becomes
+    // packet.user.prompt at the next turn boundary. Last-wins: if two
+    // injects target the same next-turn slot, the second overwrites the
+    // first.
+    //
+    // Returns null when no loop in the run is currently active (status=102).
+    // The daemon-side inject path then enqueues a fresh loop with this
+    // prompt; engine doesn't open loops itself.
+    //
+    // Rummy parallel: AgentLoop.inject(). The "active drain → write
+    // prompt entry, return immediately" branch.
+    async inject(runId, prompt) {
+        const loopRow = await this.#db.drain_current_loop_for_run.get({ run_id: runId });
+        if (loopRow === undefined)
+            return null;
+        const loopId = loopRow.id;
+        const turnRow = await this.#db.drain_next_turn_seq_for_loop.get({ loop_id: loopId });
+        const turnSeq = turnRow?.next ?? 1;
+        const sessionRow = await this.#db.drain_get_run_session.get({ run_id: runId });
+        if (sessionRow === undefined)
+            throw new Error(`Engine.inject: run ${runId} not found`);
+        const pathname = `prompt/${loopId}/${turnSeq}`;
+        const ctx = {
+            db: this.#db, sessionId: sessionRow.session_id, runId, loopId,
+            turnId: 0, // no turn open at inject time; entries don't pin turnId
+            writer: "system",
+            signal: this.#loopAborts.get(loopId)?.signal,
+            streamEventNotify: this.#streamEventNotify,
+            wakeRunNotify: this.#wakeRunNotify,
+        };
+        const entry = {
+            channels: { body: { content: prompt, mimetype: "text/markdown" } },
+            tags: [],
+        };
+        await writeEntry(pathname, entry, ctx, "plurnk");
+        return { loopId, turnSeq };
+    }
     // Subscribe to proposal-pending events. Daemon registers a listener
     // that broadcasts the loop/proposal WS notification; YOLO listener
     // (Phase E.3) registers one that auto-resolves. Listeners fire BEFORE
@@ -824,8 +1076,8 @@ export default class Engine {
         });
         return { status, outcome, body: resolution.body };
     }
-    // SCHEMES.md §8 {§8-writable-by-enforcement}: engine rejects writes whose
-    // origin is outside the target scheme's manifest.writableBy.
+    // SPEC §3.6: engine rejects writes whose origin is outside the target
+    // scheme's manifest.writableBy.
     // - Read-side ops (READ, FIND, SHOW, HIDE) are not gated.
     // - SEND broadcast (path=null) has no target scheme; not gated.
     // - COPY: dst scheme writableBy applies.
@@ -834,15 +1086,20 @@ export default class Engine {
     #checkWritable(statement, origin) {
         if (!MUTATING_OPS.has(statement.op))
             return null;
-        if (statement.op === "SEND" && statement.path === null)
+        if (statement.op === "SEND" && statement.target === null)
             return null;
+        // EXEC's target slot is `cwd`, not a scheme address. The op's
+        // authority always belongs to the exec scheme regardless of cwd.
+        if (statement.op === "EXEC") {
+            return this.#denyIfDisallowed("exec", origin);
+        }
         if (statement.op === "COPY" || statement.op === "MOVE") {
             const dstScheme = this.#schemeNameOf(statement.body);
             const dstDenial = this.#denyIfDisallowed(dstScheme, origin);
             if (dstDenial !== null)
                 return dstDenial;
             if (statement.op === "MOVE") {
-                const srcScheme = this.#schemeNameOf(statement.path);
+                const srcScheme = this.#schemeNameOf(statement.target);
                 if (srcScheme !== dstScheme) {
                     const srcDenial = this.#denyIfDisallowed(srcScheme, origin);
                     if (srcDenial !== null)
@@ -851,7 +1108,7 @@ export default class Engine {
             }
             return null;
         }
-        const target = this.#schemeNameOf(statement.path);
+        const target = this.#schemeNameOf(statement.target);
         return this.#denyIfDisallowed(target, origin);
     }
     #denyIfDisallowed(schemeName, origin) {
@@ -874,15 +1131,15 @@ export default class Engine {
     // set returns 403 — action-entry-as-outcome carries the rejection.
     async #checkFlagsGate(statement, loopId) {
         // Broadcast SEND has no scheme to gate.
-        if (statement.op === "SEND" && statement.path === null)
+        if (statement.op === "SEND" && statement.target === null)
             return null;
         const flags = await this.#loadLoopFlags(loopId);
         // Fast path: default flags gate nothing. (yolo never gates.)
         if (!flags.noProposals && !flags.noWeb && !flags.noInteraction && flags.mode === "act")
             return null;
         const active = this.#schemes.resolveForLoop(flags);
-        const check = (path) => {
-            const scheme = this.#schemeNameOf(path);
+        const check = (target) => {
+            const scheme = this.#schemeNameOf(target);
             if (scheme === null)
                 return null;
             if (active.has(scheme))
@@ -890,14 +1147,14 @@ export default class Engine {
             return { status: 403, error: `scheme '${scheme}' is inactive under current loop flags` };
         };
         if (statement.op === "COPY" || statement.op === "MOVE") {
-            return check(statement.path) ?? check(statement.body);
+            return check(statement.target) ?? check(statement.body);
         }
-        return check(statement.path);
+        return check(statement.target);
     }
     async #handleCopy(statement, ctx) {
         if (statement.op !== "COPY")
             throw new Error("unreachable");
-        const srcPath = statement.path;
+        const srcPath = statement.target;
         const dstPath = statement.body;
         if (srcPath === null)
             return { status: 400, error: "COPY requires source path" };
@@ -908,7 +1165,7 @@ export default class Engine {
     async #handleMove(statement, ctx) {
         if (statement.op !== "MOVE")
             throw new Error("unreachable");
-        const srcPath = statement.path;
+        const srcPath = statement.target;
         const dstPath = statement.body;
         if (srcPath === null)
             return { status: 400, error: "MOVE requires source path" };
@@ -966,11 +1223,30 @@ export default class Engine {
                 return { status: 415, error: `mimetype mismatch on channel '${channelName}': ${channelData.mimetype} vs ${expectedMimetype}` };
             }
         }
+        // `<L>` source range slicing per SPEC.md §16.9 (symmetric with READ
+        // `<L>` — source range, no line-number prefix).
+        // Applied to every channel of the source entry. Binary channels return
+        // 415 since line semantics don't apply.
+        const lineMarker = statement.lineMarker ?? null;
+        let channels = entry.channels;
+        if (lineMarker !== null) {
+            const sliced = {};
+            for (const [channelName, channelData] of Object.entries(entry.channels)) {
+                if (isBinaryMimetype(channelData.mimetype)) {
+                    return { status: 415, error: `cannot slice <L> on binary channel '${channelName}' (${channelData.mimetype})` };
+                }
+                const r = sliceLinesRaw(channelData.content ?? "", lineMarker);
+                if (r.status !== 200)
+                    return { status: r.status, error: r.error };
+                sliced[channelName] = { ...channelData, content: r.text ?? "" };
+            }
+            channels = sliced;
+        }
         // Tag resolution: signal = replace; absent/empty = carry from source
         const tags = (Array.isArray(statement.signal) && statement.signal.length > 0)
             ? statement.signal
             : entry.tags;
-        const writeResult = await dstHandler.writeEntry(dstPathname, { channels: entry.channels, tags }, ctx);
+        const writeResult = await dstHandler.writeEntry(dstPathname, { channels, tags }, ctx);
         return { status: writeResult.status, entryId: writeResult.entryId, created: writeResult.created };
     }
     async #handleSendBroadcast(statement, loopId) {
@@ -1007,7 +1283,7 @@ export default class Engine {
         return "file"; // local (bare) → file
     }
     async #writeLog({ statement, result, runId, loopId, turnId, sequence, origin, }) {
-        const target = this.#extractTarget(statement.path);
+        const target = this.#extractTarget(statement.target);
         const lineMarkerJson = "lineMarker" in statement && statement.lineMarker !== null
             ? JSON.stringify(statement.lineMarker)
             : null;
@@ -1018,9 +1294,36 @@ export default class Engine {
         // consumes on accept. All other statuses are terminal — state =
         // 'resolved' for the common case.
         const isProposed = result.status === 202;
-        const attrs = (result.attrs !== undefined && result.attrs !== null)
-            ? JSON.stringify(result.attrs)
-            : "{}";
+        let attrsObj = (result.attrs !== undefined && result.attrs !== null)
+            ? { ...result.attrs }
+            : {};
+        // EXEC pathname is coordinate-based — the stream entry lives at
+        // exec://<loop_seq>/<turn_seq>/<sequence>/EXEC, mirroring the log
+        // row's own URI at log://<...>/EXEC. The model can correlate the
+        // log meta to its stream output by structural parallelism — no
+        // random slug injection. Coordinate is resolved here because both
+        // log row write and applyResolution need it.
+        if (statement.op === "EXEC") {
+            const seqs = await this.#db.engine_loop_turn_seqs.get({
+                loop_id: loopId, turn_id: turnId,
+            });
+            if (seqs === undefined)
+                throw new Error(`Engine.#writeLog: loop_turn_seqs returned no row for loop=${loopId} turn=${turnId}`);
+            const coordPathname = `${seqs.loop_seq}/${seqs.turn_seq}/${sequence}/EXEC`;
+            target.scheme = "exec";
+            target.pathname = coordPathname;
+            attrsObj.pathname = coordPathname;
+            // Mutate the in-memory result.attrs too: the dispatch path
+            // hands originalResult.attrs to handler.applyResolution after
+            // proposal accept (see #acceptResolution). Both views — the
+            // stored row AND the in-memory proposal — need the same
+            // coordinate-based pathname so applyResolution writes the
+            // entry at exec://<coord>/EXEC.
+            if (result.attrs !== undefined && result.attrs !== null) {
+                result.attrs.pathname = coordPathname;
+            }
+        }
+        const attrs = JSON.stringify(attrsObj);
         const row = await this.#db.engine_insert_log_entry.get({
             run_id: runId,
             loop_id: loopId,