flowviant 0.125.29 → 0.125.31

package/README.md

@@ -200,6 +200,370 @@ On Claude Code and Codex build turns, `card_ui_review.inspect_screenshot` can su
 
 The agent can fix in-scope findings and rerun up to three attempts per turn, each capped at two minutes including startup. Every attempt stops its owned browser and preview, including on cancellation; teardown also tracks their process groups. Reports and screenshots use `.flowviant/artifacts/`, and the existing delivery Verification retains routes, viewports, actions/outcomes, scrubbed diagnostics and source identity. Tracked/nonignored file bytes and HEAD are remeasured at delivery; later changes mark evidence stale. Ignored build/runtime files are outside that source measurement. The project check, fresh read-only pre-review, human approval and merge remain separate.
 
+## Isolated review environments
+
+Code agents can provision disposable databases natively. This is opt-in: commit
+`.flowviant/environment.json` on the reviewed base branch. Projects without a
+recipe keep their existing setup. This layer works independently of the model
+and whether the project has a browser preview.
+
+For PostgreSQL, use a **dedicated development/review server** with `psql` on the
+daemon's PATH. The administrative role needs permission to create/drop databases,
+create restricted login roles and assign database ownership. Flowviant creates
+an empty database from `template0` and a distinct role for each worktree. It
+does not clone the contents of a shared development or production database.
+
+```json
+{
+  "version": 1,
+  "database": {
+    "provider": "postgres",
+    "adminUrlEnv": "REVIEW_DATABASE_ADMIN_URL",
+    "bindings": ["DATABASE_URL", "DIRECT_DATABASE_URL"]
+  },
+  "migrate": ["npm", "run", "db:migrate"],
+  "seed": ["npm", "run", "db:seed"],
+  "envFiles": [".env.local"],
+  "env": {
+    "NODE_ENV": "development",
+    "CACHE_PREFIX": "review_${ENVIRONMENT_ID}"
+  },
+  "connectors": ["database"],
+  "ttlHours": 24
+}
+```
+
+Use this project's actual migration/fixture scripts and connector names. Commands
+are argv arrays, run without a shell. The migration runner and fixture seeder
+must tolerate retries after partial failure. Each listed project MCP connector
+must reference one of the database bindings, for example `${DATABASE_URL}` in
+its environment configuration. Flowviant expands it from the same scoped values
+the app receives. Unlisted/personal connectors are not rewritten or isolated.
+
+Machine-local values belong in the gitignored
+`.flowviant/environment.local.json`, with mode `0600`, or the admin variable can
+be supplied by the daemon's environment. For example:
+
+```json
+{
+  "env": {
+    "REVIEW_DATABASE_ADMIN_URL": "postgresql://review_admin:LOCAL_PASSWORD@127.0.0.1:5432/postgres",
+    "PAYMENTS_API_KEY": "LOCAL_SANDBOX_KEY"
+  }
+}
+```
+
+This local file stays in the checkout. Its selected runtime values, excluding
+provider administrator credentials, join the isolated database bindings. Generated
+`.env`/`.dev.vars` files and local receipts are owner-only and excluded from Git.
+Existing/tracked/user-edited env files and symlink destinations are preserved;
+choose another path if one conflicts. Use `envFiles: []` for projects that do not
+load dotenv files; the provided command wrapper injects values directly, including
+complex multiline credentials. A recipe disables automatic copying of the
+checkout's ignored `.env*`, including production profiles.
+
+The first configured build allocates the database, runs the existing setup hook
+or lockfile install once, migrates and seeds. Later cards reuse that worktree's
+database, rerun migrations and retain successfully seeded data. The agent gets
+an exact private helper command for `run -- <argv>` and `refresh`. The wrapper
+selects the repository's own bindings even when a multi-repository place has
+several environments. `refresh --seed` explicitly reruns fixtures. The local UI
+self-review and final/combined-merge checks use scoped values too; combined
+worktrees have their own databases and migrate their integrated source before
+validation. These setup receipts do not count as passing application tests.
+
+The daemon keeps local allocation intent before contacting a provider, so retries
+reuse one environment id. Active turns/checks hold a heartbeat lease. Its sweep
+releases inactive environments after `ttlHours` (1–168, default 24) or worktree
+retirement; at most two receipts per repository per sweep. Shutdown retains them
+for restart. Cleanup checks database/role ownership before deleting anything;
+failures retain the receipt for retry. A reviewed recipe change rebuilds disposable
+data after the previous environment is released. Moving a worktree retains its id.
+The daemon must be running for this sweep; a remote provider adapter should also
+set/renew its own expiration as protection while the machine is offline.
+
+To use a database provider's branches, replace the `database` object with:
+
+```json
+{
+  "provider": "command",
+  "command": ["node", ".flowviant/database.mjs"],
+  "credentials": ["DATABASE_PROVIDER_API_KEY"],
+  "source": "SANITIZED_DEVELOPMENT_BRANCH_ID",
+  "bindings": ["DATABASE_URL", "DIRECT_DATABASE_URL"]
+}
+```
+
+This is the native provider-adapter lifecycle, not an AI-generated provisioner
+on every card. The reviewed adapter receives `allocate` or `release` as its last
+argument, with the environment id, original test-data source, known resource id
+and expiration in `FLOWVIANT_ENVIRONMENT_ID`, `FLOWVIANT_ENVIRONMENT_SOURCE`,
+`FLOWVIANT_ENVIRONMENT_RESOURCE_ID` and `FLOWVIANT_ENVIRONMENT_EXPIRES_AT`.
+Stdin also carries JSON `{id, resourceId, source}`. Only the named provider
+credentials and minimal toolchain environment are passed. Allocate must look up
+the original id before creating, renew its expiration and verify ownership;
+a create-success/lost-response retry must never create another branch. It returns
+JSON `{owner, resourceId, connectionString}`. Release must verify ownership and
+reconcile by id even if allocation never returned a resource id, then return
+`{owner}`. Both operations must be idempotent. Output is private and never included
+in error messages. Repository adapter files named with `./` or `.flowviant/`
+must still match the saved reviewed blobs, including during cleanup; keep that
+adapter available until its resources are released. No commercial branch SDK
+or provider credentials are installed automatically.
+
+An allocate response may also return `bindings`, keyed only by declared database
+variable names, when the provider needs distinct pooled and direct URLs for the
+same branch. Other bindings use `connectionString`. The adapter must verify that
+all of these connections target its owned environment.
+
+Database isolation does not configure auth tenants, Redis, queues, object storage,
+email or payment sandboxes. Select their development credentials explicitly and
+namespace them with the environment id where supported. Apps and connector
+processes still run as the user's UID: this is data separation, not a security
+sandbox against repository code reading other local files. An inherited role's
+access to unrelated databases is the PostgreSQL server's policy; use a dedicated
+review server. See PostgreSQL's [database creation documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
+
+## Runtime review adapters
+
+Commit `.flowviant/review.json` on the project's reviewed base branch to expose
+repeatable review workflows to code agents. One `card_runtime` interface supports
+command checks, browser apps, Linux desktops, Roblox Studio and native/engine bridges. Projects
+without targets mount no additional tools or processes. The agent's existing
+shell and browser workflows remain available.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "checks": {
+      "adapter": "command",
+      "command": ["npm", "test"],
+      "timeoutSeconds": 120
+    },
+    "web": {
+      "adapter": "browser",
+      "command": ["npm", "run", "dev", "--", "--port", "${PORT}"],
+      "port": 0,
+      "fixture": "Disposable seeded review database and test account"
+    },
+    "desktop": {
+      "adapter": "desktop",
+      "platforms": ["linux"],
+      "command": ["npm", "run", "desktop:dev"],
+      "fixture": "Disposable local workspace and sandbox service bindings"
+    }
+  }
+}
+```
+
+Use the repository's real commands. A Roblox repository can declare command
+targets for its configured Luau analyzer, standalone logic tests or Rojo build;
+these results do not claim a Studio playtest. The adapters do not install tools
+or infer gameplay from a sync server's listening port. `cwd` defaults to the
+repository root and must resolve inside that worktree. Commands are argv arrays,
+without shell expansion. Timeouts are 1–600 seconds. Browser `port: 0` allocates
+a loopback port and substitutes only `${PORT}`; a fixed port is also supported.
+The listener is attributed to the target worktree before Chrome opens it.
+The runtime MCP server gives Codex a longer tool-call timeout in its private
+build config so the CLI's default does not truncate a configured command.
+
+`discover` reports targets and actual prerequisites without launching apps.
+`run` executes a named target; command results retain exit status, bounded logs
+and source identity. A large log stays in the evidence artifact while only its
+tail enters the model context. Browser/desktop/engine targets use the existing
+Live app frame, private sign-in and take/return/stop control. `observe` retains
+the actual screenshot, `act` supplies bounded input, and `handoff` holds the turn
+without model polling. Screenshots and interactions are observations, not passing
+tests. Source changes invalidate earlier command evidence. The shell helper
+supplied to runners without MCP omits image base64 from text output; the model
+opens the retained screenshot with its own image tool if available.
+
+Only an interactive target launch creates a browser/display or stream. One
+interactive surface occupies the frame per held turn. Native screenshots run at
+a bounded low cadence, with fresh captures after input; the stream invokes no
+model per frame. Adapter-owned app/process groups stop on explicit runtime Stop,
+target replacement, timeout, abort and turn teardown. The browser frame's Stop
+closes its browser; its supervised server also closes when the runtime tool or
+turn closes. A person's Stop prevents reopening an interactive surface in that
+turn. Commands can run alongside an existing surface without replacing its
+owned server. Artifacts use the existing delivery/storage path.
+
+Command checks inherit the normal unattended build environment without the
+machine credential. Interactive apps/helpers start from the minimal toolchain
+environment plus scoped review-environment bindings. A target's optional `env`
+array selects additional variables by name, e.g. `["SANDBOX_API_KEY"]`; values
+stay local and scoped database bindings take precedence. Provider administrator
+credentials remain excluded. Personal/unlisted connectors and other external
+services keep their explicit configuration.
+
+### Linux virtual desktops
+
+The first native backend requires Xvfb, xauth, Openbox, xdotool and ImageMagick's
+`import` executable. On Debian/Ubuntu these are supplied by the `xvfb`, `xauth`,
+`openbox`, `xdotool` and `imagemagick` packages. Install them in the daemon's VM
+image; missing tools are reported on the target. The runner never installs them
+automatically or falls back to the user's display. Chrome headless itself does
+not need these desktop packages or a visible desktop session.
+
+The backend atomically allocates a private X display, disables its TCP listener
+and creates an owner-only Xauthority cookie. It starts a window manager without
+session autostart, then the declared app, waits for a visible client window and
+focuses it. The app has a fresh home/config/runtime directory and private X11
+display; inherited Wayland/WSLg and personal D-Bus sessions are not used. If an
+app needs D-Bus, use a repository-supported `dbus-run-session -- ...` command.
+Capture/input helpers receive only that display's authority. Handoff drains
+capture work before resuming public frames. Natural app exit ends the surface;
+crashes/timeouts report their actual failure. Teardown kills owned groups and
+removes the temporary home and authority files.
+
+The Linux backend runs behind the same stdio bridge used by other host helpers.
+It owns a separate process group and watches its parent pipe: a daemon killed
+without graceful shutdown closes that pipe and the helper reaps its native
+descendants. Normal bridge close first allows cleanup on EOF, with a bounded
+force-stop grace for a stalled helper.
+
+V1 supports left clicks, text, the shared bounded navigation keys and vertical
+scrolling at 1440×900. It does not yet provide drag, key holds, sound or native
+accessibility inspection. Apps needing Wayland-only APIs or GPU acceleration
+need an appropriate host/backend; an Xvfb image is not proof those capabilities
+exist. The session isolates display/cookies and avoids accidental personal
+desktop access, but still runs as the operator's UID. Use a dedicated VM/container
+for execution containment and scoped service credentials for data isolation.
+
+### Native and engine bridges
+
+A target with `adapter: "bridge"` uses the same UI and control ownership. Its
+`command` starts a reviewed host helper over private newline-delimited JSON-RPC
+2.0 stdio; `platforms` can restrict where it runs. `configuration` is a bounded
+object passed to the helper alongside the actual `worktree`. Repository helper
+paths spelled `./...` or `.flowviant/...` must match their reviewed base blobs;
+the helper launches from the checkout, with the target worktree in its scope.
+
+The protocol methods are `initialize`, `open`, `snapshot`, `act` and `privacy`.
+Initialize receives `{protocol:1, worktree, width:1440, height:900, configuration}`
+and returns `{protocol:1, isolation:"owned-session", privateHandoff:true}` or
+`isolation:"consented-window"`. It must bind that owned session or an explicitly
+consented window. Open receives `{epoch:0}`. Snapshot receives the current epoch
+and returns `{epoch,width:1440,height:900,data:"JPEG_BASE64",observation:"..."}`.
+Act receives `{epoch,input}` with the shared bounded input verbs. Frame
+notifications use method `frame` and params `{epoch,width,height,data}`. Frames
+are bounded to one million base64 characters; no debugging socket is exposed.
+An `ended` notification with the current epoch reports normal application exit;
+`failure` with `{epoch,message}` reports an actual backend error. Helpers must
+release their owned children when stdin closes and when terminated.
+Privacy receives `{private,epoch}` and must drain old captures before replying
+`{epoch,drained:true}`. The broker discards every old-epoch frame. Wrong ownership,
+missing private fences, malformed messages/images and timeouts close the helper.
+
+This contract is the extension point for Windows/macOS desktop capture and specialized engines;
+general Windows/macOS desktop capture helpers are not included in this release. Windows capture would
+use an explicitly selected window through Windows Graphics Capture; macOS would
+use ScreenCaptureKit and native input/accessibility permissions. Linux Wayland
+hosts would use their consented portal/PipeWire path. Roblox Studio requires a
+Windows or Mac host; Linux can still edit and check its filesystem sources.
+Engine-specific play/start/assert tools can use project MCP or command targets;
+declaring a bridge alone does not implement those engine semantics. The built-in
+Roblox adapter below uses Studio's own MCP rather than OS desktop capture.
+
+### Roblox Studio through Windows + WSL
+
+Use `adapter: "roblox"` for a Windows Studio fixture reached through a reviewed
+stdio launcher in WSL. Studio must already be installed, signed in, and have its
+built-in MCP server enabled. The daemon needs native Linux headless Chromium and
+`flock`; it creates no personal browser window or Windows daemon. No model service
+is added. [Roblox's MCP guide](https://create.roblox.com/docs/studio/mcp) describes
+the built-in server and its available tools.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "studio": {
+      "adapter": "roblox",
+      "command": ["./scripts/roblox-studio-mcp"],
+      "env": ["ROBLOX_STUDIO_MCP", "WSL_INTEROP", "WSL_DISTRO_NAME"],
+      "fixture": "Disposable local place with test services and worktree scripts",
+      "configuration": {
+        "studioName": "${WORKTREE}.rbxl",
+        "startPlay": true,
+        "scripts": [
+          {
+            "file": "src/server/Main.server.luau",
+            "path": ["ServerScriptService", "Main"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Commit the executable launcher on the reviewed base. For an existing Windows
+StudioMCP executable, a small launcher can use the daemon's selected
+`ROBLOX_STUDIO_MCP` environment variable (a WSL `/mnt/c/.../StudioMCP.exe` path):
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+exec "${ROBLOX_STUDIO_MCP:?Set the installed StudioMCP.exe path on this machine}"
+```
+
+Reuse a working launcher if already configured. Keep stdin/stdout attached to the
+MCP process, without shell banners or `start`; do not launch Studio itself from
+this wrapper. The adapter validates the reviewed launcher bytes before running
+it from the checkout. Machine-specific paths stay in the selected environment.
+
+Build/sync a disposable place from the task worktree using the project's actual
+Rojo or Studio workflow, then open it in Windows Studio. `studioName` must equal
+the **exact name returned by `list_roblox_studios`**; `${WORKTREE}` expands to the
+task worktree's folder name. No first-instance or place-id fallback is used.
+In that fixture set the `FlowviantReviewWorktree` attribute on ReplicatedStorage
+to the same folder name, for example in Studio's Command Bar:
+
+```lua
+game:GetService("ReplicatedStorage"):SetAttribute("FlowviantReviewWorktree", "a-TASK-WORKTREE-ID")
+```
+
+The source mappings use worktree-relative Lua/Luau filenames and explicit Studio
+instance path segments. At most forty scripts, each at most 128 KiB, are compared
+before input or play starts; CRLF/LF differences are normalized. Missing,
+ambiguous, escaping or stale mappings and a wrong worktree marker refuse that
+review. Unmapped scripts, assets and other fixtures remain unverified. A marker
+is an explicit fixture binding, not a sandbox or proof of automatic Rojo sync.
+
+`run` requires an unambiguous Edit state before starting play and waits for a
+Client player/camera. A pre-existing play session is left alone; `startPlay:false`
+attaches to an already running fixture and never stops that session. A local OS
+lock prevents simultaneous turns using the same fixture name in that daemon
+environment. This does not coordinate other WSL distros or independent MCP clients.
+Owned play receives a temporary `FlowviantReviewSession` Client attribute; the
+adapter rechecks it before input and cleanup, leaving a replacement play session
+alone. This marker is runtime state, not a saved/published place edit.
+
+Viewport captures, click/text/navigation-key input, Take control and Return use
+the existing Live app frame. PNG/JPEG images are normalized in a network-disabled
+headless canvas, letterboxed to 1440×900, with click coordinates mapped to the
+measured player viewport. Mismatched aspect ratios are refused. The two-second
+capture cadence makes no model calls. Screenshots and input are observations;
+they do not assert gameplay passed. The first version uses the shared bounded
+input vocabulary, without WASD/key holds, mouse drag or full Studio editor control.
+
+Use privately fences old captures; console history is omitted after any private
+control. Studio's Windows login/MFA dialogs are outside the viewport and must be
+completed on the Windows host. Stop review leaves the Studio editor open. The
+helper watches parent EOF and on normal Stop, abort or daemon death attempts to
+stop only play it started, with bounded cleanup time before its processes are
+forced down. A disconnected/unresponsive MCP server can prevent that final stop;
+the editor and any remaining play session stay on the Windows host.
+
+Studio must already have disposable/namespaced DataStores and sandbox service
+bindings. Flowviant's database environment does not rewrite Roblox DataStore,
+Open Cloud, HTTP or game-universe configuration. This adapter does not install
+Studio, publish a place, upload assets, invoke Roblox's AI subagents, import
+personal auth or silently select a live game. Without Studio MCP, Lua changes
+still produce the usual code diff and configured command-check evidence.
+
 ## Modes
 
 | Env | What runs |

