@arnilo/prism 0.2.9 → 0.3.1

package/docs/antigravity-agent.md

@@ -0,0 +1,207 @@
+# Antigravity delegated agent
+
+## What it does
+
+`@arnilo/prism-antigravity-agent` provides a delegated agent adapter for the official [Google Antigravity CLI (`agy`)](https://github.com/google/antigravity). It enables Prism applications to delegate complex, multi-step coding tasks to an authenticated Antigravity CLI runner while exposing host-owned Prism tools, resources, and prompts over a per-run Model Context Protocol (MCP) server.
+
+The package handles the end-to-end delegated execution lifecycle:
+- Spawns the official headless CLI (`agy --agent <name> --workspace <dir>`) as a managed subprocess.
+- Starts a run-bound loopback HTTP MCP server (`http://127.0.0.1:<port>/mcp`) authorized with an ephemeral Bearer token.
+- Writes ephemeral workspace configuration (`.agents/mcp_config.json` and custom agent instructions) with automatic backup and fail-safe restoration.
+- Parses the CLI's NDJSON output stream and projects steps into standard Prism `AgentEvent`s and [AG-UI](ag-ui.md) timeline activities.
+- Persists and resumes multi-turn conversations via `--conversation <id>`.
+- Provides an optional `createAntigravityDelegationTool` for Prism [supervisors](supervisors.md) and orchestrating agents.
+
+Prism does not manage Google OAuth tokens, cookies, or credentials; the host environment owns the official `agy` binary and interactive authentication state (`agy login` / Google AI Pro subscription).
+
+## When to use it
+
+Use `@arnilo/prism-antigravity-agent` when:
+- You want to delegate autonomous coding sessions to Google Antigravity while exposing host-owned Prism tools and capabilities via MCP.
+- You need structured event streaming, token telemetry, and [AG-UI](ag-ui.md) visual timeline integration for Antigravity executions.
+- You are orchestrating multi-agent workflows where a Prism supervisor or coding agent needs to delegate specialized subtasks to Antigravity.
+- You want conversation continuation across multiple user turns in a persistent session.
+
+Do **not** use it:
+- As a generic LLM model provider. For direct Gemini API or Vertex AI foundation model inference without an autonomous loop, use [`@arnilo/prism-provider-google`](providers/google.md) or [`@arnilo/prism-provider-vertex`](providers/vertex.md).
+- If you require step-by-step turn replacement of Antigravity's internal model loop, compaction, or planning strategy.
+- If you require unreleased raw internal chain-of-thought text. Antigravity reasoning effort is projected as token counts and timeline activity steps, not raw hidden thoughts.
+
+## Inputs / request
+
+`createAntigravityCliAgent(options)` accepts agent configuration:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `command` | `string` | `"agy"` | Path to the official `agy` executable on the host. |
+| `args` | `readonly string[]` | `[]` | Additional command-line arguments passed to the CLI. |
+| `cwd` | `string` | `process.cwd()` | Working directory for the runner process. |
+| `env` | `Record<string, string | undefined>` | `process.env` | Process environment variables. |
+| `timeoutMs` | `number` | `300000` (5m) | Maximum process execution time. |
+| `toolPolicy` | `AntigravityToolPolicy` | `"hybrid"` | Built-in CLI tool permissions (`"hybrid"`, `"all"`, `"none"`, or custom). |
+| `tools` | `ToolDefinition[]` | `[]` | Prism tools exposed to the agent via loopback MCP. |
+| `resources` | `ResourceDefinition[]` | `[]` | Prism resources exposed via loopback MCP. |
+| `prompts` | `PromptDefinition[]` | `[]` | Prism prompt templates exposed via loopback MCP. |
+| `exposure` | `AntigravityMcpExposure` | auto-created | Custom MCP server exposure handle if sharing an external server. |
+| `conversationStore` | `AntigravityConversationStore` | in-memory | Store for persisting conversation IDs across turns. |
+| `redactor` | `SecretRedactor` | auto | Secret redactor applied to events and process output. |
+| `agentName` | `string` | `"prism-agent"` | Ephemeral agent definition identifier. |
+| `systemPrompt` | `string` | built-in instructions | Custom instructions appended to the agent definition. |
+
+`agent.run(runOptions)` executes a prompt run:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `prompt` | `string` | required | User task or instruction for Antigravity. |
+| `workspace` | `string` | `agent.cwd` | Target workspace directory path for file modifications. |
+| `sessionId` | `string` | auto-generated | Prism session identifier for conversation persistence. |
+| `branchId` | `string` | `"main"` | Branch identifier for conversation isolation. |
+| `conversationId` | `string` | auto-resolved | Existing Antigravity conversation ID to resume. |
+| `signal` | `AbortSignal` | omitted | Cancellation signal to abort execution and clean up. |
+| `eventSink` | `(event: AgentEvent) => void` | omitted | Real-time event listener for streaming UI updates. |
+| `toolPolicy` | `AntigravityToolPolicy` | agent default | Per-run override for built-in tool policy. |
+
+## Outputs / response / events
+
+`agent.run()` returns a promise resolving to an `AntigravityRunResult`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `text` | `string` | Final synthesized response text from the Antigravity CLI. |
+| `conversationId` | `string` | Antigravity conversation ID for subsequent multi-turn resumption. |
+| `exitCode` | `number` | Process exit status code (0 for success). |
+| `durationMs` | `number` | Total elapsed execution time in milliseconds. |
+| `events` | `readonly AgentEvent[]` | Complete sequence of projected Prism events emitted during the run. |
+| `usage` | `UsageReport` | Aggregated prompt, completion, total, and thinking token counts. |
+| `subagents` | `readonly AntigravitySubagentSummary[]` | Subagents spawned and completed during execution. |
+
+### Streamed events
+
+The runner emits standardized Prism `AgentEvent` objects to the provided `eventSink`:
+- `delegated_agent_step`: High-level step progression with step name, status, and duration.
+- `message_delta`: Incremental response text chunks.
+- `tool_call_start` / `tool_call_delta` / `tool_call_result`: MCP tool invocations and results.
+- `agent_thought_chunk`: Thinking activity indicators with token counts.
+- `usage`: Token usage telemetry updates.
+- `subagent_spawn` / `subagent_finish`: Internal subagent hierarchy lifecycle.
+
+## Request/response example
+
+```json
+{
+  "prompt": "Inspect the repository and add unit tests for the auth helper.",
+  "workspace": "/home/user/project",
+  "sessionId": "session-101",
+  "toolPolicy": "hybrid"
+}
+```
+
+```json
+{
+  "text": "Added 4 unit tests covering token refresh and validation in auth.test.ts.",
+  "conversationId": "conv_9876543210",
+  "exitCode": 0,
+  "durationMs": 4250,
+  "usage": {
+    "promptTokens": 1520,
+    "completionTokens": 380,
+    "totalTokens": 1900,
+    "thinkingTokens": 640
+  },
+  "subagents": []
+}
+```
+
+## Implementation example
+
+### Direct runner
+
+```ts
+import { createAntigravityCliAgent } from "@arnilo/prism-antigravity-agent";
+import { createReadTool, createWriteTool } from "@arnilo/prism-coding-agent";
+
+// Configure agent with host-owned Prism tools exposed over MCP
+const agent = createAntigravityCliAgent({
+  command: "agy",
+  tools: [
+    createReadTool({ workspaceRoot: "/home/user/project" }),
+    createWriteTool({ workspaceRoot: "/home/user/project" }),
+  ],
+  toolPolicy: "hybrid", // Built-in bash/editor tools enabled; Prism MCP tools added
+});
+
+// Run a task with real-time event streaming
+const result = await agent.run({
+  prompt: "Refactor error handling in src/utils.ts to use typed AppError",
+  workspace: "/home/user/project",
+  sessionId: "session-42",
+  eventSink: (event) => {
+    if (event.type === "message_delta") {
+      process.stdout.write(event.delta.text);
+    }
+  },
+});
+
+console.log(`\nCompleted in ${result.durationMs}ms with conversation ${result.conversationId}`);
+```
+
+### Supervisor delegation tool
+
+```ts
+import { createSupervisor } from "@arnilo/prism-supervisor";
+import {
+  createAntigravityCliAgent,
+  createAntigravityDelegationTool,
+} from "@arnilo/prism-antigravity-agent";
+
+const antigravity = createAntigravityCliAgent({
+  workspace: "/home/user/project",
+  toolPolicy: "hybrid",
+});
+
+const supervisor = createSupervisor({
+  tools: [
+    createAntigravityDelegationTool({
+      agent: antigravity,
+      name: "delegate_to_antigravity",
+      description: "Delegate complex coding tasks to Google Antigravity CLI",
+    }),
+  ],
+});
+```
+
+## Extension and configuration notes
+
+### Ephemeral workspace configuration
+
+During each execution, the adapter dynamically constructs:
+1. `.agents/mcp_config.json`: Configures the local loopback MCP server endpoint (`http://127.0.0.1:<port>/mcp`) and authorization header.
+2. `.agents/agents/<name>/agent.md`: Configures custom instructions and tool permissions.
+
+If pre-existing configuration files exist in `.agents/`, they are backed up before the run and restored atomically upon completion, failure, or cancellation.
+
+### Tool policies
+
+The `toolPolicy` setting controls built-in CLI capabilities:
+- `"hybrid"` (default): Enables built-in editor, terminal, and search tools while exposing configured Prism MCP tools.
+- `"all"`: Enables all built-in CLI tools and MCP tools.
+- `"none"`: Disables built-in tools; the agent relies exclusively on exposed Prism MCP tools.
+- Custom object `{ allow?: string[], deny?: string[] }`: Explicit allow/deny lists for fine-grained governance.
+
+## Security and performance notes
+
+- **Host-owned authentication**: Prism does not read, store, or forward Google credentials. Authentication state resides in the official `agy` CLI's session store managed via `agy login`.
+- **Loopback isolation**: The ephemeral MCP HTTP server binds exclusively to `127.0.0.1` on a dynamically assigned port, secured with a cryptographically random Bearer token.
+- **Fail-safe cleanup**: Workspace configuration files and HTTP listener ports are cleaned up in `finally` blocks under all exit conditions, including `SIGINT`, timeouts, and unhandled errors.
+- **Secret redaction**: All stdout, stderr, event payloads, and tool arguments are processed through Prism's secret redactor before event emission.
+- **Terms and quota**: Antigravity CLI execution utilizes Google AI Pro subscription quotas through the authenticated official binary. Host operators should verify compliance with their organization's terms of service.
+
+## Related APIs
+
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): Connect Antigravity event streams to AG-UI and web interfaces.
+- [MCP client bridge and server exposure](mcp-tools.md): Core Model Context Protocol integration in Prism.
+- [Supervisor delegation](supervisors.md): Hierarchical multi-agent delegation patterns.
+- [Coding agent tools](coding-agent-tools.md): Native Prism file, edit, and terminal tools.
+- [Google Gemini provider](providers/google.md): Direct Gemini API model inference without CLI delegation.
+- [Google Vertex AI provider](providers/vertex.md): Enterprise cloud Vertex AI model inference.
+- [Public contracts](public-contracts.md): Core message, event, tool, and session types.

