@plurnk/plurnk-service 0.56.0 → 0.57.0

package/dist/core/Engine.js

@@ -64,14 +64,14 @@ const readMaxCommands = () => {
         return DEFAULT_MAX_COMMANDS;
     return n;
 };
-// PLURNK_MANIFEST_ITEMS — the turn-0 manifest preview. null = off (no foist);
+// PLURNK_FILES_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;
+const normalizeFilesItems = (n) => (!Number.isFinite(n) || n === 0 ? null : n < 0 ? -1 : n);
+const readFilesItems = () => {
+    const raw = process.env.PLURNK_FILES_ITEMS;
     if (raw === undefined || raw.length === 0)
         return null;
-    return normalizeManifestItems(Number.parseInt(raw, 10));
+    return normalizeFilesItems(Number.parseInt(raw, 10));
 };
 import { ProviderError } from "@plurnk/plurnk-providers";
 // Resolution timeout — proposed entries auto-cancel if nothing arrives
@@ -315,6 +315,8 @@ class Engine {
             // #263 — the last turn's prompt tokens = current window occupancy (gauge numerator), NOT the
             // summed promptTokens above, which overcounts a context that grows across turns.
             contextTokens: row?.context ?? 0,
+            // #274 — the last turn's model window (denominator); null when the provider reports none.
+            contextSize: row?.context_size ?? null,
             // #252 — the latest turn's opaque provider blob, parsed for the wire. Empty {} when the
             // provider returned no meta. The service forwards it; it never reads a field within.
             meta: JSON.parse(row?.meta ?? "{}"),
@@ -339,27 +341,6 @@ class Engine {
         this.#telemetryBuffer.delete(loopId);
         return buf;
     }
-    // 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");
-    }
     // A @plurnk/gbnf divergence position (providers#24) is a CODE-POINT offset into the
     // model's content; the snippet/telemetry surface speaks 1-based line + 0-based column.
     // Convert over code points (not UTF-16 units) so an astral char doesn't skew the line,
