@plurnk/plurnk-service 0.55.0 → 0.57.0

package/dist/core/Engine.js

@@ -9,7 +9,7 @@ import GitState from "./git-state.js";
 import Fork from "./fork.js";
 import RunCap from "./run-cap.js";
 import { teachingLine, docsExcludeSet } from "./teaching.js";
-import { readPacketInject } from "./packet-inject.js";
+import { readPacketInject, readSystemPolicy, readProjectPolicy } from "./packet-inject.js";
 import SessionSettings from "./session-settings.js";
 import { decodePathParens } from "./path-decode.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.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,11 @@ 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 ?? "{}"),
         };
     }
     #pushTelemetry(sessionId, loopId, event) {
@@ -336,26 +341,25 @@ 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] ?? ""}`);
+    // 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,
+    // clamping out-of-range offsets to the content's end.
+    #offsetToLineColumn(content, offset) {
+        const cps = Array.from(content);
+        const clamped = Math.max(0, Math.min(offset, cps.length));
+        let line = 1;
+        let column = 0;
+        for (let i = 0; i < clamped; i++) {
+            if (cps[i] === "\n") {
+                line++;
+                column = 0;
+            }
+            else {
+                column++;
+            }
         }
-        return slice.join("\n");
+        return { line, column };
     }
     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 = [];
@@ -525,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
@@ -604,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, autoReadAgents } = 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).
@@ -633,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: {
@@ -655,33 +669,25 @@ 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`);
                 }
-            }
-            // #268 — auto-READ the configured AGENTS file(s) into THIS first model turn. Env-driven
-            // (PLURNK_AGENTS_AUTO / PLURNK_AGENTS_FILES), overridable per-session by autoReadAgents; the
-            // matching files are auto-PICKed into membership at session setup (envelope). The model sees
-            // only the READ — a normal file:/// member READ, read-write so it edits the scratchpad back.
-            const { auto: agentsAuto, files: agentsFiles } = SessionSettings.resolveAgentsAutoload(autoReadAgents);
-            if (agentsAuto && runFirstLoop) { // #269 — run-once, the run's first loop
-                for (const file of agentsFiles) {
-                    const pathname = file.startsWith("/") ? file : `/${file}`;
-                    const member = await this.#db.crud_get_member_sig.get({ session_id: sessionId, scheme: null, pathname });
-                    if (member === undefined)
-                        continue; // absent / non-git session → not a member → skip
-                    const agentsRead = {
-                        op: "READ", suffix: "", signal: null, lineMarker: null,
-                        target: {
-                            kind: "url", raw: `file://${pathname}`, scheme: "file",
-                            username: null, password: null, hostname: null, port: null,
-                            pathname, params: {}, fragment: null,
-                        },
-                        body: null, position: { line: 1, column: 1 },
+                // §run-scheme — Manifest(run) = session-scope ∪ THIS run's run-scope. Foist the
+                // 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 });
+                const scratch = selfRun === undefined ? 0 : (await this.#db.engine_run_scratch_count.get({ session_id: sessionId, owner_prefix: `/${selfRun.name}/*` }))?.entries ?? 0;
+                if (scratch > 0) {
+                    const runFind = {
+                        op: "FIND", suffix: "", signal: 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: agentsRead, sessionId, runId, loopId, turnId,
-                        sequence: nextActionIndex, origin: "plurnk", onDispatch,
-                    });
+                    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
@@ -705,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
@@ -740,17 +758,19 @@ 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,
-                finish_reason: "budget_hard_stop", model: provider.model,
+                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 };
         }
         const modelMessages = this.#packetToWireMessages(requestPacket);
-        // maxTokens = remaining context window (loop policy, plurnk-providers#10).
-        // 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); // provider.contextSize, the immutable identity, read by the budget — §provider-surface-identity
-        const maxTokens = genCeiling === null ? undefined : Math.max(1, genCeiling - requestPacket.tokens);
+        // No decode cap. Our budget governs the TRANSMISSION packet (the grinder folds
+        // the input under the ceiling); the model's decode — reasoning + emission — is
+        // out of band, owned by the provider's own context window. Deriving a maxTokens
+        // from our budget conflated the two and guillotined a reasoning model's
+        // out-of-band thinking as the packet filled (`ceiling - packet` → near-zero
+        // decode → finish=length mid-reasoning → no emission → strike spiral). The
+        // provider enforces its physical wall on its own.
         let response;
         // #249 — plugin attribution tags onto the per-turn generate() wire. Value is the
         // active-plugin set (placeholder); real per-turn grounding is deferred.
@@ -761,7 +781,7 @@ class Engine {
         // #249 — session-stable frontend id, forwarded as Plurnk-Client by the plurnk provider only.
         const { client } = await SessionSettings.read(this.#db, sessionId);
         try {
-            response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens, attributions: attributions.length > 0 ? attributions : undefined, client: client ?? undefined }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired §attribution-plurnk-namespace-reserved §client-telemetry
+            response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), attributions: attributions.length > 0 ? attributions : undefined, client: client ?? undefined }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired §attribution-plurnk-namespace-reserved §client-telemetry
         }
         catch (err) {
             // Every provider error surfaces as telemetry (the client/model sees the cause). #256:
@@ -770,8 +790,11 @@ class Engine {
             // accepted: fall through as an empty no-op turn so the strike rail retries. Every other
             // kind (rate_limit, network_failure, unauthorized, …) is terminal — telemetry'd, then
             // propagated to end the loop (rather than only the opaque loop.run rejection).
+            // NOTE (providers 0.19.0 / #275): only the CONSTRAINED path still throws grammar_unenforced.
+            // 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 = {
@@ -801,14 +824,31 @@ class Engine {
         // 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 ?? []) {
+        // Parse errors are LOG ITEMS now (§telemetry — one budget surface): each failed-to-parse
+        // emission records an actionless `error` row below, after the turn's dispatched ops are
+        // sequenced (see the parse-error log write past the dispatch loop). The errors section
+        // derives a pointer to it from log≥400, uniform with action_failure.
+        // 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. 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: "grammar",
-                kind: "parse_error",
-                message,
-                position: { type: "content-offset", line, column },
-                snippet: this.#extractSnippet(packetAssistant.content, line, 2),
-                parserSource: source,
+                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 } }
+                    : {}),
             });
         }
         const opsCount = packetAssistant.ops.length;