package/docs/browser-automation.md

@@ -122,6 +122,7 @@ Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PL
 
 ## Related APIs
 
+- [Obscura browser engine](obscura.md): optional host-installed Obscura headless browser connected with `chromium.connectOverCDP` through `connectObscuraCdp` — its returned browser plugs directly into `createBrowserTools`/`createBrowserManager` as the host-supplied Playwright browser; pages on one Obscura worker share one V8 isolate, and screenshots/PDF need a render-enabled build.
 - [Tools](tools.md): registry, exclusive dispatch, validation, and ledger.
 - [Web search, fetch, and extraction](web-tools.md): preferred non-interactive retrieval path.
 - [Guardrails](guardrails.md): untrusted external content handling.

package/docs/coding-agent-tools.md

@@ -10,6 +10,7 @@
 | `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
 | `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
 | `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
+| `createAcpFilesystemOperations(client)` | Map an ACP-shaped text-file client to `read`/`write`/`edit` operations; no local-disk fallback, binary/image support, or remote `mkdir`. |
 | `createRepoListTool(cwd, options?)` | `repo_list` tool: bounded deterministic repository listing. |
 | `createRepoSearchTool(cwd, options?)` | `repo_search` tool: bounded literal text search (`outputMode`: content / files_with_matches / count). |
 | `createGlobTool(cwd, options?)` | `glob` tool: bounded filename-pattern match (`*` / `?` / `**`; opt-in bounded `{a,b}` brace expansion via `braceExpansion`). |
@@ -50,6 +51,23 @@ const tools = createToolRegistry(createCodingTools(process.cwd()));
 
 Every tool carries an explicit `kind` (`shell`→`execute`, `read`/`repo_list`→`read`, `write`/`edit`→`edit`, `repo_search`/`glob`→`search`, `delete`→`delete`, `move`→`move`) so ACP `tool_call` updates and other consumers can classify tools without name heuristics.
 
+### ACP editor-buffer operations
+
+`createAcpFilesystemOperations` adapts any client with `readTextFile({ path, line?, limit? })` and `writeTextFile({ path, content })` methods to the `ReadOperations`, `WriteOperations`, and `EditOperations` seams. All reads and writes stay client-backed; `mkdir` is a no-op, `statFile` measures a bounded UTF-8 text read, and image MIME detection is always `null`.
+
+```ts
+import { createAcpFilesystemOperations, createCodingTools } from "@arnilo/prism-coding-agent";
+
+const operations = createAcpFilesystemOperations(clientFilesystem);
+const tools = createCodingTools(cwd, {
+  read: { operations: operations.read },
+  write: { operations: operations.write },
+  edit: { operations: operations.edit },
+});
+```
+
+This is an editor-buffer adapter, not a repository backend: `repo_list`, `repo_search`, `glob`, `delete`, and `move` remain disk-backed unless separately overridden. Binary/image and document reads are not silently delegated to local disk.
+
 ## When to use it
 
 Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
@@ -144,8 +162,10 @@ Read a text or image file.
 | `path` | `string` | Path to the file (relative or absolute; `~` and `file://` expanded). Required. |
 | `offset` | `number` | Line to start reading from (1-indexed). |
 | `limit` | `number` | Maximum number of lines to read. |