package/bin/cli.mjs

@@ -80,6 +80,12 @@
 // answered here before anything else loads: no config, no update check, no
 // output but the hook's. An unknown hook exits 2, which Claude Code reads as a
 // refusal — the read guard's own rule for a hook that cannot judge.
+if (process.argv[2] === '__environment') {
+  await (await import('./lib/reviewEnvironmentMain.mjs')).reviewEnvironmentMain();
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__capture-mcp') {
   await (await import('./lib/captureAuthority.mjs')).captureMcpMain();
   process.exit(process.exitCode ?? 0);
@@ -98,6 +104,23 @@ if (process.argv[2] === '__managed-browser-mcp') {
   process.exit(0);
 }
 
+if (['__runtime-review', '__runtime-review-mcp'].includes(process.argv[2])) {
+  await (await import('./lib/runtimeReview.mjs')).runtimeReviewMain(process.argv[2] === '__runtime-review-mcp');
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
+if (process.argv[2] === '__linux-desktop-bridge') {
+  await (await import('./lib/linuxDesktopBridge.mjs')).linuxDesktopBridgeMain();
+  process.exit(process.exitCode ?? 0);
+}
+
+if (process.argv[2] === '__roblox-studio-bridge') {
+  await (await import('./lib/robloxStudioBridge.mjs')).robloxStudioBridgeMain();
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__video-render-mcp') {
   await (await import('./lib/videoRender.mjs')).videoRenderMain();
   process.exit(process.exitCode ?? 0);

package/bin/lib/agentPlan.mjs

@@ -33,6 +33,7 @@ import { scrub as envScrub, scrubCut } from './uplinkScrub.mjs';
 import { groupDependencies } from './planDependencies.mjs';
 import { AGENT_TASK_KINDS } from './agentTaskKinds.mjs';
 import { blockedAnswer } from './agentAsk.mjs';
+import { splitAnswer } from './agentSplit.mjs';
 import { isResearchUse } from './researchUse.mjs';
 import { candidateObjects } from './modelJson.mjs';
 import { parseGaps } from './turnGaps.mjs';
@@ -258,6 +259,13 @@ export function parseTurnResult(text, scrub = envScrub) {
       // as plain text.
       return { outcome: 'question', answer: blockedAnswer(scrub(question), v, scrub), ...progressOf(v, scrub) };
     }
+    if (v.status === 'split') {
+      // A split proposal (2026-11-06, agentSplit.mjs) is a question: the agent
+      // freezes until the person answers Use N subagents or Do it yourself.
+      const answer = splitAnswer(v, scrub);
+      if (!answer) continue;
+      return { outcome: 'question', answer, ...progressOf(v, scrub) };
+    }
     if (v.status === 'delivered') {
       return {
         outcome: 'delivered',

package/bin/lib/agentQueueContext.mjs

@@ -17,6 +17,12 @@ requirements. The brief and criteria marked full are supplied without clipping.
 sourceChats are the person's exact words in the New task chat these cards were
 planned in, up to each card's landing; a brief is the planner's paraphrase of
 them, and links, references and file lists there are part of the request.
+${job.gapContinuationAccepted === true ? 'This server supports disposition=required: unfinished required work continues in this card before Review.' : 'This server has not advertised automatic gap continuation. Finish required work within this turn; if it remains unfinished, ask through a blocked reply instead of declaring delivery.'}
+relatedWork names sibling cards from the same request across agents, including
+completed cards. Outside this queue does not mean unowned. Link the actual
+ownerTaskId instead of proposing or implementing a sibling's work again.
+Only a card's observed completion is recorded; verify a reported recurrence
+instead of assuming an earlier Done card solved the current failure.
 Human messages are exact recorded words across this agent, with the preceding
 question when present. taskId on a message is where it was recorded, not an
 implicit scope restriction. target.kind=agent explicitly addresses the whole

package/bin/lib/agentSplit.mjs

@@ -0,0 +1,90 @@
+/**
+ * CLAUDE SUGGESTS SUBAGENTS (2026-11-06, D28–D31, epic E5): the split a card
+ * agent proposes instead of starting children that edit files, read off its
+ * final JSON and handed on as a QUESTION.
+ *
+ *     {"status": "split", "split": {"reason": "…", "parts": [
+ *        {"title": "Port gizmo shaders", "touches": ["src/gizmo.ts"], "edits": true},
+ *        {"title": "Audit textures", "touches": ["assets/**"], "edits": false}]},
+ *      "progress": "…"}
+ *
+ * The agent freezes on it as a native CLI freezes on its ask tool (D31): the
+ * turn settles `question`, the board says Needs you, and the person answers
+ * through the existing answer lane. So the answer is built as every blocked
+ * question's is (agentAsk.mjs): prose, then ONE ```flowviant-ask fence — here
+ * with the two options the server and the page key on, `Use N subagents` and
+ * `Do it yourself` (the shared `splitUseLabel` / `SPLIT_SOLO_LABEL`), and the
+ * parts under an extra `split` key the ask reader ignores. A screen that
+ * knows nothing of splits still draws an answerable question.
+ *
+ * BOUNDED, AND NEVER LOST. `SPLIT_BOUNDS` is the shared one, key for key. A
+ * proposal past any bound, or with a hostile character, loses its fence whole
+ * and goes on as a plain-text question listing what could be read, exactly as
+ * malformed options do: the person can still answer it in words.
+ */
+import { ASK_HOSTILE } from './agentAsk.mjs';
+
+/** The shared `SPLIT_BOUNDS` (packages/shared/src/schemas/subagentSplit.ts). */
+export const SPLIT_BOUNDS = Object.freeze({ parts: 12, title: 120, touches: 8, touch: 200, reason: 600 });
+export const SPLIT_SOLO_LABEL = 'Do it yourself';
+export const splitUseLabel = n => `Use ${n} subagent${n === 1 ? '' : 's'}`;
+export const SPLIT_QUESTION = 'Use subagents?';
+
+const one = (v, max, scrub) => {
+  if (typeof v !== 'string') return null;
+  const t = scrub(v).trim();
+  return t && t.length <= max && !ASK_HOSTILE.test(t) ? t : null;
+};
+
+/** The declared split → `{ parts, reason }`, or null when any part breaks a
+ *  bound. `scrub` runs before each field is measured. */
+export function declaredSplit(raw, scrub = s => s) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!Array.isArray(raw.parts) || !raw.parts.length || raw.parts.length > SPLIT_BOUNDS.parts) return null;
+  const parts = [];
+  for (const p of raw.parts) {
+    if (!p || typeof p !== 'object' || Array.isArray(p) || typeof p.edits !== 'boolean') return null;
+    const title = one(p.title, SPLIT_BOUNDS.title, scrub);
+    const touches = p.touches === undefined ? [] : p.touches;
+    if (!title || !Array.isArray(touches) || touches.length > SPLIT_BOUNDS.touches) return null;
+    const kept = [];
+    for (const t of touches) { const k = one(t, SPLIT_BOUNDS.touch, scrub); if (!k) return null; kept.push(k); }
+    parts.push({ title, touches: kept, edits: p.edits });
+  }
+  let reason = null;
+  if (raw.reason !== undefined && raw.reason !== null) {
+    if (typeof raw.reason !== 'string') return null;
+    const r = scrub(raw.reason).trim();
+    if (r.length > SPLIT_BOUNDS.reason || ASK_HOSTILE.test(r.replace(/\n/g, ' '))) return null;
+    reason = r || null;
+  }
+  return { parts, reason };
+}
+
+const partLine = (p, i) => `${i + 1}. ${p.title}${p.touches.length ? ` — ${p.touches.join(', ')}` : ''} · ${p.edits ? 'edits' : 'read-only'}`;
+
+/**
+ * THE ANSWER A SPLIT TURN HANDS ON, or null when it declared no parts at all
+ * (then it is no answer, as a blocked turn with no question is not). The
+ * prose names the parts, so a surface that draws no fence still shows them.
+ */
+export function splitAnswer(v, scrub = s => s) {
+  const split = declaredSplit(v?.split, scrub);
+  if (!split) {
+    // Readable parts, past a bound: a plain question, answerable in words.
+    const titles = Array.isArray(v?.split?.parts) ? v.split.parts.map(p => typeof p?.title === 'string' ? scrub(p.title).trim().slice(0, SPLIT_BOUNDS.title) : '').filter(Boolean) : [];
+    if (!titles.length) return null;
+    return `${SPLIT_QUESTION} I would split this card into ${titles.length} parts:\n\n${titles.map((t, i) => `${i + 1}. ${t}`).join('\n')}`;
+  }
+  const n = split.parts.length;
+  const prose = `${split.reason ? `${split.reason}\n\n` : ''}${split.parts.map(partLine).join('\n')}\n\n${SPLIT_QUESTION}`;
+  const ask = {
+    question: SPLIT_QUESTION, header: 'Subagents',
+    options: [
+      { label: splitUseLabel(n), description: n === 1 ? 'Run this part as a subagent.' : 'Run the parts side by side.' },
+      { label: SPLIT_SOLO_LABEL, description: 'Claude does every part itself, one after another.' },
+    ],
+    split,
+  };
+  return `${prose}\n\n\`\`\`flowviant-ask\n${JSON.stringify(ask)}\n\`\`\``;
+}

package/bin/lib/architectureContract.mjs

@@ -0,0 +1,57 @@
+/** Generated by the existing vault-scoped reader; no new infrastructure access. */
+export const ARCHITECTURE_EXAMPLE = {
+  version: 1,
+  summary: 'A browser application calls an API. Production deployment is unknown.',
+  components: [
+    { id: 'web', name: 'Web app', kind: 'application', description: 'The browser interface.', evidence: 'confirmed', sources: [{ path: 'web/package.json', reason: 'Declares the browser application.' }] },
+    { id: 'api', name: 'API', kind: 'service', description: 'Handles application requests.', evidence: 'confirmed', sources: [{ path: 'api/server.ts', line: 1, reason: 'Defines the HTTP entry point.' }] },
+  ],
+  connections: [{ from: 'web', to: 'api', label: 'HTTP requests', evidence: 'confirmed', sources: [{ path: 'web/client.ts', reason: 'Calls the API base URL.' }] }],
+  unknowns: ['The repository does not establish which services are deployed.'],
+};
+
+export const SYSTEM_ARCHITECTURE_CONTRACT = `
+UNDERSTAND MY SYSTEM — docs/01-architecture.md also supplies the Architecture
+view. Full sweeps generate the report. Incremental re-grounds maintain it only
+when architecture-affecting changes are in scope; never expand an unrelated
+incremental pass into a full scan just to add this report. If no report exists
+and this pass cannot inspect the system, leave it absent. Inspect real entry
+points, workspace/package manifests, API clients,
+database/storage/queue adapters and deployment configuration before writing it.
+Map major applications, services, data stores, queues and external systems;
+do not turn every file, dependency or function into a node.
+
+Include exactly ONE fenced block tagged flowviant-architecture containing JSON
+in this version-1 format (this example is FORMAT ONLY, never project facts):
+\n\`\`\`flowviant-architecture
+${JSON.stringify(ARCHITECTURE_EXAMPLE, null, 2)}
+\`\`\`
+
+Kinds: application, service, database, queue, storage, external. Component ids
+are unique ASCII letters/digits/underscore/hyphen, starting with a letter or
+digit, at most 80 characters. Connections reference those ids. Every component
+and connection needs at least one source: a real repository-relative path you
+opened, an optional positive line number and a reason explaining the evidence.
+Never emit absolute paths, traversal or URLs as source paths. Confirmed means
+source explicitly establishes the claim; inferred means an interpretation, and
+the source reason must explain it. Neither means running, healthy or deployed.
+
+State scope in the summary: only this checked-out repository is inspected;
+other repositories, deployment state and external settings remain unknown unless
+actually inspected. Never imply project-wide or production completeness. Put
+unanswered questions and uninspected areas in unknowns. An empty/new repository
+has components: [], connections: [] and an explanation in unknowns; do not invent
+a proposed architecture. Never expose credentials, environment values, private
+hosts or secret material. Do not contact infrastructure, provision anything,
+install dependencies or run the application to construct this map.
+
+At most 80 components, 200 connections, 40 sources per finding and 80 unknowns.
+Names at most 160 characters, connection labels 200, source paths 1000 and
+summary/descriptions/reasons/questions 4000. Keep the chapter's readable prose,
+Mermaid overview, files: frontmatter and page-local provenance beside the report.
+This is source analysis by the coding CLI, not independent verification by
+Flowviant. Re-ground it when changed files affect system boundaries, config,
+entry points or connections, including additions/removals outside its old files:
+list. Re-read affected sources; retain unrelated findings without asserting a
+new verified commit for unchecked claims. Respect human/reference ownership.
+`;

package/bin/lib/architectureReport.mjs

@@ -0,0 +1,38 @@
+/** Standalone daemon counterpart of shared/systemArchitecture.ts. The release
+ * parity gate checks the same accepted/rejected reports on both readers. */
+export const SYSTEM_ARCHITECTURE_PATH = 'docs/01-architecture.md';
+export const SYSTEM_ARCHITECTURE_FENCE = 'flowviant-architecture';
+export const ARCHITECTURE_REPORT_DAEMON_VERSION = '0.125.31';
+
+const text = (value, max = 4000) => typeof value === 'string' && value.trim().length > 0 && value.trim().length <= max;
+const id = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(value);
+const source = (value) => value && typeof value.path === 'string' && value.path.length > 0 && value.path.length <= 1000 &&
+  !/^[\/\\]|[\\\x00-\x1f\x7f:#?]/.test(value.path) && value.path.split('/').every((part) => part && part !== '.' && part !== '..') &&
+  (value.line === undefined || (Number.isInteger(value.line) && value.line > 0)) && text(value.reason);
+const finding = (value) => value && ['confirmed', 'inferred'].includes(value.evidence) &&
+  Array.isArray(value.sources) && value.sources.length > 0 && value.sources.length <= 40 && value.sources.every(source);
+
+export function validArchitectureReport(value) {
+  if (!value || value.version !== 1 || !text(value.summary) || !Array.isArray(value.components) || value.components.length > 80 ||
+    !Array.isArray(value.connections) || value.connections.length > 200 || !Array.isArray(value.unknowns) || value.unknowns.length > 80 || !value.unknowns.every((question) => text(question))) return false;
+  const ids = new Set();
+  for (const component of value.components) {
+    if (!component || !id(component.id) || ids.has(component.id) || !text(component.name, 160) || !text(component.description) ||
+      !['application', 'service', 'database', 'queue', 'storage', 'external'].includes(component.kind) || !finding(component)) return false;
+    ids.add(component.id);
+  }
+  return (ids.size > 0 || value.unknowns.length > 0) && value.connections.every((connection) =>
+    connection && ids.has(connection.from) && ids.has(connection.to) && text(connection.label, 200) && finding(connection));
+}
+
+export function readSystemArchitecture(markdown) {
+  const blocks = [...markdown.matchAll(/^```flowviant-architecture[^\S\r\n]*\r?\n([\s\S]*?)^```[^\S\r\n]*\r?$/gm)];
+  if (blocks.length === 0) return { status: markdown.includes('```flowviant-architecture') ? 'invalid' : 'missing' };
+  if (blocks.length !== 1) return { status: 'invalid' };
+  try {
+    const report = JSON.parse(blocks[0][1]);
+    return validArchitectureReport(report) ? { status: 'available', report } : { status: 'invalid' };
+  } catch {
+    return { status: 'invalid' };
+  }
+}