@@ -822,19 +862,23 @@ class Engine {
         // §grinder-strike-coupling): the loop continues, the model sees the steering hint not the strike
         // count, and a non-resolver spins out to the engine's 500.
         let steerStruck = false;
-        // Premature terminate: a SEND[200] while the run still holds a live stream/spawn — the model
-        // declared done with work running. Downgrade the 200 to 102 so it dispatches as a continue (its
-        // body is preserved, not discarded) and steer; the stream's own conclusion or a KILL is the exit.
+        // Premature terminate: a SEND[200] while the run still holds a live thing — an open stream/spawn
+        // OR a non-terminal child run (§run-lifecycle: children and streams are the same kind of "live
+        // thing a run holds"). The model declared done with work running. Downgrade the 200 to 102 so it
+        // dispatches as a continue (its body is preserved, not discarded) and steer; the stream's/child's
+        // own conclusion (the wake edge) or a KILL is the exit.
         if (sendOp?.signal === 200) {
             const openSubs = await this.#db.find_open_subscriptions_for_run.all({ run_id: runId });
             const execHandler = this.#schemes.get("exec");
-            if (openSubs.length > 0 || execHandler?.hasActiveSpawns?.(runId) === true) {
+            const liveChild = await this.#db.engine_run_has_live_child.get({ run_id: runId });
+            if (openSubs.length > 0 || execHandler?.hasActiveSpawns?.(runId) === true || liveChild !== undefined) {
                 sendOp.signal = TURN_STATUS_IMPLICIT_CONTINUE; // 102 — downgraded, no longer a terminal
                 steerStruck = true;
                 this.#pushTelemetry(sessionId, loopId, {
                     source: "engine:rail",
                     kind: "premature_terminate",
-                    message: "Attempted termination with active streams. Terminate with 202 to hibernate until stream completion, KILL(path) with 200 again to clean up, or 499 to fail.",
+                    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",
                 });
             }
         }
@@ -852,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.
@@ -865,8 +910,12 @@ 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
+            // provider normalized). Stored verbatim, unenforced; the service never reads a field.
+            meta: JSON.stringify(response.meta ?? {}),
         });
         // Dispatch model ops starting at nextActionIndex (continues the
         // turn's running counter after any pre-model writes).