+| `findText` | `string` | Literal substring to search for (no regex). When set, the tool pages through the file from `offset` and returns the page starting at the **first matching line** (re-read at the hit line so the match is the first line). No match is an error result with no file body. |
+| `findMode` | `"exact" \| "case-insensitive"` | Match mode for `findText` (default `"exact"`). Two literals only — no regex, no fuzzy. |
 
-**Outputs:** text files are scanned incrementally until one requested page, `maxLines`/`maxBytes`, EOF, or `maxScanBytes` (default 64 MiB scanned per call; 1 GiB hard cap). The default path never loads the complete file and returns a `Use offset=N to continue` footer when more remains. Exact total line count is reported only when EOF was already reached in the bounded scan. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
+**Outputs:** text files are scanned incrementally until one requested page, `maxLines`/`maxBytes`, EOF, or `maxScanBytes` (default 64 MiB scanned per call; 1 GiB hard cap). The default path never loads the complete file and returns a `Use offset=N to continue` footer when more remains. Exact total line count is reported only when EOF was already reached in the bounded scan. When `findText` is set, the tool pages through `readText` output (in `maxLines`-sized pages) from `offset`, returns the page whose first line is the first match, and stops at the same `maxScanBytes` scan cap — the search is a literal substring scan (per `findMode`), never regex. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort, findText scan limit) are error results.
 
 `read` tool options (via `createReadTool(cwd, options)` or `ToolsOptions.read`):
 
@@ -166,6 +186,14 @@ const read = createReadTool(cwd, {
   maxImageBytes: DEFAULT_MAX_IMAGE_BYTES,
   transformImage: async ({ buffer, mimeType }) => host.resizeImage(buffer, mimeType),
 });