@@ -548,7 +529,14 @@ class Engine {
         // from sequence=2 onward on prompt-foisted turns; 1 onward
         // otherwise.
         let nextActionIndex = 1;
+        // §model-entry — the run's first turn opens with the model's own turn-0, mirrored OPEN: a
+        // worked turn PLAN → the environment FINDs the foist ACTUALLY dispatches → SEND[102]. Built
+        // from the real ops below (not a static print — we lean into the genuine echo paradigm) and
+        // written at sequence 1, so it reads first as the emission with the foisted results following.
+        const turnZeroMoves = [];
         if (seq === 1) {
+            if (runFirstLoop)
+                nextActionIndex = 2; // reserve sequence 1 for the turn-0 echo
             // 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
@@ -627,16 +615,16 @@ class Engine {
         const fsDivergences = await GitMembership.indexGitMembership(systemCtx);
         await this.#logFsFictions(sessionId, fsDivergences);
         await EntryManifest.maintainDerivations(systemCtx);
-        // Turn-0 catalog preview (PLURNK_MANIFEST_ITEMS, §actor-boundary-manifest-preview):
+        // Turn-0 catalog preview (PLURNK_FILES_ITEMS, §actor-boundary-manifest-preview):
         // one FIND(scheme:///**) per scheme that holds entries, foisted into the run's first
         // model turn so it opens with its catalog (the per-scheme arrays that replaced the
         // single manifest.json). -1 → each scheme's whole catalog; N → its first N rows
         // (clamped to the scheme's count so FIND's strict <L> never 416s); off by default.
         if (seq === 1) {
-            // #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 && runFirstLoop) { // #269 — catalog preview is run-once
+            // #231 — a session's client-chosen filesItems REPLACES the env default outright.
+            const { filesItems: sessionMI } = await SessionSettings.read(this.#db, sessionId);
+            const filesItems = sessionMI !== null ? normalizeFilesItems(sessionMI) : readFilesItems();
+            if (filesItems !== null && runFirstLoop) { // #269 — catalog preview is run-once
                 // engine_scheme_catalog_summary is the scheme source: session-scoped, ordered,
                 // one row per scheme that has entries (scheme=null → file). log:// is absent —
                 // it lives in log_entries, not the catalog (present-mode, the # Log section).
@@ -656,9 +644,12 @@ class Engine {
                     // documenting surface. The prompt is shown in # Prompt, so the plurnk catalog
                     // the model orients on IS the docs; doc links are no longer rendered inline (#270).
                     const isPlurnk = schemeName === "plurnk";
-                    // entries===0 (an always-foisted empty known/unknown) → uncapped: nothing to
-                    // clamp, and Math.min(items, 0)=0 would emit a degenerate <1,0> marker.
-                    const cap = isPlurnk || manifestItems < 0 || entries === 0 ? null : Math.min(manifestItems, entries);
+                    // Only the FILE list is cappable (PLURNK_FILES_ITEMS first-N): the tracked-file
+                    // tree is external and arbitrarily large. Every other scheme — known/unknown
+                    // (memory), run (scratch), plurnk (docs) — foists FULL, never truncated: a partial
+                    // view of the model's own memory reads as withheld. file at -1, or any non-file
+                    // scheme → no cap. (file in this loop always has entries>0, so no degenerate <1,0>.)
+                    const cap = schemeName === "file" && filesItems > 0 ? Math.min(filesItems, entries) : null;
                     const catalogFind = {
                         op: "FIND", suffix: "", signal: null,
                         target: {
@@ -678,9 +669,12 @@ class Engine {
                         sequence: nextActionIndex, origin: "plurnk", onDispatch,
                     });
                     nextActionIndex++;
+                    // §model-entry — the same FIND, rendered back to DSL for the turn-0 echo (the model's
+                    // own survey, mirrored OPEN). The <L> cap rides as `<1,N>`, exactly as the model would type it.
+                    turnZeroMoves.push(`<<FIND(${isPlurnk ? "plurnk://docs/**" : `${schemeName}:///**`})${cap === null ? "" : `<1,${cap}>`}::FIND`);
                 }
                 // §run-scheme — Manifest(run) = session-scope ∪ THIS run's run-scope. Foist the
-                // building run's OWN scratch (run:///**, uncapped — a run needs the full view to
+                // building run's OWN scratch (run://self/**, uncapped — a run needs the full view to
                 // manage its private workspace) so it's catalogued in ITS perspective alone; other
                 // runs reach it only via explicit FIND(run://<name>/**). A run with no scratch foists nothing.
                 const selfRun = await this.#db.run_name_by_id.get({ run_id: runId });
@@ -688,11 +682,12 @@ class Engine {
                 if (scratch > 0) {
                     const runFind = {
                         op: "FIND", suffix: "", signal: null,
-                        target: { kind: "url", raw: "run:///**", scheme: "run", username: null, password: null, hostname: "", port: null, pathname: "/**", params: {}, fragment: null },
+                        target: { kind: "url", raw: "run://self/**", scheme: "run", username: null, password: null, hostname: "self", port: null, pathname: "/**", params: {}, fragment: null },
                         body: null, lineMarker: null, position: { line: 1, column: 1 },
                     };
                     await this.dispatch({ statement: runFind, sessionId, runId, loopId, turnId, sequence: nextActionIndex, origin: "plurnk", onDispatch });
                     nextActionIndex++;
+                    turnZeroMoves.push("<<FIND(run://self/**)::FIND"); // §model-entry — the run-scope survey, into the turn-0 echo
                 }
             }
             // #260 — foist a turn-0 READ of each client-passed @file path so its content sits in front
@@ -716,12 +711,24 @@ class Engine {
                 });
                 nextActionIndex++;
             }
+            // §model-entry — mirror the model's turn-0 OPEN at sequence 1: PLAN → the FINDs actually
+            // foisted above (real, their results already in the log) → SEND[102]. Dynamic — it reflects
+            // the true survey, never a frozen print — and OPEN: the worked example the model orients on,
+            // so the grammar can stay thin. Subsequent turns mirror the model's real output, folded.
+            if (runFirstLoop) {
+                const emission = ["<<PLAN:Initialize:PLAN", ...turnZeroMoves, "<<SEND[102]:Initialized:SEND"].join("\n");
+                await this.#writeModelEntry({ verbatim: emission, runId, loopId, turnId, sequence: 1, folded: false, origin: "plurnk" });
+            }
         }
         // §environment-observation — pre-seed the run's ambient observations (what changed since
         // it last looked) as foisted rows before the packet composes; advance the action index
         // past them so model ops continue after. Two instances of one machine: env-delta (sibling
         // edits · timestamp cursor · always folded) and exec streams (channel bytes · byte cursor ·
         // terminal delta opens). §env-delta §exec-stream
+        // §exec-poll — EXEC `<0>` is turn-scoped: reap the run's open turn-scoped streams (necessarily
+        // from a prior turn — this runs before the turn's own spawns) so a `<0>` never survives into
+        // the subsequent turn. The terminal output then surfaces born-OPEN via the stream-delta path.
+        await this.#reapTurnScopedStreams(runId);
         nextActionIndex += await this.#materializeEnvironmentDeltas({ sessionId, runId, loopId, turnId, fromSequence: nextActionIndex });
         nextActionIndex += await this.#materializeStreamDeltas({ runId, loopId, turnId, fromSequence: nextActionIndex });
         // SPEC §telemetry — git working-tree state for the telemetry section, read once
@@ -751,6 +758,7 @@ class Engine {
             await this.#db.engine_close_turn.run({
                 id: turnId, status: 413, packet: JSON.stringify(hardPacket),
                 usage_prompt: 0, usage_completion: 0, usage_cached: 0, usage_cost_pico: 0,
+                usage_context_size: provider.contextSize, // #274 — the model's window, even on a hard-413 turn
                 finish_reason: "budget_hard_stop", model: provider.model, meta: "{}",
             });
             return { turnId, status: 413, statuses: [], fingerprint: "", budgetStruck: enforced.struck, budgetHardStop: true, steerStruck: false };
@@ -786,7 +794,7 @@ class Engine {
             // In GBNF-filter mode the provider returns the bytes with a grammar_unenforced telemetry
             // event instead — recovered on the success path below (response.telemetry), no empty turn.
             if (err instanceof ProviderError) {
-                this.#pushTelemetry(sessionId, loopId, { source: "provider", kind: err.kind, message: err.message });
+                this.#pushTelemetry(sessionId, loopId, { source: "provider", kind: err.kind, message: err.message, level: "error" });
                 if (err.kind !== "grammar_unenforced")
                     throw err;
                 response = {
@@ -823,20 +831,23 @@ class Engine {
         // providers#24 / #275: non-fatal provider telemetry on a SUCCESSFUL turn. In GBNF-filter
         // mode the provider no longer THROWS grammar_unenforced — it returns the model's bytes
         // (here, packetAssistant.content) and attaches the conflict as a telemetry event carrying
-        // the divergence code-point position. Mirror the parse_error path: forward each event, and
-        // when it locates a position, render the model its own emission around that line so it can
-        // self-correct — the exact recovery affordance parse errors already get, instead of the
-        // empty-turn cascade the old throw produced.
+        // the divergence code-point position. Forward each event with a content-offset `line:col`;
+        // the model resolves it against its own emission — the born-OPEN `model` row (§model-entry),
+        // not an embedded snippet that would duplicate the emission.
+        let hadContentOffsetNotice = false;
         for (const event of response.telemetry ?? []) {
             const located = typeof event.position === "number"
                 ? this.#offsetToLineColumn(packetAssistant.content, event.position)
                 : null;
+            if (located !== null)
+                hadContentOffsetNotice = true;
             this.#pushTelemetry(sessionId, loopId, {
                 source: event.source,
                 kind: event.kind,
                 message: event.message ?? "",
+                level: event.level ?? "warn", // forward the producer's severity; default for a producer predating the field
                 ...(located !== null
-                    ? { position: { type: "content-offset", line: located.line, column: located.column }, snippet: this.#extractSnippet(packetAssistant.content, located.line, 2) }
+                    ? { position: { type: "content-offset", line: located.line, column: located.column } }
                     : {}),
             });
         }
@@ -867,6 +878,7 @@ class Engine {
                     source: "engine:rail",
                     kind: "premature_terminate",
                     message: "Attempted termination with active streams or child runs. Terminate with 202 to hibernate until they complete, KILL(path) with 200 again to clean up, or 499 to fail.",
+                    level: "warn",
                 });
             }
         }
@@ -884,6 +896,7 @@ class Engine {
                 source: "engine:rail",
                 kind: "idle_turn",
                 message: "If the turn's work is complete, terminate with 200. If awaiting a stream or run trigger, terminate with 202 to hibernate.",
+                level: "warn",
             });
         }
         // Close the turn with the final packet, status, and usage stats.
@@ -897,6 +910,7 @@ class Engine {
             usage_completion: usage.completion,
             usage_cached: usage.cached,
             usage_cost_pico: provider.costFor(usage), // §provider-surface-costfor
+            usage_context_size: provider.contextSize, // #274 — the running model's window (gauge denominator)
             finish_reason: finishReason,
             model,
             // #252 — opaque provider→client metadata passthrough (e.g. balancePico the
@@ -925,13 +939,18 @@ class Engine {
             || realCommands++ < maxCommands);
         const droppedCount = opsCount - opsToDispatch.length;
         const statuses = [];
-        for (const [i, statement] of opsToDispatch.entries()) {
+        // Running counter — a multi-file READ writes N rows from one statement (rowsWritten),
+        // so the next op's sequence picks up after them. Collapses to nextActionIndex+i when
+        // every op writes one row (the common case).
+        let rowSeq = nextActionIndex;
+        for (const statement of opsToDispatch) {
             const result = await this.dispatch({
                 statement, sessionId, runId, loopId, turnId,
-                sequence: nextActionIndex + i,
+                sequence: rowSeq,
                 origin, onDispatch,
             });
             statuses.push(result.status);
+            rowSeq += result.rowsWritten ?? 1;
         }
         // max_commands_exceeded IS model-facing: dropped ops are things
         // the model emitted that didn't run — it needs to know. Engine
@@ -943,29 +962,39 @@ class Engine {
                 kind: "max_commands_exceeded",
                 emitted: opsCount,
                 dropped: droppedCount,
+                level: "error",
             });
         }
         // §telemetry — parse errors as LOG ITEMS: a failed-to-parse emission records an actionless
         // `error` row (status 400, no target, snippet = the foldable body) at the turn's next free
         // sequence (after the dispatched ops). The model folds/kills/recalls it like any log entry,
         // and the errors section derives a pointer (status + coordinate) from log≥400 — one surface.
-        let errSeq = nextActionIndex + opsToDispatch.length;
+        let errSeq = rowSeq; // after every dispatched row, including a multi-file READ's fan-out
         for (const { message, line, column, source } of parseErrors ?? []) {
-            const snippet = this.#extractSnippet(packetAssistant.content, line, 2);
             await this.#db.engine_insert_log_entry.get({
                 run_id: runId, loop_id: loopId, turn_id: turnId, sequence: errSeq++,
                 origin: "model", source: "grammar", op: "error", suffix: "", signal: null,
                 scheme: null, username: null, password: null, hostname: null, port: null,
                 pathname: null, params: null, fragment: null, lineMarker: null,
                 tx: "", mimetype_tx: "text/plain",
-                // `message`/`snippet` render as the foldable body (not a pointer `error` field), so the
-                // derived errors-section pointer stays minimal (status + coordinate), the bloated parser
-                // message lives in the log row, reclaimable on FOLD.
-                rx: JSON.stringify({ message, position: { type: "content-offset", line, column }, snippet, parserSource: source }),
+                // The error carries the parser message + a content-offset `line:col`; the model resolves
+                // it against its own born-OPEN emission (the `model` row, §model-entry), so no snippet is
+                // embedded. The derived errors-section pointer stays minimal (status + coordinate).
+                rx: JSON.stringify({ message, position: { type: "content-offset", line, column }, parserSource: source }),
                 mimetype_rx: "application/json",
                 status_rx: 400, tokens: 0, state: "resolved", outcome: null, attrs: "{}",
             });
         }