@@ -890,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
@@ -908,8 +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 = rowSeq; // after every dispatched row, including a multi-file READ's fan-out
+        for (const { message, line, column, source } of parseErrors ?? []) {
+            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",
+                // 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.
@@ -1032,15 +1117,23 @@ class Engine {
         // peer sections (unbundled). The budget section carries its {{tokensFree}}
         // placeholders here; they resolve below once the assembled total is known.
         const inject = await readPacketInject(); // #240 — operator section, per-turn, fail-hard on a broken path
+        const sessionRoot = (await this.#db.envelope_get_session.get({ id: sessionId }))?.project_root ?? null;
+        const systemPolicy = await readSystemPolicy(); // ~/.plurnk/AGENTS.md (or PLURNK_POLICY)
+        const projectPolicy = await readProjectPolicy(sessionRoot); // <projectRoot>/AGENTS.md (or PLURNK_PROJECT)
         const defaults = [
             { name: "definition", slot: "system", header: null, content: system_definition, tokens: 0 },
             { name: "tools", slot: "system", header: null, content: tools.join("\n"), tokens: 0 }, // titleless — the examples flow on from plurnk.md (definition) directly above
             { name: "schemes", slot: "system", header: "Plurnk System Schemes", content: this.#schemes.teach(), tokens: 0 },
             ...(inject !== null ? [{ name: "inject", slot: "system", header: "Plurnk Operator Notes", content: inject, tokens: 0 }] : []),
-            { name: "log", slot: "system", header: "Plurnk System Log", content: PacketWire.renderLog(log, countTokens), tokens: 0 },
+            // policy: the client's privileged rules — ~/.plurnk/AGENTS.md (system) then <root>/AGENTS.md (project) — below grammar/tools/schemes, above budget-the-law. AGENTS is POLICY here, never a curatable READable entry. Empty content ⇒ section omitted.
+            { name: "system-policy", slot: "system", header: "Plurnk System Policy", content: systemPolicy ?? "", tokens: 0 },
+            { name: "project-policy", slot: "system", header: "Project Policy", content: projectPolicy ?? "", tokens: 0 },
+            // budget at the BOTTOM of the SYSTEM slot — budget is LAW (the ceiling is a hard constraint the model must obey), so it belongs in the lean privileged zone, not as user-slot status.
+            { name: "budget", slot: "system", header: "Plurnk System Budget", content: budgetReadout, tokens: 0 },
             { name: "prompt", slot: "user", header: "Plurnk System User Prompt", content: prompt, tokens: 0 },
-            { name: "budget", slot: "user", header: "Plurnk System Budget", content: budgetReadout, tokens: 0 },
             { name: "errors", slot: "user", header: "Plurnk System Errors", content: PacketWire.renderErrors(telemetryErrors), tokens: 0 },
+            // log in the USER slot, low: short-term memory (data, not rules) at the action point, so the model consults its history instead of skimming it. git follows it as workspace status — not law, so it stays in user, never system.
+            { name: "log", slot: "user", header: "Plurnk System Log", content: PacketWire.renderLog(log, countTokens), tokens: 0 },
             { name: "git", slot: "user", header: "Plurnk System Git Status", content: PacketWire.renderGit(gitStatus), tokens: 0 },
             { name: "requirements", slot: "user", header: "Plurnk System Requirements", content: baseRequirements, tokens: 0 },
         ];
@@ -1187,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
@@ -1227,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,
@@ -1314,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
@@ -1382,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)
@@ -1402,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
@@ -1510,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;
@@ -1800,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` };
@@ -1894,8 +2029,9 @@ class Engine {
         const schemeName = this.#schemeNameOf(path);
         if (schemeName === null)
             return { status: 400, error: "KILL target must be a URL path with a scheme" };
-        if (schemeName === "log")
-            return { status: 405, error: "log:/// is append-only; KILL must bounce" };
+        // KILL on log:/// erases the log row(s) — the model's DB-storage curation lever
+        // (plurnk.md:36, :98), routed to Log.kill below via the killable.kill path. The old
+        // "append-only" 405 forbade what the grammar requires; FOLD only collapses the render.
         // Process-KILL: any scheme whose handler exposes kill() aborts a live stream — the
         // exec handler, registered as "exec" + under every runtime tag (sh/node), so a tag-
         // addressed stream (sh:///l/t/s) routes here, not to deleteEntry. §exec
@@ -1904,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` };
@@ -1926,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.
@@ -2159,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 {