+
+// jump to the first line containing the needle
+await read.execute({ path: "src/edit.ts", findText: "createEditTool" }, ctx);
+// case-insensitive search starting at offset 50
+await read.execute(
+  { path: "src/edit.ts", findText: "edittool", findMode: "case-insensitive", offset: 50 },
+  ctx,
+);
 ```
 
 `read` result `metadata`:
@@ -236,13 +264,13 @@ Precise text replacement in an existing file via exact-then-fuzzy matching.
 
 Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse).
 
-**Fuzzy silent-success tradeoff (loud):** when exact match fails, fuzzy may still apply a replacement **without warning the model**. That can edit the wrong region if `oldText` is slightly off (extra/missing whitespace, unicode lookalikes). Prefer exact `oldText` copied from a fresh `read`. Duplicate / non-unique matches already **fail closed** and leave the file unchanged — ambiguity is not silently resolved by picking the first hit.
+**Fuzzy silent-success tradeoff (loud):** when exact match fails, fuzzy may still apply a replacement and is **reported** — both the confirmation text (`Successfully replaced N block(s) in {path} (fuzzy match).`) and `metadata.fuzzy: true`. That can edit the wrong region if `oldText` is slightly off (extra/missing whitespace, unicode lookalikes). Prefer exact `oldText` copied from a fresh `read`. On **no match**, the error lists up to 3 nearby lines (1-indexed, clipped to 120 chars) whose first-line substring matches the edit's first non-empty `oldText` line, so the model can correct its `oldText` (skipped when the needle is shorter than 4 chars or no line contains it). Duplicate / non-unique matches already **fail closed** and leave the file unchanged — ambiguity is not silently resolved by picking the first hit.
 
 A BOM is stripped before matching and re-prepended on write; original line endings are restored. Defaults reject targets over 8 MiB, aggregate old/new UTF-8 input over 2 MiB, or more than 100 edits (hard caps: 64 MiB, 16 MiB, and 1,000). Stat and bounded read checks run before matching or mutation. Default local `writeFile` uses same-directory temp + `rename` (crash-safe replace).
 
-**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
+**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`, with ` (fuzzy match)` appended when the replacement applied via fuzzy matching) plus `metadata`. Any failure — missing/unreadable file, no match (with nearby line context), duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
 