+        // §model-entry — mirror this turn's verbatim emission back as a `model` row, so the NEXT
+        // packet shows the model exactly what it last produced. Born OPEN when the turn carried an
+        // emission-level error the model must resolve against its own bytes — a parse error or a
+        // content-offset NOTICE (grammar_unenforced) — both report a line the model reads off this
+        // row. Folded otherwise (budget-neutral until the model OPENs it). Empty emissions (a
+        // struck/silent turn) write nothing — no prior output to mirror.
+        if (packetAssistant.content.trim().length > 0) {
+            const hadEmissionError = (parseErrors?.length ?? 0) > 0 || hadContentOffsetNotice;
+            await this.#writeModelEntry({ verbatim: packetAssistant.content, runId, loopId, turnId, sequence: errSeq++, folded: !hadEmissionError });
+        }
         // Zero ops is NOT an error to report — the model knows it emitted
         // nothing. Strike accounting (engine-internal) treats it as a
         // struck turn; the model just sees an empty packet next turn.
@@ -1251,6 +1280,7 @@ class Engine {
             source: "engine:rail",
             kind: "budget_overflow",
             folded: [...folded.entries()].map(([scheme, count]) => ({ scheme, count })),
+            level: "warn",
         });
     }
     // Wire projection lives in ./packet-wire.ts so Engine and
