Skip to content

Spec2Contract Readonly

Grzegorz Nowak edited this page Oct 10, 2026 · 2 revisions

Spec-to-contracts — Readonly (book ↔ in-tests contracts)

The Readonly area of the Product Book covers the session readonly posture: how it is toggled (/readonly, Ctrl+Shift+R, --readonly, prompt/skill frontmatter), how it is persisted and rehydrated, how it guards tools and bash, how it crosses into spawned children and handoff, and how it is surfaced in the TUI. Its left space is PB-READONLY-01 … PB-READONLY-45 (45 rows). Contracts are carried mainly by the readonly fixture family T25–T31 (toggle, frontmatter, bash classifier, spawn, rehydration, handoff, os-sandbox), with secondary seals from T01, T08, T12, T32, T43, T44, T46 and the T49 e2e lifecycle.

Junction rows

Claim ID Assertion (terse) Fixture(s) Status Notes
PB-READONLY-01 /readonly toggles readonly on or off in the session. T25 ✅ asserted readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations" / "readonly toggle off restores write, handoff, and bash access".
PB-READONLY-02 Ctrl+Shift+R toggles readonly only while the agent is idle. T25 ✅ asserted readonly-mode.test.ts — "readonly shortcut only toggles while idle" (handler no-ops when isIdle() false, blocks write when true).
PB-READONLY-03 --readonly boolean startup flag, off by default. T29 ✅ asserted readonly-rehydration.test.ts — "returns false for empty branch with no CLI flag" / "returns true for empty branch with CLI flag" (default-off and set-on behaviour). Aspect: default value.
PB-READONLY-03 --readonly declared as a boolean flag. — ⚠️ no test yet Aspect: flag declaration/type. Would seal it: assert the registered flag descriptor is { type: "boolean", default: false } via the test host flag registry.
PB-READONLY-04 Session with no saved readonly entries starts readonly when --readonly is true. T29 ✅ asserted readonly-rehydration.test.ts — "returns true for empty branch with CLI flag" (empty branch has no entries).
PB-READONLY-05 Interactive prompt/skill with readonly: true enables readonly when invoked. T26 ✅ asserted readonly-frontmatter.test.ts — "single /name input activates readonly frontmatter", "/skill:name activates readonly from skill frontmatter", "suffixed /name command activates readonly frontmatter", "dotted /name command activates readonly frontmatter".
PB-READONLY-06 Interactive prompt/skill with readonly: false disables readonly when invoked. T26 ✅ asserted readonly-frontmatter.test.ts — "deferred readonly disable emits a one-shot context nudge" (enabled via /readonly, then /nudge-off disables and emits [readonly] disabled); "readonly: false frontmatter keeps readonly disabled and stays silent when already disabled".
PB-READONLY-07 Frontmatter takes effect at before_agent_start, not at initial slash input. T26 ✅ asserted readonly-frontmatter.test.ts — "input handler queues a prompt command even when the registry is unavailable until before_agent_start", "before_agent_start skips readonly cache population while no slash-command toggle is pending", "queued slash commands are consumed FIFO across before_agent_start calls".
PB-READONLY-08 Readonly frontmatter requires a boolean; invalid values ignored with a warning. T26, T32 ✅ asserted readonly-frontmatter.test.ts — "invalid /prompt readonly value records a warning for the prompt source", "invalid /skill:name readonly value records a warning", "malformed /prompt frontmatter records a parse warning"; frontmatter-cache.test.ts — "populateFromSkills returns null for non-boolean readonly frontmatter", "records invalid readonly value issues".
PB-READONLY-09 Prompt/skill invoked during streaming is not executed; UI warns it needs an idle agent. T26 ✅ asserted readonly-frontmatter.test.ts — "streaming readonly frontmatter is blocked without a delayed toggle" (result {action:"handled"}, no posture change, notification readonly frontmatter requires an idle agent).
PB-READONLY-10 Headless/RPC input does not apply interactive slash-command readonly frontmatter. T26 ✅ asserted readonly-frontmatter.test.ts — "headless /name frontmatter stays a no-op through the deferred pipeline", "extension input stays a no-op when hasUI is false". Aspect: headless; RPC path not separately distinguished.
PB-READONLY-11 /readonly does nothing when no UI is attached. T25 ✅ asserted readonly-mode.test.ts — "readonly toggle is a no-op in headless mode" (hasUI:false; write stays unblocked).
PB-READONLY-12 A toggle records its new posture in the session. T26 ✅ asserted readonly-frontmatter.test.ts — "one readonly entry is appended per consumed queued toggle" (pi-schematic-readonly entry with data.enabled), "deferred readonly enable emits a one-shot context nudge". Note: assertion is on the deferred/frontmatter toggle path; the /readonly command append is exercised indirectly via resume/rehydration.
PB-READONLY-13 Resuming a session or /tree restores the latest saved posture on the active branch. T29, T30 ✅ asserted readonly-rehydration.test.ts — "uses a persisted readonly entry when present", "picks the latest entry (true wins)", "picks the latest entry (false wins)"; readonly-handoff.test.ts — "session resume restores readonly enforcement from persisted state", "session tree re-announces readonly even when the rehydrated value is unchanged".
PB-READONLY-14 A saved off posture overrides --readonly on resume. T29 ✅ asserted readonly-rehydration.test.ts — "uses a persisted readonly entry when present" (entry enabled:false with CLI flag true → false), "falls back to the CLI flag when no valid readonly entry exists".
PB-READONLY-15 While readonly is on, write is blocked with an explicit reason. T25, T43 ✅ asserted readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy" (reason READONLY_WRITE_EDIT_BLOCK_REASON).
PB-READONLY-16 While readonly is on, edit is blocked with an explicit reason. T25, T43 ✅ asserted readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, and bash mutations"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy", "block reasons use 'Readonly mode:' prefix".
PB-READONLY-17 Parent write/edit remain advertised but are blocked at call time. T25, T43 ✅ asserted Aspect: call-time block. readonly-mode.test.ts — "readonly toggle on blocks …"; notifications.test.ts — "parent readonly tool-call consumer uses centralized block copy".
PB-READONLY-17 Parent write/edit stay advertised in the tool list while readonly is on. — ⚠️ no test yet Aspect: advertisement. Child filtering is asserted (T28) but the parent keeps the tools; would seal it: assert the parent's registered tool list still contains write/edit while readonly.
PB-READONLY-18 Readonly bash permits non-mutating commands. T27 ✅ asserted readonly-bash-classifier.test.ts — "allows bash reads and non-mutating commands", "allows readonly-safe git inspection subcommands", "allows piped read commands", "allows sudo commands that only read".
PB-READONLY-19 Readonly bash permits filesystem writes inside the OS temp dir. T27, T31 ✅ asserted readonly-bash-classifier.test.ts — "allows bash writes to temp dir", "allows hidden-file globs inside temp dir", "blocks cwd-relative downloads outside temp but allows inside temp"; os-sandbox.test.ts — "sandbox allows writes through a symlinked temp path".
PB-READONLY-20 Classifier blocks recognized write redirects outside temp. T27 ✅ asserted readonly-bash-classifier.test.ts — "blocks write redirects outside temp dir", "blocks heredoc redirects outside temp", "blocks command substitutions that write outside temp".
PB-READONLY-21 Classifier blocks recognized filesystem mutations outside temp. T27 ✅ asserted readonly-bash-classifier.test.ts — "blocks bash writes outside temp dir", "classifies git commands correctly", "blocks git branch creation", "blocks git tag creation", "blocks chained commands that write outside temp".
PB-READONLY-22 Known package-manager mutations blocked even pointed at a temp path. T27 ✅ asserted readonly-bash-classifier.test.ts — "blocks package managers unconditionally".
PB-READONLY-23 A blocked bash call reports the reason and the original command. T27, T43 ✅ asserted notifications.test.ts — "bash and sandbox consumers use centralized readonly copy" (result.reason === buildReadonlyBashBlockReason(verdict.reason, command), which embeds Command: <cmd>), "block reasons use 'Readonly mode:' prefix"; readonly-bash-classifier.test.ts — block assertions on the real tool_call path.
PB-READONLY-24 A non-string bash command is rejected as invalid input while readonly is on. T27, T28 ✅ asserted readonly-bash-classifier.test.ts — "blocks malformed bash input without throwing"; readonly-spawn.test.ts — "readonly bash guard rejects non-string commands".
PB-READONLY-25 macOS uses sandbox-exec when functional, denying writes outside temp and /dev/null. T31 ✅ asserted os-sandbox.test.ts — "buildMacProfile rejects paths containing quotes", "wrapped command blocks non-temp writes and allows temp writes", "sandbox allows writes to /dev/null". Note: the wrapped-command assertions are platform-gated (if (!canUseOsSandbox()) return), so they seal the macOS sandbox-exec path only when run on macOS.
PB-READONLY-26 Linux uses functional bwrap, read-only root + writable temp. T31 ✅ asserted os-sandbox.test.ts — "quotes dynamic Linux sandbox paths for the outer shell" (--bind <temp> <temp>), "bwrap executes a quoted bind path without shell injection", "wrapped command blocks non-temp writes and allows temp writes". Note: bwrap execution is platform-gated to Linux.
PB-READONLY-27 Linux without functional bwrap falls back to classifier alone. T27 ✅ asserted Aspect: classifier-alone behaviour. readonly-bash-classifier.test.ts — all allow/block tests go through applyReadonlyBashGuard, which classes mutations and allows reads with no OS sandbox.
PB-READONLY-27 The classifier-alone selection when bwrap is unavailable. — ⚠️ no test yet Aspect: fallback selection. Would seal it: stub canUseOsSandbox() to false and assert the guard returns allow for reads and a classified block for mutations (no sandbox action).
PB-READONLY-28 Windows has no syscall-level sandbox; bash relies on classifier alone. T27 ✅ asserted Aspect: classifier-alone behaviour. readonly-bash-classifier.test.ts — allow/block suite exercises the no-sandbox classifier path.
PB-READONLY-28 Windows selecting classifier-only enforcement (no syscall sandbox). — ⚠️ no test yet Aspect: Windows platform selection. Would seal it: force platform win32 / canUseOsSandbox()===false and assert no sandbox wrapping while mutable commands are still classified-blocked.
PB-READONLY-29 Classifier checks commands even with an OS sandbox; unsafe rejected before launch. T27, T43 ✅ asserted notifications.test.ts — "bash and sandbox consumers use centralized readonly copy" asserts applyReadonlyBashGuard(mutation).action === "block" (not sandbox) unconditionally; readonly-handoff.test.ts — assertNonTempBashBlocked requires block:true before execution.
PB-READONLY-30 A spawned child inherits the parent's readonly posture at spawn time. T28, T01 ✅ asserted readonly-spawn.test.ts — "readonly child authority note communicates readonly inheritance", "real readonly child omits write/edit and blocks a non-temp bash write"; spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (prompt carries inherit readonly authority).
PB-READONLY-31 A readonly child does not receive write/edit in its tool list. T28, T01 ✅ asserted readonly-spawn.test.ts — "filterReadonlyToolNames removes write and edit in readonly mode", "real readonly child omits write/edit …"; spawn.test.ts — "spawn execute composes Model Group routing with readonly child guards" (seenConfig.tools excludes write/edit).
PB-READONLY-32 A readonly child's bash runs through the same readonly guard as the parent's. T28 ✅ asserted readonly-spawn.test.ts — "readonly bash guard blocks non-temp writes and allows temp writes" (same applyReadonlyBashGuard), "real readonly child … blocks a non-temp bash write" (READONLY_BASH_BLOCKED).
PB-READONLY-33 Children cannot call handoff. T28, T01 ✅ asserted readonly-spawn.test.ts — "buildChildToolNames excludes spawn and handoff from inherited tools", "real readonly child …" (observed tool sets exclude handoff/spawn); spawn.test.ts — child tools exclude handoff.
PB-READONLY-34 Readonly blocks agent-initiated handoff unless a temporary exception is pending. T25, T30 ✅ asserted readonly-mode.test.ts — "readonly toggle on blocks write, edit, handoff, …"; readonly-handoff.test.ts — "blocked readonly handoff never invokes compaction".
PB-READONLY-35 /handoff <direction> reserves the exception without removing the write/edit guard. T30 ✅ asserted readonly-handoff.test.ts — "/handoff command creates temporary bypass for handoff tool only" (handoff unblocked; write stays blocked; non-temp bash blocked); "after handoff compaction, bypass is cleared and readonly persists".
PB-READONLY-36 /notebook <topic> can authorize a readonly handoff only if usage meets the threshold. T30, T46, T08 ✅ asserted readonly-handoff.test.ts — "readonly topic boundary creates the same bypass contract as explicit /handoff", "readonly topic boundary derives eligibility from percentage when tokens are unavailable", "readonly topic boundary stays advisory until handoff is eligible"; watchdog.test.ts — "eligible readonly human topic boundary auto-creates handoff bypass equivalent to /handoff"; notebook.test.ts — "readonly /notebook boundary notification explains deferred handoff eligibility".
PB-READONLY-37 Threshold is 30,000 estimated tokens; too-small/unknown is not eligible. T12, T30 ✅ asserted handoff-eligibility.test.ts — "handoff eligibility prefers explicit tokens" (MIN_HANDOFF_TOKENS; -1 ineligible), "estimates tokens from percent and context window" (14.9999% ineligible), "rejects malformed or unestimable usage"; readonly-handoff.test.ts — "readonly human topic boundary promotes exactly at the token threshold".
PB-READONLY-38 Human topic change before the threshold is advisory until eligible, not an immediate authorization. T30, T08, T46 ✅ asserted readonly-handoff.test.ts — "readonly topic boundary stays advisory until handoff is eligible", "advisoryDelivered flag prevents repeated advisory nudges for ineligible boundary"; notebook.test.ts — "readonly /notebook boundary notification explains deferred handoff eligibility"; watchdog.test.ts — "context injects readonly handoff guidance after explicit user /handoff".
PB-READONLY-39 An agent-originated topic boundary cannot grant the exception. T30 ✅ asserted readonly-handoff.test.ts — "readonly agent topic transitions cannot promote or remain queued", "readonly agent topic boundary is not promoted to handoff bypass".
PB-READONLY-40 After successful handoff, a still-enabled readonly posture is reannounced to the next context. T30, T49 ✅ asserted readonly-handoff.test.ts — "the handoff summary stays readonly-free and the fresh context relearns readonly live", "after handoff compaction, bypass is cleared and readonly persists"; real-host.test.ts (e2e) — "handoff queues the successor instruction and re-announces readonly in its turn", "readonly lifecycle: handoff bypass clears after compaction while readonly persists".
PB-READONLY-41 Status bar shows 🔒 readonly while enabled and removes it when disabled. T44 ✅ asserted tui-indicators.test.ts — "updateIndicators shows readonly indicator when enabled" (lock emoji + "readonly"), "updateIndicators hides readonly indicator when disabled".
PB-READONLY-42 Toggling readonly notifies the operator of the new posture. T26, T43 ◐ partly asserted notifications.test.ts — "summary constants use '[readonly]' prefix", "composition chain: READONLY_ENABLED_STATUS contains READONLY_BASH_SCOPE"; readonly-frontmatter.test.ts — "readonly success notifications use the exact slash-command source" (frontmatter-initiated toggles). Missing portion: the /readonly command / Ctrl+Shift+R themselves calling ctx.ui.notify with READONLY_ENABLED_STATUS / READONLY_DISABLED_NOTIFICATION — readonly-mode.test.ts uses a no-op notify, so that emission is not asserted.
PB-READONLY-43 The agent gets a one-shot hidden context nudge on change, not a repeated warning each turn. T25, T26, T46 ✅ asserted readonly-mode.test.ts — "toggle delivers an activation nudge via context hook", "toggle off delivers a deactivation nudge"; readonly-frontmatter.test.ts — "deferred readonly enable emits a one-shot context nudge" (second hook returns none); watchdog.test.ts — "context hook suppresses watchdog after readonly toggle nudge is drained".
PB-READONLY-44 At 70%+, the readonly TUI warning directs same-topic work to spawn and different-topic to eligible handoff. T44 ◐ partly asserted tui-indicators.test.ts — "updateIndicators shows readonly-specific warning widget at 70%+ context" (asserts widget mentions readonly, spawn, explicit /handoff) and "hides widget below 70% context". Missing portion: the explicit same-topic→spawn / different-topic→eligible-handoff mapping text; the test asserts keyword presence only.
PB-READONLY-45 /notebook is exempt from workflow frontmatter interception while readonly. T26 ✅ asserted readonly-frontmatter.test.ts — "/notebook bypasses deferred frontmatter lookup" (with "/readonly bypasses…" and "/handoff bypasses…").

Empty surfaces in this area

No PB-READONLY row is entirely ⚠️; every claim has at least one representing fixture. The following contract surfaces within a row have no test:

  • PB-READONLY-03 — --readonly is declared as a boolean flag (type/default descriptor). Would seal it: assert the registered flag descriptor { type: "boolean", default: false } via the test host.
  • PB-READONLY-17 — the parent keeps write/edit advertised while readonly. Would seal it: assert the parent tool list still contains write/edit after /readonly (only the call-time block is covered).
  • PB-READONLY-27 — Linux-without-functional-bwrap fallback selection. Would seal it: stub canUseOsSandbox() false and assert no sandbox action (classifier allow for reads, block for mutations).
  • PB-READONLY-28 — Windows classifier-only selection (no syscall sandbox). Would seal it: force platform win32 / canUseOsSandbox() false and assert classifier-only enforcement with no wrapping.

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
45 49 43 2 4

Clone this wiki locally