-`edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
+`edit` result `metadata`: `{ path, diff, patch, firstChangedLine, fuzzy? }` — the absolute path written, a display-oriented diff, a standard unified patch, the first changed line in the new file, and `fuzzy: true` present only when the replacement applied via fuzzy (not exact) matching. These are host-readable; the model only sees the short confirmation (keeps model context small).
 
 ### `repo_list`
 

package/docs/computer-use-linux.md

@@ -0,0 +1,122 @@
+# Linux desktop control
+
+## What it does
+
+`@arnilo/prism-computer-use-linux` wraps the host-owned [`computer-use-linux`](https://github.com/agent-sh/computer-use-linux) MCP binary as Prism `ToolDefinition`s. It connects over stdio only when `createComputerUseLinuxTools()` is called, keeps upstream tool names, filters unknown tools, and composes desktop admission, execution approval, result bounds, serialization, redaction, and trust labeling over Prism's existing seams.
+
+The package also exports `loadComputerUseLinuxSkill()`, which loads the short Prism-authored desktop procedure bundled at `skills/computer-use-linux/SKILL.md`. It does not resolve or vendor an upstream skill tree.
+
+## When to use it
+
+Use this package when a Linux host has installed and configured `computer-use-linux` and an agent must inspect or operate that host's desktop. Use the generic [Device adapters](device-adapters.md) contract when implementing another vendor adapter or when the host needs only admission and stream-bound primitives.
+
+Do not use it as a desktop launcher, a cross-platform adapter, or a permission bypass. The host owns the binary, desktop session, sandbox, approval decision, and execution policy.
+
+## Inputs / request
+
+`createComputerUseLinuxTools(options)` accepts:
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `command` | `string` | `computer-use-linux` | Host-owned executable. |
+| `args` | `readonly string[]` | `["mcp"]` | MCP server arguments. |
+| `cwd`, `env`, `stderr` | stdio transport options | omitted | Host-owned process configuration. |
+| `serverId` | `string` | `computer-use-linux` | Bridge/error metadata identifier. |
+| `device` | `DeviceAdapter` | required | Must be enabled `desktop-control` with a sandbox. |
+| `runLimits` | `RunLimits` | required | Shared run accounting required by device admission. |
+| `executionPolicy` | `ExecutionPolicy` | omitted | High-risk mutator approval/policy seam. |
+| `approved` | `boolean` | `false` | Host approval for mutating calls. |
+| `includeSetupTools` | `boolean` | `false` | Explicitly expose host setup tools. |
+| `redactor` | `SecretRedactor` | omitted | Redacts returned external data. |
+| `platform` | `NodeJS.Platform` | `process.platform` | Test/host seam; production must be Linux. |
+| `connect` | MCP bridge factory | `connectMcpTools` | Test seam; not needed in production. |
+
+`loadComputerUseLinuxSkill()` takes no arguments and reads only the package-local skill file. The file is capped at 64 KiB.
+
+## Outputs / response / events
+
+| Export | Result |
+| --- | --- |
+| `createComputerUseLinuxTools` | `{ tools, close }`; `tools` contains known upstream tools returned by the bridge. |
+| `tools` | Read observations (`doctor`, app/window discovery, `get_app_state`, `screenshot`) plus mutators; setup tools are excluded by default. |
+| `close()` | Closes the MCP bridge and its host-owned process transport. |
+| `loadComputerUseLinuxSkill` | Prism `Skill` with name `computer-use-linux` and bounded instructions. |
+| `COMPUTER_USE_LINUX_*` constants | Read, mutating, setup, known-name, and skill-name lists for host filtering and registration. |
+| `MAX_SKILL_FILE_BYTES` | 64 KiB bundled-skill read ceiling. |
+| Tool result | External data with `metadata.trust = "untrusted_external"`; screenshot/app-state oversize results become `dropped_oversize`. |
+
+Mutating calls are serialized through one mutex and run `assertDeviceAdmit` plus `assertExecutionAllowed` before the remote MCP call. Read observations bypass per-call approval but still require an admitted device.
+
+## Request/response example
+
+```json
+{
+  "command": "computer-use-linux",
+  "args": ["mcp"],
+  "device": {
+    "kind": "desktop-control",
+    "enabled": true,
+    "requireApproval": true,
+    "sandbox": "linux-desktop"
+  },
+  "runLimits": {
+    "maxTurns": 32,
+    "maxToolCalls": 200
+  },
+  "approved": false,
+  "includeSetupTools": false
+}
+```
+
+## Implementation example
+
+```ts
+import { createToolRegistry, type Skill } from "@arnilo/prism";
+import {
+  createComputerUseLinuxTools,
+  loadComputerUseLinuxSkill,
+} from "@arnilo/prism-computer-use-linux";
+
+async function installDesktop(hostSkills: { register(skill: Skill): void }, hostApproved: boolean) {
+  const desktop = await createComputerUseLinuxTools({
+    device: {
+      kind: "desktop-control",
+      enabled: true,
+      requireApproval: true,
+      sandbox: "linux-desktop",
+    },
+    runLimits: { maxTurns: 32, maxToolCalls: 200 },
+    approved: hostApproved,
+  });
+  const tools = createToolRegistry(desktop.tools);
+  hostSkills.register(loadComputerUseLinuxSkill());
+
+  // Keep `desktop` alive while the run can call `tools`; close it at run end.
+  return { tools, close: () => desktop.close() };
+}
+```
+
+## Extension and configuration notes
+
+- Install and configure the host binary separately: `npm install -g @agent-sh/computer-use-linux` or another host-managed installation. Prism has no runtime dependency on that binary and never downloads it.
+- The factory exposes unprefixed upstream names. Unknown or future upstream names are omitted until Prism classifies them.
+- `setup_accessibility` and `setup_window_targeting` are host-only and omitted unless `includeSetupTools: true` is explicitly selected. The bundled skill never instructs agent turns to perform setup.
+- `connect` is an injectable bridge factory for fake MCP tests. The package's normal path uses `connectMcpTools` with stdio `{ command, args: ["mcp"] }`.
+- `loadComputerUseLinuxSkill()` is inert beyond reading its packaged file; it does not discover peers, resolve paths, or connect to MCP.
+
+## Security and performance notes
+
+- Construction fails closed on non-Linux hosts and requires `DeviceAdapter.kind = "desktop-control"`, explicit `enabled: true`, a sandbox, and shared `RunLimits` before connecting.
+- Mutators are high-risk external mutations: they require device admission, host approval when configured, and `ExecutionPolicy`; input calls are serialized to prevent concurrent desktop state changes.
+- Observation results are untrusted external content and pass the optional host redactor. Screenshot/app-state payloads pass `acceptDeviceChunk`; oversize payloads are replaced with `dropped_oversize`, not forwarded.
+- Imports are inert. The default setup surface is off, the skill file is capped at 64 KiB, and no full upstream skill tree is shipped.
+- The host must keep credentials, desktop session state, binary paths, sandbox identity, and approval state outside model-controlled arguments.
+
+## Related APIs
+
+- [Device adapters](device-adapters.md): generic admission, shared limits, chunk bounds, and telemetry redaction contract.
+- [MCP client bridge](mcp-tools.md): host-owned MCP transport and bounded tool mapping.
+- [Tools](tools.md): registry and dispatch lifecycle for the returned `ToolDefinition`s.
+- [Context and skills](context-and-skills.md): explicit skill registration, activation, and progressive disclosure.
+- [Host security](host-security.md): trust, approval, sandbox, and untrusted external-content boundaries.
+- [Upstream computer-use-linux](https://github.com/agent-sh/computer-use-linux): host binary and desktop prerequisites.

package/docs/database-persistence.md

@@ -389,7 +389,7 @@ For document or wide-column stores, map the relational tables above to the store
 - **Branches:** In document stores, a branch can be a lightweight document keyed by `leaf_entry_id` that points to the session and root. Rebuild still walks `parent_id` links in entries.
 - **Retention:** Use TTL columns or scheduled map-reduce/streaming jobs. TTL on `expires_at` or entry timestamps is the simplest NoSQL implementation.
 
-The Node JSONL session store is a single-process development adapter. It has no cross-process locking, no migrations, no retention enforcement, and no tenant isolation. Do not use it as a production multi-writer store.
+The Node JSONL session store is a single-process development adapter. It has no cross-process locking, no migrations, no retention enforcement, and no tenant isolation. Do not use it as a production multi-writer store. Appends serialize per instance; a rejected append (conflict, duplicate, corrupt file) does not poison later appends on that instance. The rejected write is not committed.
 
 ## Request/response example
 

package/docs/device-adapters.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy only** in `@arnilo/prism` (`src/devices.ts`). No vendor voice or desktop-control implementation ships in 0.0.14 — those are demand-gated to 0.1.x. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
+Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy** in `@arnilo/prism` (`src/devices.ts`). The first vendor adapter, `@arnilo/prism-computer-use-linux`, wraps the host-owned `computer-use-linux` MCP binary without changing this generic contract. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
 
 ## When to use it
 
@@ -79,7 +79,7 @@ if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), fr
 
 - Frozen caps: audio/screenshot/stream chunk **1 MiB / 8 MiB**; concurrent device sessions per identity **1 / 4**. Device wall time / turns / tool calls consume the shared `RunLimits` (admission fails closed without run accounting).
 - `enabled` resolves to `true` only on an explicit `true`; any other value is disabled. `requireApproval` stays `true` unless the host explicitly sets `false` (it should not).
-- Vendor voice / desktop-control packages are **deferred to 0.1.x** and ship only if Task 0 records measured demand. This page documents the contract they must satisfy via `runDevicePolicyConformance`.
+- `@arnilo/prism-computer-use-linux` is the first vendor package. It remains optional, Linux-only, host-binary-owned, and outside umbrella profiles; this page stays generic so future voice or desktop vendors can satisfy the same contract via `runDevicePolicyConformance`.
 
 ## Security and performance notes
 
@@ -91,7 +91,8 @@ if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), fr
 ## Related APIs
 
 - [Browser automation](browser-automation.md): verified-state checkpoints + reload/verify-before-side-effect for browser composition.
+- [Linux desktop control](computer-use-linux.md): first-party host-owned `computer-use-linux` MCP wrapper using this contract.
 - [Conversations](conversations.md): durable threads that own the runs device sessions bind to.
 - [Host security](host-security.md): approval, sandbox, and egress trust boundaries device adapters compose over.
 - [Performance and resource limits](performance.md): shared `RunLimits` accounting.
-- [Migration](migration.md): 0.0.14 additive seams and 0.1.x device vendor deferral.
+- [Migration](migration.md): historical 0.0.14 additive seams and device-vendor deferral; the 0.3.0 desktop wrapper is additive and optional.

package/docs/graft.md

@@ -0,0 +1,125 @@
+# Graft context-graph integration
+
+## What it does
+
+`@arnilo/prism-graft` is an optional package that wires [nanonets/graft](https://github.com/nanonets/graft) — a repository context-graph CLI (`graft/` directory, INDEX.md orientation, symbol-level wiring graph) — into Prism contribution contracts.
+
+It registers six pull tools backed by the graft CLI (`--json`, argv-safe), a push-mode retrieval-pack context provider plus first-turn orientation injector carried on the `graft` skill, commands (`graft`, `graft-build`, `graft-check`, `graft-viz`), and an edit-watch middleware that computes blast radius after mutating tool calls. Import is inert; a missing graft CLI fails closed at `setup` with a bounded redacted error.
+
+## When to use it
+
+Use it when a host wants agents to locate code by architecture, callers, and coupling before grep-spelunking. Three modes:
+
+- `"pull"` (default) — register the tools; the agent decides when to query.
+- `"push"` — per-turn retrieval pack (pointers only) + first-turn orientation, injected automatically.
+- `"both"` — everything.
+
+Install optional peer `@nanonets/graft@^0.13.0` **or** pass `packageRoot`/`cliPath` explicitly. Pair with progressive disclosure: the `graft` skill body stays small; tool schemas carry the details. Graft complements indexed code search (`repository_search`): graph/semantic locators vs literal search — neither replaces the other.
+
+Zero-code alternative (L0): hosts can skip this package entirely and let agents call `graft <command> --json` through their shell tool, optionally seeding context with graft's own generated instruction files. This package exists for native-tool ergonomics, budgeted subprocesses, session persistence, and push mode.
+
+## Inputs / request
+
+`createGraftExtension(options)`:
+
+| Field | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `cliPath` / `packageRoot` | `string` | no | Explicit stub/binary or checkout root with a manifest-declared bin; default resolves optional peer `@nanonets/graft`. Relative paths rejected; explicit paths existence-checked at resolve time. |
+| `mode` | `"pull" \| "push" \| "both"` | no | Surface selection. Default `pull`. |
+| `projectDir` | `string` | no | Directory graft operates on. Default `process.cwd()` at setup. |
+| `retrievalBudgetMs` | `number` | no | Wall-clock budget per CLI child call (default 8000). |
+| `maxResultBytes` | `number` | no | Stdout cap before parsing (default 512 KiB). |
+| `maxPromptChars` | `number` | no | Prompts longer than this never become ask argv (default 4096). |
+| `allowUpstreamTelemetry` | `boolean` | no | Default false → children run with `DO_NOT_TRACK=1`. |
+| `providerEnv` | `Record<string, string>` | no | Explicit graft provider settings (`GRAFT_API_KEY`, …). Never inherited from host env; only `GRAFT_*` keys reach the child. |
+| `editToolNames` | `readonly string[]` | no | Tools triggering blast-radius lookup. Default `write`, `edit`, `move`. |
+| `quietStartup`, `hideStatus` | `boolean` | no | Suppress startup status events / status reporting. |
+| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM attach pattern). |
+| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for state restore. |
+
+Pull tools (mode includes `pull`): `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map`, `graft_blast`.
+
+Push surfaces (mode includes `push`): skill `graft` carrying context provider `graft-context` (per-turn pointers-only pack, gated: ≥12-char prompt, dedup by seen node ids, 32 KiB block ceiling) and instruction injector `graft-orient` (`first_turn`, byte-capped INDEX.md cut + staleness banner).
+
+Registered commands: `graft` (`status` \| `build` \| `check` \| `viz` dispatch), plus `graft-build`, `graft-check`, `graft-viz` aliases.
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `createGraftExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`; emits `graft:loaded` on setup. |
+| `resolveGraftCli(options)` | Fail-closed CLI resolution (`explicit` → command+argv, `peer-bin` → node + manifest bin). |
+| `runGraftJson(cli, argv, options)` / `childEnv(options)` / `childTimeoutMs` / `DEFAULT_MAX_RESULT_BYTES` | Shared budgeted JSON runner for hosts building custom surfaces. |
+| `readBoundedFile` / `redactPaths` / `GraftResolveError` | Bounded-read and redaction helpers. |
+
+Events: `graft:status` (check/build outcomes), `graft:dirty` (post-edit, repo-relative path + optional `staleCountEstimate`), `graft:loaded` (mode + cliKind metadata).
+
+Session custom entry shape (`data.type === "graft-state"`, CAS via `expectedParentId`):
+
+```json
+{ "kind": "custom", "data": { "type": "graft-state", "freshness": { "checkedAt": "...", "fresh": true }, "seen": ["node-a"], "savedTokensApprox": 120 } }
+```
+
+The graph never rebuilds itself mid-session (no auto-rebuild): after edits, ask/grep results may lag one turn; graft self-refreshes on the next indexed query, or run `/graft build` for an immediate refresh. The skill text states this contract to the agent.
+
+## Request/response example
+
+Tool call (pull):
+
+```json
+{ "name": "graft_ask", "arguments": { "query": "where is auth handled?", "count": 3 } }
+→ { "nodes": [{ "id": "auth-guard", "title": "requireAuth", "path": "src/auth.ts", "line": 41 }] }
+```
+
+Status event:
+
+```json
+{ "type": "graft:status", "extension": "@arnilo/prism-graft", "metadata": { "fresh": true, "missing": 0, "stale": 2 } }
+```
+
+## Implementation example
+
+See [`examples/graft-extension.ts`](../examples/graft-extension.ts) — network-free demo against the package fixture stub: one pull-tool call, one push turn with pack injection + dedup, one simulated edit producing blast radius, and the `DO_NOT_TRACK` child-env guard.
+
+```ts
+import { createExtensionKernel, createMemorySessionStore } from "@arnilo/prism";
+import { createGraftExtension } from "@arnilo/prism-graft";
+
+const store = createMemorySessionStore();
+const kernel = createExtensionKernel({ errorPolicy: "throw" });
+await kernel.load([
+  createGraftExtension({
+    packageRoot: "./vendor/graft-checkout",
+    mode: "both",
+    quietStartup: true,
+    appendEntry: async (entry, options) => store.append(entry, options),
+    getEntries: async () => store.list("s1"),
+  }),
+]);
+// Pull: dispatch graft_ask/… tools. Push: runs assemble the skill-carried
+// provider + graft-orient injector. Edits: middleware emits graft:dirty.
+```
+
+## Extension and configuration notes
+
+- Import alone registers nothing (`sideEffects: false`); no timers, watchers, or network. The only child processes are budgeted graft CLI calls.
+- Retrieval happens in-process via Prism primitives (context provider, injector, tool_result middleware) — no external hook shims.
+- Ask result shape is parsed tolerantly (`nodes|results|matches|hits`) because graft is pre-1.0; formatters emit pointers (`title` + `file:line` + `[[wikilink]]`), never source bodies.
+- Not included in `@arnilo/prism-code`, `@arnilo/prism-sdk`, or the `prism-all` umbrella (deliberate opt-out, like Caveman/Ponytail) — opt-in install only.
+- Multi-repo layouts work as upstream graft defines them (workspaces, submodules with `--follow-submodules`, sibling repos); point `projectDir` at the graft root that owns the target repo.
+
+## Security and performance notes
+
+- Telemetry default-off: children always get `DO_NOT_TRACK=1` unless `allowUpstreamTelemetry` is true; child env is fixed-base — host env vars are never inherited, and only explicit `GRAFT_*` keys from `providerEnv` pass through. Route secrets like `GRAFT_API_KEY` through the host's credential resolution when populating `providerEnv`.
+- Upstream output is untrusted: stdout capped (`maxResultBytes`), prompts capped (`maxPromptChars`), injected packs bounded (32 KiB), orientation cut byte-capped (8 KiB); error paths are logged redacted (absolute paths/home dirs).
+- Every CLI call is wall-clock-budgeted (`retrievalBudgetMs`, minus fixed overhead for the timeout math) and every failure degrades silently: pull tools return structured errors, the push pack contributes nothing, edit-watch passes the tool result through untouched.
+- No background workers; state persists through two CAS appends per turn at most (freshness patch, seen-set/saved-tokens update).
+
+## Related APIs
+
+- [Ponytail behavior integration](ponytail.md): same adapter pattern (optional peer/upstream path, fail-closed setup, session custom entries).
+- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
+- [Indexed code search](indexed-code-search.md): literal `repository_search` seam — complement, not overlap.
+- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`; skill-carried context providers.
+- [Instruction injection](instruction-injection.md): injector seams (`graft-orient` rides `first_turn`).
+- [Extension kernel and event bus](extensions.md): explicit `kernel.load`, extension events.