@@ -1291,6 +1321,7 @@ class Engine {
             const parsedRx = r.mimetype_rx === "application/json" ? JSON.parse(r.rx) : r.rx;
             return {
                 kind: "action_failure",
+                level: "error", // the derived error pointer is always an error — clients color off level (#276)
                 coordinate: `${r.loop_seq}/${r.turn_seq}/${r.sequence}`,
                 op: r.op,
                 target,
@@ -1378,6 +1409,18 @@ class Engine {
         }
         return written;
     }
+    // §exec-poll — EXEC `<0>` is turn-scoped: abort the run's open turn-scoped streams via their
+    // owning scheme (the same registry-routed abort the total reap uses). Called at each pre-turn
+    // before the turn's own spawns, so every open turn-scoped sub here is from a prior turn — it
+    // never survives into the subsequent turn. Fire-and-forget: the spawn finalizes async and its
+    // terminal output surfaces born-OPEN through the stream-delta path (§exec-stream).
+    async #reapTurnScopedStreams(runId) {
+        const open = await this.#db.find_open_turn_scoped_subscriptions_for_run.all({ run_id: runId });
+        for (const { id, scheme } of open) {
+            const handler = this.#schemes.get(scheme);
+            handler?.abortSubscription?.(id);
+        }
+    }
     // §environment-observation — exec streams as an instance of the ambient-observe machine:
     // each turn, emit each owned channel's unshown byte-delta as a foisted READ@200 row. Folded
     // while the channel streams; the terminal delta (channel closed) auto-OPENs. The cursor is the
