Clio Coder 0.3.7

Added

• Typed dispatch intent and host-run verification (#155). The singular request and every tasks[] item accept one intent object (read_roots, write_roots, relevant_paths, expected_outputs, verification: [{check, timeout_ms?}]); gate: "<check>" is the one shorthand for a single verification entry. Paths are normalized to sorted, duplicate-free repository-relative POSIX paths with entry and byte caps, and absolute, escaping, or malformed entries fail before approval. A check is a declared id resolved through the verify tool's DeclaredCheck projection (package scripts and .clio-coder/verifiers.yaml) at admission, so model text never becomes argv; the resolved argv, cwd, and timeout are frozen into the execution snapshot and the plan hash, and the approval artifact renders them. After a successful worker attempt the orchestrator runs each check through the code-step runner with no shell and the closed environment allowlist, memoizes successful evidence on the workspace fingerprint plus argv, cwd, and allowlisted environment values, and seals hostVerification (verified, rejected, or skipped with per-check argv, exit code, duration, bounded output tail, memo provenance, and artifact path) into the receipt. A rejected check turns the run into host_verification_rejected, which suppresses automatic retry. Review and compete accept the intent paths but refuse verification entries, as does the Claude Code subprocess runtime, each with a named reason. The receipt seals intent on the native worker path and the Claude Code and ACP delegation paths alike. Receipt integrity moves to v16 and covers intent and hostVerification; the existing verification evidence object keeps its name. Dispatch output, monitor, and the Fleet Runs card render host_verification=<status> beside evidence_verification.
• /btw <question> asks one side question beside the session (refs #41). The round sends the compiled message history as read-only input under a short fixed instruction with no tools, streams the answer into an overlay, and appends nothing to the session JSONL, the transcript, the context ledger, or the task board, so a fleet run's workers are never briefed from it. Esc cancels a streaming round; a /btw during an in-flight turn is refused rather than queued. The round's usage is counted in /cost under a side questions row and is excluded from the turn count.
• Opt-in desktop notifications (#204). terminal.notify: true emits one content-free terminal notification when a turn ends, when a detached batch settles, and when a worker permission or ask_user request parks. The title is fixed, the body comes from a closed vocabulary, control characters are stripped, and the body is bounded to 128 bytes. OSC 777 is the default and OSC 9 is used on iTerm2, Windows Terminal, and ConEmu, never both for one event. Headless, ACP, and non-TTY runs never emit one.
• Single-writer token, checkout writer lease, and worktree-per-task (#207). writers: 1 on a parallel dispatch or an ExecutionPlan admits at most one write-scope step at a time in declared order while read-scope steps stay concurrent; the agent ledger's claims remain advisory. The first checkout writer takes a lease under the state dir keyed by the canonical checkout path and carrying pid, process birth token, and acquisition time; a live sibling process is refused with checkout_writer_lease_held naming the holder pid, and a dead owner is reclaimed. worktree: true with apply: "merge" (default) or "preserve" runs a writer task on clio/task/<runId> under .clio-coder/worktrees/<runId>/, maps the worker cwd, write roots, and protected artifacts into it, and runs declared host verification there before merging; a conflict fails closed as worktree_merge_conflict and preserves the branch, and a protected-path change fails closed. The receipt gains worktree: {path, branch, diffHash, apply, applied, reason?}, receipt integrity moves to v17, and the approval artifact renders worktree, apply, and the frozen merge destination. Non-git checkouts, read-only agents, compete mode, and a cwd outside the checkout are refused with named reasons.
• Fleet authoring CLI (#209). clio-coder fleet new <name> --from <builtin> copies build-review, build-test, or sdlc into .clio-coder/fleets/ and refuses an existing destination, an unsafe stem, or an unknown builtin. fleet validate <name> [--json] runs the same preflight fleet run performs (parse, graph, command bindings, agent resolution, plan compile, write-boundary preflight) with no state-dir write, ledger row, reservation, or worker. fleet graph <name> [--json] prints the compiled waves with each step's kind, agent or command, scope, dependencies, and write boundary, and expands loop check and repair nodes. fleet commands init discovers package scripts, justfile recipes, Makefile targets, and pyproject script and tool entries through the verifier discovery and writes a fully commented commands.yaml draft; uncommenting confirms an entry and an existing registry is never replaced. fleet run <name> --resume <runId> replays the successful, integrity-valid prefix recorded in a durable fleet-run record under the state dir, reports replayed steps with their original receipt references, refuses a changed plan hash with a per-step diff, and refuses differing --var values. The existing fleet resume admission-control subcommand is unchanged.
• /fleet run <name> [--var k=v ...] previews a fleet contract before anything dispatches (#208). The route preflight sends each step's compiled task, so a contract that validates from the CLI previews from the TUI, and a --var value may be quoted to carry spaces (--var task="add a pow function"). The approval overlay lists the steps by wave with kind, agent and resolved target (or command id and the exact argv from commands.yaml), scope, and declared write boundary, then the budget ceiling the run is admitted under; a contract that fails preflight opens the same overlay with its diagnostics and no accept key. Enter dispatches through one shared fleet-run path in the dispatch domain (executeFleetRun) so admission, autonomy, receipts, gate decisions, write-boundary enforcement, and the durable ledger are identical to clio-coder fleet run; Esc dispatches nothing and writes nothing. clio-coder fleet run runs through that same path and both surfaces write the durable fleet-run record, so a run started from the TUI can be resumed with fleet run --resume. The Fleet Runs board gains a phase column (w<n> <stepId>) on rows a fleet plan dispatched, empty on every other row; the compact island keeps its fixed width and shows the column only when the agent label still fits. /fleet alone still opens Settings → Fleet, and /fleet run during an in-flight turn is refused rather than queued.
• /handoff <goal> carries a session's working state into a fresh session (#206). The goal is required and gated: under 12 characters, or a non-goal such as "continue" or "resume", is refused with the rule named. One out-of-turn model round with no tools extracts decisions, facts, files, commands, and open questions as JSON against a fixed schema; every list and string is bounded, and over-bound output is truncated with a visible marker rather than refused. Every file path is checked against the session's own read ledger (folded through the active /tree path) and never against the filesystem, so a path the session never touched is dropped and listed under dropped (not in this session's read ledger). Extracted decisions merge with the settled decision board, which wins. The document opens for review with e for $EDITOR; Esc cancels with nothing written. On accept Clio mints a session, seeds it with the reviewed document as data labelled by its origin session, replays the old session's skill activations, and leaves the old session untouched apart from one terminal note naming the target. A handoff never writes a memory promotion candidate and never calls the task-memory bank. Its usage is counted in /cost under a handoffs row and excluded from the turn count.
• /oracle <question> and the oracle shadow advisor (#210). The recipe is read-only, unreachable from /run, and never receives a forked transcript: /oracle packs a bounded digest as dispatch briefing data (settled decisions from the decision board, open tasks from the task board, the last compaction summary when one exists, and the question), capped at 12 KiB with per-section caps and a truncation marker and filtered to the active /tree branch. The run is a singular read-only internal dispatch through the ordinary path, so admission, receipts, and the Fleet Runs island apply; its oracle-report contract carries a verdict, the strongest challenge, what would change its mind, and the decisions it cited, and the rendered answer reaches the main agent as an operator note the way /share does. /oracle during an in-flight turn is refused rather than queued.
• Opt-in turn-end watchdog (#210). watchdog: {enabled: false, target?, cadenceToolCalls?} is hot reloaded. With enabled: true, a turn that changed the tree is reviewed by one read-only verifier dispatch briefed with the turn's coalesced diff (per-path last-write-wins, bounded to 12 KiB) and the task board's current scope; its failed checks become one transcript notice naming the count and the first three, a passing report emits nothing, and a turn with no file mutations never fires. watchdog.target routes the run at a cheap local model; cadenceToolCalls: N also fires it every N tool calls inside a turn. At most one watchdog run is in flight at a time and an overlapping trigger is dropped and counted. It never auto-follows, never queues a turn, and never mutates. Headless and ACP runs never fire it.
• Durable out-of-turn usage and Settings Center rows for notifications and the watchdog (#211, refs #41, #204, #206, #210). A /btw side question or a /handoff extraction round appends nothing to the session JSONL by contract, so the spend now goes to its own store at <stateDir>/usage/out-of-turn.jsonl: one JSON line per priced call carrying the label, session id, the repo identity the session ledger is filed under, timestamp, target, attributed model id, and provider usage, written with one append per row and kept as a bounded ring of 1000 rows rewritten atomically under the state-file lock. clio-coder usage report folds that store beside the session ledgers into the window's tokens, cost, and per-model totals, and prints turns, side questions, and handoffs counts on both the text and --json surfaces, subtracting labelled calls from the turn count exactly as /cost does; an archive with no labelled call renders byte-identical to before. terminal.notify gains a boolean row under EXPERIENCE › Terminal, and watchdog.enabled, watchdog.target, and watchdog.cadenceToolCalls gain rows under a new EXPERIENCE › Watchdog section. The two optional keys render their absence as (session target) and (turn end only) while their editors open on the stored value or empty, never on that prose; submitting an empty value removes the key from settings.yaml rather than storing a blank, and a cadence below one is refused with the bound named, matching the config validator. Settings Center wording is pinned word for word to the settings template where it overlaps.
• mode: "council", the read-only sibling of compete (#212). Two to five members run the same singular task concurrently on local and HTTP targets with no mutation. Members come from a configured workers.rosters.<name>.members[] roster ({label, target, model?, thinking?, color?}, validated at config load for two to five members, unique labels matching [a-z][a-z0-9_-]{0,31}, theme color tokens or six-digit hex, no unknown keys, hot reloaded) or from inline members; exactly one of roster or members is accepted. synthesis: none | judge | vote (default none), rounds: 1..3 (default 1), and judge only with judge synthesis. Refusals are typed: council_roster_unknown, council_members_out_of_range, council_member_label_duplicate, council_member_target_unknown, council_member_remote_node (a route that resolves to an SSH fleet node is refused before approval), council_synthesis_requires_judge_settings, and council_verification_unsupported. A council request that names no agent seats the builtin researcher rather than the dispatch default coder, whose write requirement the council profile cannot satisfy. Admission pins every member and the judge to read-only autonomy and an internal council-read-only tool profile holding exactly read, grep, find, ls, code_nav, and context, enforced through ordinary worker admission rather than prompt text. The resolved plan expands every member in every round plus the judge, so the approval artifact lists each member's label, target, model, thinking, node, color, round, and synthesis, and the plan hash binds all of it. Round one gives every member the same task and briefing; each later round gives a member the other members' prior answers as labelled untrusted briefing data (never its own), bounded to 8 KiB with a truncation marker, with a failed peer marked rather than quoted. vote computes a deterministic strict majority over the final round's structured verdict fields with no model call and reports no_verdict_field or no_majority when it cannot; judge runs one read-only judge under a fixed prompt with every final answer as labelled briefing. The dispatch result carries one section per member and one synthesis section, details.council holds the typed council-report ({members: [{label, runId, round, answer, verdict?, failed?}], synthesis: {kind, text?, verdict?, tally?, judgeRunId?}}), and the result is an error only when a final-round member or the judge failed. Every member run seals its own receipt; none and vote seal one coordinator-only zero-token synthesis receipt that carries no member provenance and publish its enqueued and completed lifecycle events so the Fleet Runs board and /share see it, and the judge receipt is the synthesis receipt in judge mode, each pointing backward at every final member run through gate provenance. monitor reports the council role and group, the Fleet Runs board projection carries council: {group, label, color?, round} for a later grid, and receipt integrity moves to v18 with the council field. The grid and /council are a separate change.
• Council rendering and /council (#213). The Alt+W Fleet Runs board folds a council group into one card in the position of its first row: a side-by-side grid with one column per member while every column keeps at least 34 cells, otherwise the whole group stacks, because a grid where only some columns are readable is worse than none. Each column shows the member label in its roster color (a theme token paints as that token, #rrggbb paints literally through the xterm cube without truecolor, anything else takes the accent), the target and model, the round and status, and up to four rows of the run's bounded answer tail; a council that ran several rounds keeps one column per member at its newest round, and the synthesis run renders full width under the members. The compact island shows one card per council naming the group, member count, and round. /council [--roster <name>] [--rounds <n>] [--synthesis judge|vote|none] <task> owns no dispatch path of its own: it builds dispatch-tool arguments spelled exactly as the tool declares them and admits them through the tool registry, so supervised autonomy parks the same approval overlay a model-asked council would. --roster falls back to workers.rosters.default; with neither the command refuses and names the setting rather than guessing from the only roster present. Rounds and synthesis bounds are enforced where the operator typed them, and a /council during an in-flight turn is refused rather than queued. /share <synthesis runId> brings every final-round member's labelled answer and the synthesis line (mode, verdict, tally, judge run) into the main context as one bounded prose block, never the raw payload; /share <member runId> labels that member's answer with its roster label; a synthesis whose sealed text does not parse is shared verbatim.
• Fleet contract v5: kind: plan, kind: gate, per-step target or profile, and top-level writers (#214). Version literal 5 joins the contract; readers of 1 to 4 refuse plan, gate, target, profile, and writers by name, exactly as they refuse writes below 4, and ExecutionPlan versioning is unchanged. An agent step, a loop check agent, or a loop repair agent may declare target: <targetId> or profile: <workers.profiles key> (never both); resolution shares the /run --target and /run --agent-profile request fields, and an unknown id refuses at preflight naming it, in fleet validate, fleet run, and the /fleet run preview, which now reports a route the process cannot resolve as a named diagnostic instead of rendering route unresolved. A kind: gate step names a validator agent, one repository-relative path that becomes its whole derived write boundary (a separate writes is refused), and a run command whose argv carries the gate path as the single whole-token {{path}} substitution; after the author settles, the coordinator runs the command with no shell against the untouched tree and requires red, a green baseline fails the step as gate_not_discriminating, the receipt seals fleetGate: {path, pathHash}, and a loop may use check: {kind: gate, gate: <id>}, in which case only verbatim FAIL lines from the check reach the repair agent. A kind: plan step (agent defaults to the builtin architect) declares roster, maxTasks: 1..16, optional proposals: true, its own scope and writes, and an optional route default; the architect returns a delegation-plan result contract ({tasks: [{id, agent, description, depends_on, writes, mode?}]}) that a pure validator checks for roster membership, task count, unique ids, resolvable acyclic dependencies, and writes inside the plan step's boundary, each failure a named delegation_plan_* reason that fails the step and splices nothing. delegation-plan is an admitted worker result contract, so the architect step reaches the model. On success the coordinator records the deterministic plan hash on the durable fleet run record and the scheduler splices the tasks into the live plan after the wave settles: every spliced task passes the same preflight, reservation, admission group, writer-token grouping, post-step write-boundary enforcement, and durable settlement record as a static step, depends on the plan step plus its declared dependencies, inherits the plan step's target or profile, and seals lineage to the plan step's run. proposals: true first runs every roster member read-only with the same task and hands the architect their PROPOSAL <agent> sections as briefing bounded to 12,000 bytes. fleet graph names a gate or plan step by its contract kind with the gate path and run command or the roster and maxTasks, and a step whose receipt succeeded but whose gate baseline or delegation plan failed settles as failed with reason=<name> in fleet run output and the /fleet run notice. The approval artifact renders target or profile, gate path, run command, and baseline command, and plan roster, maxTasks, and proposals; fleet run --resume replays the static prefix up to the first plan step and reruns it rather than reconstructing prior dynamic tasks. Receipt integrity moves to v19 with the fleetGate field.
• Resource library (#215). The marketplace index machinery that carries skills now carries agent recipes, prompt templates, and fleet contracts. Every index entry accepts kind: skill | agent | prompt | fleet (default skill, so every existing index parses unchanged) and optional typed requires: [skill:x, agent:y, prompt:p, fleet:z], resolved recursively across the selected catalog and the private catalog; a missing, malformed, or cyclic requirement refuses the entry with library_requirement_missing, library_requirement_malformed, or library_requirement_cycle naming the chain. clio-coder library list|search [--kind k] [--json], library add <ref> [--from <catalog|path>] [--with-requirements] [--yes], library use <kind> <name>, library sync, library push, and library remote confirm <url> land as one literal dynamic import. add resolves requirements against the pin store and the destination path, lists satisfied ones separately, refuses on unsatisfied ones unless --with-requirements installs them first in dependency order, prints every destination and SHA-256 before writing, and writes nothing without --yes. An agent installs to <configDir>/agents/<name>.md after the recipe schema and policy checks, a prompt to <configDir>/prompts/<name>.md after the prompt loader, a fleet to a new user fleet root <configDir>/fleets/<name>.md after parseFleetContract (precedence is builtin, then user, then project), and a skill through the existing installer; every install is pinned by typed ref and hash in <configDir>/library-pins.yaml through the safe resource write. A private catalog at library.catalog (default <configDir>/library.yaml) overlays same-ref marketplace entries and resolves relative sources beside itself. Git-backed sync is opt-in: library.sync: false (the default) refuses sync and push with library_sync_disabled before any process spawns; with it on, the repository's remote must be named library and match a confirmed URL (library remote confirm, which refuses library_remote_mismatch when it differs from library.remote), sync runs git fetch library then git merge --ff-only FETCH_HEAD, and push runs git push library, each an argv vector with no shell. Share archives gain agent and fleet entry types (share export --agents --fleets, included in --all), imported into the user roots after the same validation. The Skills Hub keeps rendering skills only; its kind tabs are a separate change.
• Skills Hub kind tabs and /library (#216). The hub carries one tab per resource library kind (Skills, Agents, Prompts, Fleets), switched with ←/→, the key vocabulary the Settings Center already uses to move between sections; the frame title names the active tab and the footer states its row count. The Skills tab is unchanged. The other three list their kind from the same discoverLibrary() the CLI's library list --kind reads, with origin, version, installed or available, the short pin hash, and the names of any unresolved requirements in the warning token; a catalog entry the library refuses appears as a diagnostic row rather than being omitted. i installs through the same classify, plan, and write sequence library add runs, behind a framed confirmation that states every destination and SHA-256 and writes nothing on Esc; an entry with unresolved requirements is refused by name on the first i, and a second i opens the install-with-requirements confirmation naming every entry it would write in dependency order. Enter on an installed row inserts /run <agent> for an agent, the /<id> invocation for a prompt, /skill <name> for a skill, and for a fleet closes the hub and opens the /fleet run approval preview; a row that is not installed says so and points at i. /library [kind] opens the hub on that tab and /library alone on Skills, where /skill still opens. Tab support lives in the shared list overlay, so untabbed overlays are unchanged.

Changed

• clio-coder fleet run now executes through the same executeFleetRun path as /fleet run, so admission, autonomy, receipts, gate decisions, write-boundary enforcement, and the durable fleet-run record under <stateDir>/fleet-runs/<runId>.json are identical from both surfaces, and a run started from either can be resumed with fleet run --resume (#208, #209). The fleet resume admission-control subcommand is unchanged.
• Fleet contracts resolve from three roots with fixed precedence: builtin, then the new user root <configDir>/fleets/, then the project's .clio-coder/fleets/ (#215). A project contract still shadows a user one of the same name.
• share export --all now includes agent recipes and fleet contracts beside the existing entry types, and share import validates them through the recipe schema and parseFleetContract before writing (#215). Archives without those entry types import unchanged.
• The /fleet run approval preview reports a step route the process cannot resolve as a named preflight diagnostic instead of rendering route unresolved (#214).
• clio-coder usage report prints turns, side questions, and handoffs counts on the text and --json surfaces (#211). An archive with no labelled out-of-turn call reports zero side questions and handoffs and the same tokens, cost, and per-model totals as before.
• Receipt integrity moves from v15 to v19 across this release: v16 adds intent and hostVerification (#155), v17 adds worktree (#207), v18 adds council (#212), and v19 adds fleetGate (#214). Receipts sealed by 0.3.6 fail verification under 0.3.7 and are never read as evidence; they are not migrated.
• clio-coder --help lists library beside skills.
• The /fleet run approval, /handoff review, and Skills Hub install confirmation overlays match Enter, Esc, and the arrows by key name rather than raw bytes, so they answer under the kitty keyboard protocol, where Esc arrives as CSI 27 u, and ignore key-release events.