package/docs/host-security.md

@@ -155,6 +155,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Optional `@arnilo/prism-browser` requires a host-supplied Playwright Browser (`playwright-core@1.61.0` peer). Import is inert. One non-persistent context belongs to one run; actions serialize; refs are snapshot-scoped; CSS/evaluate/CDP/persistent profiles are denied. Context routing + `serviceWorkers: "block"` deny file/data/blob/devtools/private/loopback by default and require contained-proxy attestation for external egress (Playwright routing is defense in depth, not DNS containment). Uploads are realpath-rooted; downloads quarantine with hash/MIME until host `approveRelease`; screenshots return bounded `ImageContent`. Observation vs mutation/high-impact actions map to `ExecutionPolicy`. Treat snapshot/page text as untrusted external content. Close contexts with `browser_close` or `manager.closeRun(runId)` on abort/terminal. Browser control endpoint, binary/image pin, and real egress firewall/proxy remain host-owned. Shared sandbox: `createSharedSandboxBrowserOptions()` + `assertBrowserSandboxNetwork()`.
 - Browser verified-state checkpoints (0.0.14, `createBrowserCheckpointLedger()`) store URL + domain-state hash + host data refs only — never serialized browser internals (cookies/storage/contexts). After any resume/interruption the ledger fails closed (`assertVerifiedBeforeSideEffect`) until the host reloads + verifies, so side effects never replay on stale state.
 - Device adapters (0.0.14, `resolveDevicePolicy`/`assertDeviceAdmit`) are deny-by-default: admission fails closed without explicit `enabled`, an explicit sandbox, approval (when required), an under-budget session count, and shared `RunLimits`. Stream chunks over the frozen cap are dropped with a marker; telemetry is redacted before emit/persist. No vendor voice/desktop package ships in 0.0.14 (demand-gated 0.1.x); device adapters cannot broaden consent/memory/network/file/browser/connector/tool permissions (gate 8).