@@ -1446,19 +1489,7 @@ class Engine {
     }
     async dispatch(context) {
         const { statement, sessionId, runId, loopId, turnId, sequence, origin, onDispatch } = context;
-        const schemeCtx = {
-            db: this.#db,
-            sessionId, runId, loopId, turnId,
-            writer: origin,
-            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),
-            executors: this.#executors,
-        };
+        const schemeCtx = this.#buildSchemeCtx({ sessionId, runId, loopId, turnId, origin });
         let result;
         let denial = this.#checkWritable(statement, origin);
         if (denial === null)
@@ -1466,6 +1497,12 @@ class Engine {
         if (denial !== null) {
             result = denial;
         }
+        else if (_a.#readFansOut(statement)) {
+            // READ honors FIND: a glob/folder scope or a matcher fans out to one log row per MATCH
+            // (its own writeLogs), returning early. A READ never proposes, so it bypasses the
+            // single-row path below. A bare entry, body-less, falls through to the direct read. #286
+            return await this.#handleReadFanout(statement, schemeCtx, { runId, loopId, turnId, sequence, origin, onDispatch });
+        }
         else {
             // SPEC §scheme-surface + plurnk-schemes#1: action-entry-as-outcome. Scheme-handler
             // exceptions become the action-entry's outcome (status 500), not a
@@ -1574,6 +1611,38 @@ class Engine {
         }
         return result;
     }
+    // op.look (#283) — resolve a READ and return its content WITHOUT writing a
+    // log_entries row: the client's off-run inspection primitive (LOOK → READ,
+    // invisible to the model). READ never mutates and never proposes, so this is
+    // dispatch's resolve path minus #writeLog. Runs on the client loop, so the
+    // human's inspection is never constrained by a model loop's flags. {§op-look}
+    async look(context) {
+        const { statement, sessionId, runId, loopId, origin = "client" } = context;
+        if (statement.op !== "READ")
+            throw new Error(`look resolves READ only; got ${statement.op}`);
+        // turnId is a write-time FK only — a look writes no row, so 0 (no turn) is inert.
+        const schemeCtx = this.#buildSchemeCtx({ sessionId, runId, loopId, turnId: 0, origin });
+        const denial = await this.#checkFlagsGate(statement, loopId);
+        if (denial !== null)
+            return denial;
+        return this.#run(this.#schemeNameOf(statement.target), statement, schemeCtx);
+    }
+    #buildSchemeCtx(ids) {
+        const { sessionId, runId, loopId, turnId, origin } = ids;
+        return {
+            db: this.#db,
+            sessionId, runId, loopId, turnId,
+            writer: origin,
+            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),
+            executors: this.#executors,
+        };
+    }
     // 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;
