@possumtech/rummy 2.0.1 → 2.1.0

package/src/plugins/prompt/README.md

@@ -14,3 +14,25 @@ Finds the latest `prompt://` entry in the turn_context rows. The mode
 attribute (available tool list) and optional `warn` attribute in ask
 mode. Falls back to the mode passed by the core if no prompt entry
 exists.
+
+## Archived prompts: the singular exception to invisibility
+
+`v_model_context.sql` filters archived entries out of the model's
+context — every scheme **except `prompt`**. Archived `prompt://`
+entries flow through with `effective_visibility = 'archived'` and
+their body suppressed (per `projected.body`'s visibility CASE). The
+plugin then renders the tag with full attributes (`path`,
+`visibility="archived"`, etc.) but empty body.
+
+The exception exists because the prompt is run identity: every other
+archived entry is recoverable by pattern search if the model ever
+needs it back, but the prompt is the question the run is answering.
+A model that loses sight of its prompt cannot honestly act. Keeping
+the archived prompt's path visible lets the model emit
+`<get path="prompt://N"/>` to promote it back if it archived
+prematurely (or step back to an earlier stage via
+`<update status="174">`).
+
+This is the only entry-type exception to the "archived = invisible"
+contract. New schemes that warrant similar treatment should be added
+explicitly here, not by accident.

package/src/plugins/prompt/prompt.js

@@ -1,3 +1,5 @@
+const SUMMARIZED_PROMPT_CHAR_CAP = 500;
+
 export default class Prompt {
 	#core;
 
@@ -7,28 +9,23 @@ export default class Prompt {
 		core.hooks.tools.onView(
 			"prompt",
 			(entry) => {
-				const limit = 500;
 				const full = entry.body;
-				if (full.length <= limit) return full;
-				return `${full.slice(0, limit)}\n[truncated — promote to see the complete prompt]`;
+				if (full.length <= SUMMARIZED_PROMPT_CHAR_CAP) return full;
+				return `${full.slice(0, SUMMARIZED_PROMPT_CHAR_CAP)}\n[truncated — promote to see the complete prompt]`;
 			},
 			"summarized",
 		);
 		core.on("turn.started", this.onTurnStarted.bind(this));
-		core.filter("assembly.user", this.assemblePrompt.bind(this), 300);
+		core.filter("assembly.user", this.assemblePrompt.bind(this), 225);
 	}
 
 	async onTurnStarted({ rummy, mode, prompt, isContinuation }) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
 
 		if (!isContinuation && prompt) {
-			// Each new prompt is the start of an independent state-machine
-			// cycle. Archive prior cycles' prompts and per-turn logs so they
-			// don't pollute Deployment-landing validation. Knowns, unknowns,
-			// and file entries persist (cross-cycle knowledge survives).
+			// New prompt = new cycle; archive prior cycle's prompts/logs (knowns/unknowns persist).
 			await store.archivePriorPromptArtifacts(runId, turn);
 
-			// prompt:// writable_by: ["plugin"] — explicit for clarity.
 			await store.set({
 				runId,
 				turn,
@@ -43,7 +40,7 @@ export default class Prompt {
 	}
 
 	async assemblePrompt(content, ctx) {
-		const { rows, contextSize, toolSet } = ctx;
+		const { rows, toolSet } = ctx;
 		const promptEntry = rows.findLast(
 			(r) => r.category === "prompt" && r.scheme === "prompt",
 		);
@@ -63,12 +60,7 @@ export default class Prompt {
 		let warn = "";
 		if (mode === "ask") warn = ' warn="File editing disallowed."';
 
-		// Surface the most recent prior-turn budget demotion as a
-		// `reverted="N"` attribute on <prompt>. Historical error
-		// entries sit in <log> but read as ambient noise; this signal
-		// is dynamic and always fresh — the model sees that its
-		// promotions last turn were reverted, in the same spot where
-		// it reads budget numbers.
+		// reverted="N" surfaces last turn's 413 demotion count next to budget numbers.
 		let reverted = "";
 		const priorTurn = ctx.turn - 1;
 		if (priorTurn >= 1) {

package/src/plugins/rm/rm.js

@@ -27,9 +27,12 @@ export default class Rm {
 		await ctx.entries.rm({ runId: ctx.runId, path: target });
 		if (ctx.projectRoot) {
 			const { unlink } = await import("node:fs/promises");
-			const { join } = await import("node:path");
+			const { isAbsolute, join } = await import("node:path");
+			const targetPath = isAbsolute(target)
+				? target
+				: join(ctx.projectRoot, target);
 			try {
-				await unlink(join(ctx.projectRoot, target));
+				await unlink(targetPath);
 			} catch (err) {
 				// File may already be absent — entry rm'd regardless.
 				if (err.code !== "ENOENT") throw err;

package/src/plugins/rm/rmDoc.md

@@ -3,11 +3,11 @@
 Example: <rm path="src/config.js"/>
 <!-- File removal. Simplest form. -->
 
-Example: <rm path="known://temp_*" preview/>
-<!-- Preview before deleting. Safety pattern for bulk operations. -->
+Example: <rm path="known://temp_*" manifest/>
+<!-- Optional: Manifest before deleting. Safety pattern for bulk operations. -->
 
 * Permanent. Prefer <set path="..." visibility="archived"/> to preserve for later retrieval
 <!-- Nudges toward archive over rm. Path attr included so the model sees a complete invocation shape, not a fragment. -->
 
-* `preview` shows what paths would be affected without performing the operation.
-<!-- Canonical preview teaching lives here — rm is the most intuitive 'check before committing' case. Model generalizes to cp/mv/get by analogy. Advanced uses (e.g. archive rediscovery via <get preview>) belong in persona/skill docs, not here. -->
+* `manifest` lists what paths would be affected without performing the operation.
+<!-- Canonical manifest teaching lives here — rm is the most intuitive 'check before committing' case. Model generalizes to cp/mv/get by analogy. Advanced uses (e.g. archive rediscovery via <get manifest>) belong in persona/skill docs, not here. -->

package/src/plugins/rpc/README.md

@@ -29,4 +29,5 @@ all registered tools.
 - `getRuns`, `getRun`
 
 ### Notifications
-- `run/state`, `run/progress`, `run/proposal`, `ui/render`, `ui/notify`, `stream/cancelled`
+- `run/changed` — pulse: an entry under this run changed; client reconciles via `getEntries(run, { since })`.
+- `ui/render`, `ui/notify`, `stream/cancelled`

package/src/plugins/rpc/rpc.js

@@ -24,10 +24,7 @@ export default class Rpc {
 			description: "Returns { methods, notifications } catalog.",
 		});
 
-		// --- Primitives (SPEC primitives) ---
-		// The client surface is a thin projection of the plugin API.
-		// Six verbs, each takes an object of entry-grammar params.
-		// Writer is fixed to "client"; permissions enforced per scheme.
+		// Primitives (SPEC #primitives); writer fixed to "client".
 
 		r.register("set", {
 			handler: async (params, ctx) => {
@@ -139,8 +136,9 @@ export default class Rpc {
 				return { ok: true, path };
 			},
 			description:
-				"Write an update:// entry carrying a turn's continuation/terminal " +
-				"signal. Not general — this is the lifecycle verb.",
+				"Write a status update at log://turn_N/update/<slug> carrying a " +
+				"turn's continuation/terminal signal. Not general — this is the " +
+				"lifecycle verb.",
 			params: {
 				run: "string — run alias",
 				body: "string — update text",
@@ -151,9 +149,7 @@ export default class Rpc {
 			requiresInit: true,
 		});
 
-		// Connection handshake. First call a client makes. Establishes
-		// the project identity for this connection and announces the
-		// server's protocol version.
+		// Connection handshake; project identity + protocol version.
 		r.register("rummy/hello", {
 			handler: async (params, ctx) => {
 				const { RUMMY_PROTOCOL_VERSION } = await import(
@@ -311,11 +307,18 @@ export default class Rpc {
 		r.register("getEntries", {
 			handler: async (params, ctx) => {
 				const runRow = await this.#resolveRun(params.run, ctx);
-				const { pattern = "*", bodyFilter = null } = params;
+				const {
+					pattern = "*",
+					bodyFilter = null,
+					since = null,
+					limit = null,
+					withBody = false,
+				} = params;
 				const rows = await ctx.projectAgent.entries.getEntriesByPattern(
 					runRow.id,
 					pattern,
 					bodyFilter,
+					{ since, limit },
 				);
 				return rows
 					.filter((e) => !params.scheme || e.scheme === params.scheme)
@@ -323,30 +326,43 @@ export default class Rpc {
 					.filter(
 						(e) => !params.visibility || e.visibility === params.visibility,
 					)
-					.map((e) => ({
-						path: e.path,
-						scheme: e.scheme,
-						state: e.state,
-						outcome: e.outcome,
-						visibility: e.visibility,
-						turn: e.turn,
-						tokens: e.tokens,
-						attributes:
-							typeof e.attributes === "string"
-								? JSON.parse(e.attributes)
-								: e.attributes,
-					}));
+					.map((e) => {
+						const row = {
+							id: e.id,
+							path: e.path,
+							scheme: e.scheme,
+							state: e.state,
+							outcome: e.outcome,
+							visibility: e.visibility,
+							turn: e.turn,
+							tokens: e.tokens,
+							attributes:
+								typeof e.attributes === "string"
+									? JSON.parse(e.attributes)
+									: e.attributes,
+						};
+						if (withBody) row.body = e.body;
+						return row;
+					});
 			},
 			description:
 				"List entries matching a pattern. Read-only — no promotion. " +
-				"Optional filters: scheme, state, visibility, bodyFilter.",
+				"Optional filters: scheme, state, visibility, bodyFilter. " +
+				"Pass `withBody: true` to include `body` on each row (omitted by default to keep pulse-reconcile traffic lean). " +
+				"For incremental sync after a `run/changed` pulse, pass `since` (last seen entry id); " +
+				"use `limit` to chunk catch-up.",
 			params: {
 				run: "string — run alias",
 				pattern: "string? — glob pattern (default '*')",
 				scheme: "string? — filter by scheme (e.g. 'file')",
 				state: "string? — filter by state",
 				visibility: "string? — filter by visibility",
-				bodyFilter: "string? — narrow pattern matches by body content",
+				bodyFilter:
+					"string? — filter rows by content of body (substring/glob; NOT for body inclusion — see withBody)",
+				withBody:
+					"boolean? — include `body` field on each returned row (default false)",
+				since: "number? — only entries with id > since (insertion-ordered)",
+				limit: "number? — cap result count",
 			},
 			requiresInit: true,
 		});
@@ -436,9 +452,10 @@ export default class Rpc {
 
 		// --- Notifications ---
 
-		r.registerNotification("run/state", "Turn state update.");
-		r.registerNotification("run/progress", "Turn status.");
-		r.registerNotification("run/proposal", "Proposal awaiting resolution.");
+		r.registerNotification(
+			"run/changed",
+			"Pulse: an entry under this run changed. Query with `getEntries(run, { pattern, since })` to reconcile.",
+		);
 		r.registerNotification(
 			"stream/cancelled",
 			"Server-initiated stream cancellation.",
@@ -446,8 +463,7 @@ export default class Rpc {
 		r.registerNotification("ui/render", "Streaming output.");
 		r.registerNotification("ui/notify", "Toast notification.");
 
-		// Auto-dispatch: any registered tool is callable via RPC.
-		// Checked at request time — no timing dependency on plugin load order.
+		// Any registered tool is callable via RPC; resolved at request time.
 		r.setToolFallback(hooks, buildRunContext, dispatchTool);
 	}
 
@@ -464,18 +480,14 @@ export default class Rpc {
 	async #dispatchSet(params, ctx) {
 		if (!params.path) throw new Error("set: path is required");
 
-		// run:// is the lifecycle surface. A set to a brand-new run://
-		// alias starts a run loop; a state transition cancels or resolves.
+		// run:// = lifecycle surface (start run, cancel, resolve).
 		if (params.path.startsWith("run://")) {
 			return await this.#dispatchRunSet(params, ctx);
 		}
 
 		const runRow = await this.#resolveRun(params.run, ctx);
 
-		// State transition on an existing proposed entry → route through
-		// AgentLoop.resolve, which applies scheme-specific side effects
-		// (patch application for set://, file removal for rm://, stream
-		// setup for sh:// / env://, etc.).
+		// State transitions on proposed entries → AgentLoop.resolve for scheme-specific effects.
 		if (params.state && !params.append && !params.pattern) {
 			const current = await ctx.projectAgent.entries.getState(
 				runRow.id,
@@ -521,10 +533,7 @@ export default class Rpc {
 	async #dispatchRunSet(params, ctx) {
 		let alias = params.path.slice("run://".length);
 
-		// Empty alias on a new-run set → synthesize ${model}_${epoch}.
-		// Matches AgentLoop.#generateAlias so server- and client-initiated
-		// runs share one naming scheme. Clients that want a specific name
-		// pass it in the path; anonymous starts get the synthesized one.
+		// Empty alias → ${model}_${epoch}; mirrors AgentLoop.#generateAlias.
 		if (!alias) {
 			const { attributes: attrs = {} } = params;
 			if (!attrs.model) {
@@ -580,9 +589,7 @@ export default class Rpc {
 				fork: attrs.fork,
 			};
 			const { body = "" } = params;
-			// Fire-and-forget: client watches state via entry notifications.
-			// ProjectAgent exposes .ask/.act wrappers over AgentLoop#run; route
-			// by mode rather than calling the private loop directly.
+			// Fire-and-forget; client watches state via entry notifications.
 			const kickoff =
 				mode === "act"
 					? ctx.projectAgent.act(
@@ -605,10 +612,7 @@ export default class Rpc {
 			return { ok: true, alias };
 		}
 
-		// Existing run + fork=true: create a child run synchronously so we
-		// can return the child alias, then kick off the loop against it.
-		// fork needs a brand-new run row with parent_run_id set; inject()
-		// would just add another prompt to the parent.
+		// fork=true → new child run with parent_run_id; inject() would only add a prompt to parent.
 		const attrs = params.attributes ? params.attributes : {};
 		if (attrs.fork === true) {
 			const { mode } = attrs;

package/src/plugins/set/README.md

@@ -15,7 +15,7 @@ SEARCH/REPLACE edits, and pattern updates.
 - **Category**: `logging`
 - **Handler**: Routes based on attributes:
   - `blocks` or `search` — SEARCH/REPLACE edit via `processEdit`.
-  - `preview` — pattern preview (dry run).
+  - `manifest` — pattern manifest (lists matches without performing the set).
   - Scheme path — direct upsert at status 200.
   - File path — produces status 202 (proposed) with unified diff patch.
   - Glob/filter — bulk update via `updateBodyByPattern`.
@@ -31,3 +31,7 @@ the merge conflict block when a SEARCH/REPLACE was performed.
 - **Heuristic fallback**: On literal failure, fuzzy matching with warnings.
 - **Patch generation**: `generatePatch` produces unified diff for client display.
 - File writes are always status 202 (proposed); scheme writes resolve immediately.
+- **`proposal.content` filter** — when the client accepts a proposed
+  set, this plugin overrides the resolved body to the body it
+  already staged on the audit entry (rather than whatever literal
+  body the client passed through `resolve`).

package/src/plugins/set/set.js

@@ -79,12 +79,7 @@ export default class Set {
 			}
 		}
 		const turn = (await db.get_run_by_id.get({ id: runId })).next_turn;
-		// Preserve the file entry's current visibility — a <get>
-		// earlier in the run may have promoted it. Updating the
-		// body without specifying visibility falls through to
-		// the data-category default ("summarized") and wipes
-		// the promotion, making the model re-get the file next
-		// turn (then cycle-strike out).
+		// Preserve current visibility; default would wipe an earlier <get>'s promotion.
 		const existingState = await entries.getState(runId, attrs.path);
 		await entries.set({
 			runId,
@@ -94,9 +89,13 @@ export default class Set {
 			visibility: existingState?.visibility,
 		});
 		if (projectRoot) {
-			const { writeFile } = await import("node:fs/promises");
-			const { join } = await import("node:path");
-			await writeFile(join(projectRoot, attrs.path), patched).catch(() => {});
+			const { writeFile, mkdir } = await import("node:fs/promises");
+			const { dirname, isAbsolute, join } = await import("node:path");
+			const targetPath = isAbsolute(attrs.path)
+				? attrs.path
+				: join(projectRoot, attrs.path);
+			await mkdir(dirname(targetPath), { recursive: true });
+			await writeFile(targetPath, patched);
 		}
 		if (isNewFile && projectId) {
 			await File.setConstraint(db, projectId, attrs.path, "active");
@@ -112,24 +111,22 @@ export default class Set {
 		const rawSummary = typeof attrs.summary === "string" ? attrs.summary : null;
 		const summaryText = rawSummary ? rawSummary.slice(0, 80) : null;
 
-		// Invalid visibility value on a body-less set: reject with an
-		// error instead of falling through to the write path. Without
-		// this guard, a typo like visibility="promoted" (pre-migration
-		// terminology) silently body-wiped the target — the fidelity
-		// regression that cost us multiple demo runs.
+		// Reject invalid visibility on body-less set; otherwise a typo silently wipes the body.
 		if (
 			!entry.body &&
 			attrs.path &&
 			attrs.visibility !== undefined &&
 			!visibilityAttr
 		) {
-			await rummy.hooks.error.log.emit({
-				store,
+			await store.set({
 				runId,
 				turn,
 				loopId,
-				message: `Invalid visibility "${attrs.visibility}" on <set path="${attrs.path}"/>. Use visibility="visible|summarized|archived".`,
-				status: 400,
+				path: entry.resultPath,
+				body: `Invalid visibility "${attrs.visibility}" on <set path="${attrs.path}"/>. Use visibility="visible|summarized|archived".`,
+				state: "failed",
+				outcome: "validation",
+				attributes: { path: attrs.path },
 			});
 			return;
 		}
@@ -187,8 +184,8 @@ export default class Set {
 		// Edit: sed patterns or SEARCH/REPLACE blocks
 		if (attrs.blocks || attrs.search != null) {
 			await this.#processEdit(rummy, entry, attrs);
-		} else if (attrs.preview && attrs.path) {
-			// Preview
+		} else if (attrs.manifest && attrs.path) {
+			// Manifest: list paths and token costs without performing the operation.
 			const matches = await store.getEntriesByPattern(
 				runId,
 				attrs.path,
@@ -202,7 +199,7 @@ export default class Set {
 				attrs.path,
 				attrs.body,
 				matches,
-				{ preview: true, loopId },
+				{ manifest: true, loopId },
 			);
 			return;
 		} else {
@@ -262,8 +259,7 @@ export default class Set {
 					{ loopId },
 				);
 			} else {
-				// Direct scheme write (known://, unknown://, etc.)
-				// Same result shape as file writes — diff against existing.
+				// Direct scheme write; same diff-against-existing shape as file writes.
 				const existing = await store.getBody(runId, target);
 				const oldContent = existing === null ? "" : existing;
 				const newContent = entry.body;
@@ -280,8 +276,7 @@ export default class Set {
 					path: target,
 					body: newContent,
 					state: "resolved",
-					// Scheme writes default to promoted — the model wrote it, so
-					// it's material unless they explicitly demote/archive.
+					// Scheme writes default visible; the model wrote it.
 					visibility: visibilityAttr ? visibilityAttr : "visible",
 					attributes: summaryText ? { summary: summaryText } : null,
 					loopId,
@@ -340,8 +335,7 @@ export default class Set {
 
 	summary(entry) {
 		if (!entry.body) return "";
-		// Preserve SEARCH/REPLACE merge blocks intact — truncating them
-		// drops the before/after the model needs to recognize its edit.
+		// Preserve SEARCH/REPLACE blocks intact; truncation strips before/after the model needs.
 		if (/<<<<<<< SEARCH[\s\S]*>>>>>>> REPLACE/.test(entry.body)) {
 			return entry.body;
 		}
@@ -370,10 +364,7 @@ export default class Set {
 
 		for (const match of matches) {
 			if (match.scheme === null) {
-				// Bare file path — apply the edit immediately against the
-				// match body so the log carries a concrete before/after
-				// merge. #materializeRevisions still runs at turn-end to
-				// consolidate the set:// proposal for client acceptance.
+				// Bare file: apply edit immediately so log carries before/after merge.
 				const canonicalPath = `set://${match.path}`;
 				const revision = Set.#buildRevision(attrs);
 				const existingAttrs = await rummy.getAttributes(canonicalPath);
@@ -533,8 +524,7 @@ export default class Set {
 		}
 	}
 
-	// `replace` attr is optional in search/replace form — absence means
-	// "delete the match"; normalize to empty string at this boundary.
+	// Missing `replace` = delete the match; normalize to empty string.
 	static #resolveReplace(attrs) {
 		return attrs.replace === undefined ? "" : attrs.replace;
 	}

package/src/plugins/set/setDoc.md

@@ -18,5 +18,5 @@ Example: <set path="src/config.js">s/port = 3000/port = 8080/g;s/We're almost do
 Example: <set path="example.md">Full file content here</set>
 <!-- Create: body contents are entire file. -->
 
-* YOU MUST NOT use <sh></sh> or <env></env> to list, create, read, or edit files — use <get></get> and <set></set>
+YOU MUST NOT use <sh></sh> or <env></env> to list, create, read, or edit files — use <get></get> and <set></set>
 <!-- Reinforces at the decision point — model reading setDoc for file ops sees the prohibition here, not just buried in shDoc/envDoc which it may not be reading. -->

package/src/plugins/sh/README.md

@@ -24,7 +24,8 @@ record, one data payload:
 - **Data channels**: `sh://turn_N/{slug}_1` (stdout), `sh://turn_N/{slug}_2`
   (stderr) — scheme=`sh`, category=`data`. Created at status=102 on
   proposal acceptance, grow via the `stream` RPC, transition to 200/500
-  via `stream/completed`. Render inside the `<context>` block as `<sh>`.
+  via `stream/completed`. Render inside `<visible>` as `<sh>` when
+  promoted; listed in `<summarized>` otherwise.
 
 The `sh` scheme exists **only** for the data channels. The proposal/log
 entry itself is in the unified `log://` namespace along with every

package/src/plugins/sh/sh.js

@@ -1,4 +1,4 @@
-import { logPathToDataBase } from "../helpers.js";
+import { logPathToDataBase, streamSummary } from "../helpers.js";
 import docs from "./shDoc.js";
 
 const LOG_ACTION_RE = /^log:\/\/turn_\d+\/(\w+)\//;
@@ -8,11 +8,7 @@ export default class Sh {
 
 	constructor(core) {
 		this.#core = core;
-		// `sh` scheme holds the streamed stdout/stderr payload — that's
-		// data the model reads, not an audit record. The log entry at
-		// log://turn_N/sh/{slug} (scheme=log, category=logging) is the
-		// audit record; it lives in a separate namespace by design.
-		// See SPEC §streaming_entries and the scheme/category invariant.
+		// data scheme = streamed stdout/stderr; audit lives in log://. SPEC #streaming_entries.
 		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
 		core.on("visible", this.full.bind(this));
@@ -53,9 +49,7 @@ export default class Sh {
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId, loopId } = rummy;
-		// Proposal at 202 with the command as summary and empty body — the
-		// body fills in on accept (log message about the action). Data
-		// entries with stdout/stderr are created on accept in resolve().
+		// 202 with command summary, empty body; stdout/stderr entries created on accept.
 		await store.set({
 			runId,
 			turn,
@@ -71,7 +65,7 @@ export default class Sh {
 		return `# sh ${entry.attributes.command}\n${entry.body}`;
 	}
 
-	summary() {
-		return "";
+	summary(entry) {
+		return streamSummary("sh", entry);
 	}
 }

package/src/plugins/sh/shDoc.md

@@ -6,8 +6,8 @@ Example: <sh>npm install express</sh>
 Example: <sh>npm test</sh>
 <!-- Test execution. Another common side-effect action. -->
 
-* YOU MUST NOT use <sh></sh> to read, create, or edit files — use <get></get> and <set></set>
+YOU MUST NOT use <sh></sh> to read, create, or edit files — use <get></get> and <set></set>
 <!-- Forces file operations through the entry system. -->
 
-* YOU MUST use <env></env> for commands without side effects
+YOU MUST use <env></env> for commands without side effects
 <!-- Reinforces the env/sh split. Read = env, mutate = sh. -->

package/src/plugins/stream/README.md

@@ -16,12 +16,13 @@ A streaming action lives in **two namespaces** by design:
   `{action}://turn_N/{slug}_2`, ... — scheme=`{action}` (sh, env, ...),
   category=`data`. Created at status=102 on proposal acceptance. Grow
   via `stream`; terminal via `stream/completed` / `stream/aborted` /
-  `stream/cancel`. Render inside `<context>`.
+  `stream/cancel`. Render inside `<visible>` (or `<summarized>` if
+  demoted).
 
-The stream RPC `path` param is always the **log-entry path** (that's
-what clients receive on `run/proposal`). The server derives the data
-base path internally via `logPathToDataBase`. See
-[scheme_category_split](#scheme_category_split).
+The stream RPC `path` param is always the **log-entry path** (the
+`log://...` path the client discovers via `getEntries` after a
+`run/changed` pulse). The server derives the data base path internally
+via `logPathToDataBase`. See [scheme_category_split](#scheme_category_split).
 
 ## RPC Methods
 

package/src/plugins/stream/stream.js

@@ -1,22 +1,6 @@
 import { logPathToDataBase } from "../helpers.js";
 
-/**
- * Stream plugin — generic streaming entry infrastructure.
- *
- * Receives chunks from the client (or any producer) and appends them to
- * existing data entries. Producers (sh/env handlers) create the data
- * entries at status=102 on proposal acceptance; this plugin handles the
- * subsequent append + terminal-status transition via two RPC methods.
- *
- * RPC `path` param is the **log-entry path** (log://turn_N/{action}/{slug}
- * — that's what the client sees on `run/proposal`). Channels live under
- * the producer scheme ({action}://turn_N/{slug}_N) for a clean
- * data-vs-logging namespace split; this plugin derives the data base from
- * the log path on every RPC call.
- *
- * Not a model-facing tool. No scheme, no tooldoc, no dispatch handler.
- * Pure RPC plumbing that any streaming-producer plugin can leverage.
- */
+// RPC plumbing that appends/terminates streaming data entries; see plugin README.
 export default class Stream {
 	#core;
 
@@ -25,9 +9,7 @@ export default class Stream {
 		const hooks = core.hooks;
 		const r = hooks.rpc.registry;
 
-		// stream: append a chunk to a streaming entry.
-		// Entry path is constructed as `${path}_${channel}` per the Unix FD
-		// convention (1=stdout, 2=stderr, higher=other producer channels).
+		// stream: append chunk; channel = Unix FD (1=stdout, 2=stderr).
 		r.register("stream", {
 			handler: async (params, ctx) => {
 				if (!params.run) throw new Error("run is required");
@@ -67,8 +49,7 @@ export default class Stream {
 			requiresInit: true,
 		});
 
-		// stream/completed: transition all data channels for this producer
-		// to their terminal status and finalize the log entry body.
+		// stream/completed: terminal status on all channels + finalize log body.
 		r.register("stream/completed", {
 			handler: async (params, ctx) => {
 				if (!params.run) throw new Error("run is required");
@@ -107,8 +88,7 @@ export default class Stream {
 					});
 				}
 
-				// Update the log entry body with final stats. Keep it terse —
-				// one line summarizing exit code, duration, and channel sizes.
+				// One-line final stats for the log entry body.
 				const logEntry = await store.getAttributes(runId, params.path);
 				let command = "";
 				if (logEntry?.command) command = logEntry.command;
@@ -138,11 +118,7 @@ export default class Stream {
 			requiresInit: true,
 		});
 
-		// stream/aborted: client-initiated cancellation. Transitions all data
-		// channels to status 499 (Client Closed Request — the de-facto HTTP
-		// status for client-terminated requests) and rewrites the log entry
-		// body to note the abort. Shape mirrors stream/completed for client
-		// symmetry: same run/path addressing, same channel sweep.
+		// stream/aborted: client cancellation; channels → 499; mirrors stream/completed.
 		r.register("stream/aborted", {
 			handler: async (params, ctx) => {
 				if (!params.run) throw new Error("run is required");
@@ -211,12 +187,7 @@ export default class Stream {
 			requiresInit: true,
 		});
 
-		// stream/cancel: server-initiated cancellation. Any client (or
-		// internal server code) can cancel a streaming producer — the server
-		// transitions channels to 499 immediately and pushes a
-		// stream/cancelled notification so connected clients can kill their
-		// local processes. Also serves as stale 102 cleanup: if the client
-		// died mid-stream, call stream/cancel to mark orphaned entries terminal.
+		// stream/cancel: server-initiated; pushes stream/cancelled notification; cleans stale 102s.
 		r.register("stream/cancel", {
 			handler: async (params, ctx) => {
 				if (!params.run) throw new Error("run is required");