+- Optional `@arnilo/prism-wiki` tools treat agent-supplied input as untrusted at the first-party `.wiki/` filesystem boundary. `wiki_read_page` enforces lexical containment (`path.relative` with separator-aware `..`/absolute checks) plus `fs.realpath` containment for the wiki root and every successfully read file, so sibling-prefix (`.wiki-evil`), `..`, absolute, alternate-separator, and symlink escapes are denied before content is returned; missing contained pages report `found: false` while denied paths throw an access-denied error (never mapped to not-found). `wiki_record_insight` rejects empty titles/content, caps titles at 200 characters and content at 65,536 bytes, and collapses control characters and newlines in titles to single-line display text before any page/frontmatter/index/log write, so titles cannot inject Markdown headings, index entries, or log entries; slugs are allow-listed to `[a-z0-9-_]` with a non-empty fallback. See [LLM Wiki](wiki.md).
 - `@arnilo/prism-credentials-node` rejects oversized/malformed envelopes and excessive scrypt work before KDF allocation, uses async scrypt, and requires restrictive existing/new Unix vault modes. Keep vault ownership and parent-directory access host-controlled; review before `chmod 600`, never auto-weaken a file policy. Keychain calls use abort-aware native async work with finite timeout/payload caps and sanitized errors. OS prompts, service availability, and whether a native backend promptly honors cancellation remain host/platform boundaries; no plaintext fallback is attempted.
 - LLM compaction always sends finite summary `maxTokens`, retains bounded deltas/events, and bounds/redacts provider/factory/policy error detail. Observational-memory workers cap turns, calls, arguments, results, transcript, and surfaced errors; unknown tools fail before execution, while invalid results can only be rejected after a host tool returns and may therefore follow side effects. Pass all known provider/credential/tool secrets into compaction/runtime options; exact replacement is not secret discovery.
 - Default remote-media loading resolves every DNS answer, rejects the hostname if any address is non-public, and pins one validated address through the request. Explicit `allowedHostnames` can trust private destinations. A host-supplied `fetch` owns DNS/rebinding/proxy/redirect safety; a custom `requestUrl` must connect to its supplied validated address.