@@ -1864,17 +1933,19 @@ class Engine {
     #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).
+    // 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 `run://self` =
+    // self (ctx.runId); a name resolves within the session (404 if absent). §run-scheme,
     // §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 = target.kind === "url" ? (target.hostname ?? "") : ""; // §run-scheme — run is the AUTHORITY (run://<name>), not the path
+        if (name === "")
+            return { status: 400, error: "run:// fork requires a source run name or 'self' (run://self)" };
         let srcRunId = ctx.runId;
-        if (name !== "" && name !== ".") {
+        if (name !== "self") {
             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` };
@@ -1969,12 +2040,22 @@ class Engine {
             return await killable.kill(pathnameFromPath(path), statement.signal, ctx);
         }
         if (schemeName === "run") {
+            // Entry-path present → KILL a run-scope scratch ENTRY (delete it), self-only —
+            // NOT run cancellation. The authority (hostname) names the owner, the pathname the
+            // entry; only the path-ABSENT form (run://<name>) terminates the run-as-actor. §run-scheme
+            const entryPath = path.kind === "url" ? (path.pathname ?? "") : "";
+            if (entryPath !== "" && entryPath !== "/") {
+                const runHandler = this.#schemes.get("run");
+                return await runHandler.deleteEntry(statement, ctx);
+            }
             // terminate — abort any run by address; whoever holds it may end it.
-            // `.`/"" = self. cancelRun (→ Daemon.cancelDrain) aborts the run's signal
+            // `run://self` = 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 = path.kind === "url" ? (path.hostname ?? "") : ""; // §run-scheme — run is the AUTHORITY
+            if (name === "")
+                return { status: 400, error: "run:// kill requires a run name or 'self' (run://<name>)" };
             let runId = ctx.runId;
-            if (name !== "" && name !== ".") {
+            if (name !== "self") {
                 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` };
@@ -1991,6 +2072,101 @@ class Engine {
         const delResult = await handler.deleteEntry(pathnameFromPath(path), ctx);
         return { status: delResult.status };
     }
+    // Multi-file READ fan-out (SPEC §matcher-result — "the companion to FIND's survey"). A glob
+    // READ target resolves to MANY files; READ returns one log row per file that matches, each
+    // holding that file's matching lines. The matched SET is exactly FIND's survey (which files
+    // + where — matchLines), so we reuse the scheme's own find, then READ each matched file. One
+    // model command, N log rows — each row addresses its concrete file, so it folds/kills/re-READs
+    // on its own. The running sequence counter in runTurn advances by rowsWritten.
+    // A READ fans out (honors FIND) when it resolves to more than the single exact entry: a glob
+    // or folder scope, OR a matcher (which selects per-match within whatever the target resolved).
+    // A bare entry, body-less, is the one direct read. #286
+    static #readFansOut(statement) {
+        if (statement.op !== "READ")
+            return false;
+        if ("body" in statement && statement.body !== null)
+            return true; // a matcher → per-match fan-out
+        const t = statement.target;
+        const p = t === null ? "" : (t.kind === "url" ? t.pathname : t.raw);
+        return p.includes("*") || p.endsWith("/"); // glob/folder scope → fan out its contents
+    }
+    // Clone the READ onto one concrete match — the FIND already matched, so the per-match READ
+    // delivers content at the span: strip the body (no re-match) and set <L> to the span. A null
+    // span (body-less folder/glob fan-out) reads the whole entry. #286
+    static #retargetRead(statement, pathname, span) {
+        const t = statement.target;
+        const target = t !== null && t.kind === "url"
+            ? { ...t, pathname, raw: `${t.scheme}://${pathname}` }
+            : { ...t, raw: pathname };
+        const lineMarker = span !== null ? { marks: [span.lineStart, span.lineEnd] } : null;
+        return { ...statement, target: target, lineMarker, body: null };
+    }
+    async #handleReadFanout(statement, ctx, ids) {
+        const { runId, loopId, turnId, sequence, origin, onDispatch } = ids;
+        const schemeName = this.#schemeNameOf(statement.target);
+        const found = await this.#run(schemeName, { ...statement, op: "FIND" }, ctx);
+        const matches = found.matches ?? [];
+        // Find-less scheme, a matcher/scope error, or zero matches → a single row carrying the
+        // status, exactly like a non-fanned READ. The model sees the empty/failed result, not silence.
+        if (found.status !== 200 || matches.length === 0) {
+            const result = { status: found.status === 200 ? 204 : found.status };
+            const id = await this.#writeLog({ statement, result, runId, loopId, turnId, sequence, origin });
+            onDispatch?.(id);
+            return { ...result, rowsWritten: 1 };
+        }
+        // One READ row per MATCH — the span's source lines (or the whole entry for a body-less
+        // folder/glob). The match span is SOURCE LINES, so deliver via a raw line-slice — NOT the
+        // scheme's <L> (which is item-index for application/json, structural for xml). Read each
+        // distinct entry's content once, then line-slice per match. #286
+        const wholeByPath = new Map();
+        const fannedStatuses = [];
+        let written = 0;
+        for (const m of matches) {
+            let whole = wholeByPath.get(m.pathname);
+            if (whole === undefined) {
+                whole = await this.#run(schemeName, _a.#retargetRead(statement, m.pathname, null), ctx);
+                wholeByPath.set(m.pathname, whole);
+            }
+            const result = _a.#sliceMatch(whole, m.span);
+            const id = await this.#writeLog({ statement: _a.#retargetRead(statement, m.pathname, m.span), result, runId, loopId, turnId, sequence: sequence + written, origin });
+            onDispatch?.(id);
+            fannedStatuses.push(result.status);
+            written++;
+        }
+        return { status: 200, rowsWritten: written, fannedStatuses };
+    }
+    // Deliver one match: the whole entry (body-less, span null) or the source lines at the span —
+    // a RAW line-slice, so a structural mimetype (json item-index / xml) doesn't mis-slice a span
+    // that is, by construction, source line numbers (#286).
+    static #sliceMatch(whole, span) {
+        if (whole.status !== 200 || span === null)
+            return whole;
+        const sliced = LineMarkerOps.sliceLines(typeof whole.content === "string" ? whole.content : "", { marks: [span.lineStart, span.lineEnd] });
+        if (sliced.status !== 200)
+            return { status: sliced.status, error: sliced.error };
+        return { status: 200, content: sliced.text ?? "", mimetype: "text/markdown", startLine: sliced.startLine ?? span.lineStart };
+    }
+    // §model-entry — mirror a verbatim model emission back as an actionless `model` log row, so
+    // the model can finally SEE its own prior output (and reason through its own syntax errors).
+    // Born FOLDED by default (budget-neutral until OPENed); the turn-0 exemplar passes folded:false
+    // (born open — the one worked example the model orients on, thinning the grammar). text/vnd.plurnk.
+    async #writeModelEntry({ verbatim, runId, loopId, turnId, sequence, folded, origin = "model" }) {
+        const row = await this.#db.engine_insert_log_entry.get({
+            run_id: runId, loop_id: loopId, turn_id: turnId, sequence,
+            origin, source: null, op: "model", suffix: "", signal: null,
+            scheme: null, username: null, password: null, hostname: null, port: null,
+            pathname: null, params: null, fragment: null, lineMarker: null,
+            tx: "", mimetype_tx: "text/vnd.plurnk",
+            rx: JSON.stringify({ content: verbatim, mimetype: "text/vnd.plurnk" }),
+            mimetype_rx: "application/json",
+            status_rx: 200, tokens: this.#tokenize(verbatim), state: "resolved", outcome: null, attrs: "{}",
+        });
+        if (row === undefined)
+            throw new Error("Engine.#writeModelEntry: insert returned no row");
+        if (folded)
+            await this.#db.engine_fold_log_entry.run({ id: row.id });
+        return row.id;
+    }
     // PLAN — the model's reasoning op (the 11th op). An ordinary op: dispatched like any
     // other, logged, and broadcast to the client as a log entry — but a pure no-op for
     // state (PLAN ∉ MUTATING_OPS); its body serializes into the log row's tx, no effect.
@@ -2224,7 +2400,7 @@ class Engine {
         // it into the canonical pathname so known://x ≡ known:///x ≡ /x and the log keys identically to
         // the entry (/prompt/<loop>, /docs/x.md). A foreign web host (http://, unregistered) is NOT a
         // namespace: keep it in hostname. run:// is the one registered EXCEPTION — its authority IS the
-        // run selector (§run-scheme), and run:/// (self) must stay distinct from run://name, so Run.ts
+        // run selector (§run-scheme), and run://self must stay distinct from run://name, so Run.ts
         // folds the owner into the storage path itself, never here.
         const foldNs = scheme !== null && scheme !== "run" && this.#schemes.has(scheme);
         return {