@@ -172,7 +173,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - License inventory: 160 locked third-party packages; all declare permissive MIT, ISC, BSD, Apache-2.0, or compatible dual licenses. No GPL, AGPL, SSPL, or missing lockfile license metadata.
 - Install scripts: only `better-sqlite3@12.11.1` runs an install script (`prebuild-install || node-gyp rebuild --release`), required by the explicitly installed SQLite adapter. Core and other optional packages add no install hook.
 - Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
-- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy.
+- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy. `security:threat-suites` also gates CodeQL-remediation regressions (plan 038): linear `trimTrailingSlashes`/parsers with no environment regex evaluation, single-pass HTML sanitization, crypto (not `Math.random`) fixture identifiers, and no clear-text error logging on password-handling paths.
 
 PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy beyond package origin/DNS pinning, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
 
@@ -213,6 +214,7 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
 - **Named threat-suites leg.** `npm run security:threat-suites` aggregates the Phase 8–11 conformance suites (durable-loop/HITL approval, coding sandbox/egress/forge, ACP protocol, OIDC/OPA/MCP-OAuth/OpenAPI/artifact) into one named 0.1.0 security evidence leg — same scripts as `npm test`, no rewrite; the Phase 7 tenant-isolation suite is its protected counterpart under `npm run test:postgres` (missing `PRISM_TEST_POSTGRES_URL` is a named blocked gate).
 - **Supply-chain negative fixtures.** `scripts/release-gate.test.mjs` verifies the tarball deny list rejects tampered content (plans/reviews/maps/tests), unexpected file types and credential material (native binaries, `.pem`/`.key`/`.p12`), and that a provenance flag suppressed in CI is detectable in the `release.mjs` publish dry-run arguments (`--provenance` mandatory under `GITHUB_ACTIONS`, never claimed on local OIDC-less publishes).
 - **Mandatory gate stack.** CodeQL/SAST, PR dependency review (fail on high), secret scan (source + unpacked tarballs), SPDX SBOM + license policy, tarball allow/deny content checks, and provenance (npm OIDC + GitHub build attestations on tarballs and SBOM) all run in `security.yml`/`release.yml`; evidence for the 0.1.0 tree is recorded in [0.1.0 readiness](0.1.0-readiness.md).
+- **CodeQL query suite.** `.github/codeql/codeql-config.yml` selects the `security-extended` suite for `javascript-typescript` (with the default suite) on push/PR/schedule in `security.yml` (10-minute job bound; measured runtime ~3m22s on the audited SHA, last successful main run `33059128198`). The ignore list covers only generated `dist`, `node_modules`, and release/security artifact directories — first-party packages, threat suites, and fixtures that ship or execute are always scanned, so new alerts enter the same plan-038 ledger/remediation loop (config + guardrails asserted in `scripts/phase38-codeql-regression.test.mjs`). Local Task 6 gates (typecheck/lint/format/threat suites/audit/secret scan/SBOM) pass on the remediations; GitHub `state=open` stays non-zero until those remediations are the analyzed head. Groups G (`js/insufficient-password-hash` on RFC 7636 S256) and H (`js/incomplete-url-substring-sanitization` on a negative docs assertion) are maintainer-reviewed false positives queued for narrow dismissal after that analyze, not code changes.
 - **Live canaries are blocked gates, not skips.** The `live-canaries` and `sandbox-browser` workflows always set their gate env (`PRISM_LIVE_CANARIES=1`), so absent credentials fail the job loudly with a named owner (the workflow + dispatching operator) and retained `canary-report.json` evidence; the local silent-skip path exists only when the gate env is not set.
 
 ## Distributed events and tool effects