rovecode 0.3.2

package/src/tools/bash-bg.ts

@@ -0,0 +1,94 @@
+/** The three tools that read and stop background shell jobs (port #55): `bash_list`, `bash_output`,
+ *  `bash_kill`. The job manager itself is tools/bash-jobs.ts; starting a job is `bash` with a flag.
+ *
+ *  WHY THREE READ/WRITE TOOLS AND NOT ONE. A model that starts a four-minute build has to be able to
+ *  ask three different questions — what is still running, what has it printed since I last looked, and
+ *  stop it — and folding them into one tool with an `action` argument means every call carries an
+ *  argument that could be wrong. The cost is three schema entries; the benefit is that each call says
+ *  what it does.
+ *
+ *  `bash_output` returns only what is NEW since the previous read, so a model polling a build sees the
+ *  next hundred lines rather than the same first hundred again. That is the single most important
+ *  property here: a tool that re-sends its whole buffer every time turns a long build into a context
+ *  leak, and the model cannot tell the repeat from real progress. When the ring dropped output the
+ *  reader had not yet seen, the read SAYS how much it lost — a gap a model is told about can be worked
+ *  around; a silent one is read as the command having printed nothing. */
+
+import type { Tool, ToolOutput } from "../core/types.ts";
+import { jobManager, type JobInfo } from "./bash-jobs.ts";
+
+const NO_MANAGER = "background jobs are not available on this surface";
+
+function describe(j: JobInfo, now: number): string {
+  const secs = Math.round(((j.finishedAt ?? now) - j.startedAt) / 1000);
+  const code = j.exitCode !== undefined ? ` exit=${j.exitCode}` : "";
+  const pid = j.pid !== undefined ? ` pid=${j.pid}` : "";
+  const drop = j.dropped > 0 ? ` (${j.dropped} chars dropped from the buffer)` : "";
+  return `${j.id} ${j.status}${code}${pid} ${secs}s — ${j.command}${drop}`;
+}
+
+export const bashListTool: Tool = {
+  schema: {
+    name: "bash_list",
+    description:
+      "List this session's background shell jobs (started with `bash … run_in_background: true`): id, status, exit code, pid, elapsed and the command. " +
+      "A finished job stays listed until its output has been read at least once, so nothing you started disappears unseen.",
+    args: { type: "object", properties: {} },
+  },
+  kind: "read",
+  execute(_args, _ctx): Promise<ToolOutput> {
+    const m = jobManager();
+    if (!m) return Promise.resolve({ ok: false, output: NO_MANAGER });
+    const jobs = m.list();
+    if (jobs.length === 0) return Promise.resolve({ ok: true, output: "no background jobs in this session" });
+    const now = Date.now();
+    return Promise.resolve({ ok: true, output: jobs.map((j) => describe(j, now)).join("\n"), data: jobs });
+  },
+};
+
+export const bashOutputTool: Tool = {
+  schema: {
+    name: "bash_output",
+    description:
+      "Read what a background job has printed SINCE YOUR LAST READ of it (not the whole buffer — repeated reads show progress, never the same lines twice). " +
+      "Says `more output remains` when the job printed more than one read returns, and says how many characters were dropped if the job outran its buffer. " +
+      "Do not poll in a tight loop: a finished job also posts one note into this conversation by itself.",
+    args: { type: "object", properties: { id: { type: "string", description: "job id from bash_list (e.g. b1)" } }, required: ["id"] },
+  },
+  kind: "read",
+  execute(args, _ctx): Promise<ToolOutput> {
+    const m = jobManager();
+    if (!m) return Promise.resolve({ ok: false, output: NO_MANAGER });
+    const id = String((args as { id: string }).id ?? "").trim();
+    if (id === "") return Promise.resolve({ ok: false, output: "bash_output needs an id (bash_list shows them)" });
+    const r = m.read(id);
+    if (!r.ok) return Promise.resolve({ ok: false, output: r.reason });
+    const head = describe(r.info, Date.now());
+    const lost = r.lost > 0 ? `\n[${r.lost} characters were dropped from this job's buffer before you read them]` : "";
+    const more = r.more ? "\n[more output remains — read again]" : "";
+    const body = r.text === "" ? "(nothing new)" : r.text;
+    return Promise.resolve({ ok: true, output: `${head}${lost}\n${body}${more}`, data: r.info });
+  },
+};
+
+export const bashKillTool: Tool = {
+  schema: {
+    name: "bash_kill",
+    description:
+      "Stop a background job and everything it started (the process TREE, not just the shell — a killed `npm run dev` must not leave its port bound). " +
+      "Killing an already-finished job is not an error. Its output stays readable afterwards.",
+    args: { type: "object", properties: { id: { type: "string", description: "job id from bash_list (e.g. b1)" } }, required: ["id"] },
+  },
+  kind: "execute",
+  execute(args, _ctx): Promise<ToolOutput> {
+    const m = jobManager();
+    if (!m) return Promise.resolve({ ok: false, output: NO_MANAGER });
+    const id = String((args as { id: string }).id ?? "").trim();
+    if (id === "") return Promise.resolve({ ok: false, output: "bash_kill needs an id (bash_list shows them)" });
+    const r = m.kill(id);
+    if (!r.ok) return Promise.resolve({ ok: false, output: r.reason ?? `could not kill "${id}"` });
+    return Promise.resolve({ ok: true, output: `${id} ${r.info?.status ?? "killed"} — its output is still readable with bash_output ${id}`, data: r.info });
+  },
+};
+
+export const bashJobTools: readonly Tool[] = [bashListTool, bashOutputTool, bashKillTool];

package/src/tools/bash-jobs.ts

@@ -0,0 +1,237 @@
+/** Background shell jobs (port #55). `bash … run_in_background: true` starts a job here instead of
+ *  awaiting it; `bash_list` / `bash_output` / `bash_kill` (tools/bash-bg.ts) read and stop them.
+ *
+ *  WHAT A JOB IS NOT. It is not an agent. TaskManager (core/tasks.ts) stays the one agent-job registry
+ *  and nothing in this file runs a loop. A job is one shell command whose output the run can come back
+ *  to — a dev server, a long build, a test suite that takes four minutes — and the reason it exists is
+ *  that the alternative is worse in both directions: a foreground `bash` either blocks the whole run
+ *  until the command finishes, or gets killed by a timeout and loses whatever it had printed.
+ *
+ *  SAME DOOR, SAME LOCKS. Every job runs through the SAME executor seam a foreground `bash` uses, so
+ *  the configured rung shapes its argv and `kill` is the rung's own tree kill (Windows Job Object +
+ *  taskkill sweep; SIGTERM to the process group on POSIX, #67 — a background `npm run dev` that forks
+ *  is exactly the case where killing only the launcher leaves the port bound). Policy is upstream:
+ *  the permission rules, execpolicy, hooks and the human approval all run before bashTool.execute, so
+ *  starting a job in the background is gated exactly like running it in the foreground. It is the same
+ *  tool with a flag, deliberately (ADR-005).
+ *
+ *  BOUNDS, because an unbounded buffer is a memory leak with a feature name:
+ *    MAX_JOBS      running at once; the next start is refused AS DATA, never thrown
+ *    RING_CHARS    decoded output kept per job; the oldest is dropped and the drop is COUNTED, and a
+ *                  read reports how many UNREAD characters it lost rather than silently skipping them
+ *    MAX_READ      one read returns at most this much and says `more` when output remains
+ *    KEEP_FINISHED finished jobs stay listed until a read has seen their final output; after that only
+ *                  the newest few are kept, buffers trimmed to a tail
+ *
+ *  A finished job posts ONE note through the mechanisms that already exist: a push into the run's
+ *  SteeringQueue (the loop drains it before the next model call, like a task note) and one listener
+ *  emission for the TUI's transcript. It does not interrupt a turn and it does not poll.
+ *
+ *  Pattern source (Apache-2.0, PATTERN LEVEL ONLY, no code copied): google-gemini/gemini-cli @ 0bd1d43
+ *  — `is_background` as a flag on the ONE shell tool, list rendering pid/status/command/exit code, a
+ *  bounded read that refuses a pid outside the session's own history, and a timed-out result that names
+ *  the timeout and keeps its partial output. Departures: a per-job cursor (each read returns only NEW
+ *  output) instead of a tail snapshot, an in-memory ring instead of a log file, a hard concurrency
+ *  bound, and the kill is the executor's tree-kill path rather than a bare signal. */
+
+import { getExecutor, type SpawnObserver } from "../core/executor.ts";
+import type { SteeringQueue } from "../core/loop.ts";
+
+export const MAX_JOBS = 4;
+export const RING_CHARS = 200_000;
+export const MAX_READ = 10_000;
+export const KEEP_FINISHED = 8;
+
+export type JobStatus = "running" | "exited" | "killed" | "failed";
+
+export interface JobInfo {
+  id: string;
+  command: string;
+  status: JobStatus;
+  startedAt: number;
+  finishedAt?: number;
+  /** the launcher's pid, once the process exists */
+  pid?: number;
+  /** the shell's exit code (exited/failed) */
+  exitCode?: number;
+  /** characters dropped from the ring because the job outran the buffer */
+  dropped: number;
+  /** true once a read has seen the job's final output — only then may it be reaped */
+  drained: boolean;
+}
+
+interface JobRecord {
+  info: JobInfo;
+  buf: string;
+  /** how far a reader has consumed `buf`; each read returns only what is new */
+  cursor: number;
+  ac: AbortController;
+  done: Promise<void>;
+}
+
+export interface JobManagerOptions {
+  /** where a finish note lands — the same queue the loop drains before its next model call */
+  notify?: SteeringQueue;
+  /** the run's signal: its abort kills every job, so background work never outlives the session */
+  owner?: AbortSignal;
+}
+
+export class BashJobManager {
+  private readonly jobs = new Map<string, JobRecord>();
+  private readonly listeners = new Set<(j: JobInfo) => void>();
+  private seq = 0;
+  private unbind?: () => void;
+
+  constructor(private readonly opts: JobManagerOptions = {}) {
+    const owner = opts.owner;
+    if (owner) {
+      const onAbort = (): void => { this.killAll(); };
+      owner.addEventListener("abort", onAbort, { once: true });
+      this.unbind = () => owner.removeEventListener("abort", onAbort);
+    }
+  }
+
+  /** Status-transition listener (the TUI's transcript note). Returns the unsubscribe. */
+  subscribe(fn: (j: JobInfo) => void): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  list(): JobInfo[] { return [...this.jobs.values()].map((j) => ({ ...j.info })); }
+
+  status(id: string): JobInfo | undefined {
+    const j = this.jobs.get(id);
+    return j ? { ...j.info } : undefined;
+  }
+
+  private get running(): number {
+    let n = 0;
+    for (const j of this.jobs.values()) if (j.info.status === "running") n++;
+    return n;
+  }
+
+  /** Start a job. Refusals are DATA — a full pool is a normal condition, not an exception. */
+  start(command: string, cwd: string): { ok: true; info: JobInfo } | { ok: false; reason: string } {
+    if (this.running >= MAX_JOBS) {
+      return { ok: false, reason: `${MAX_JOBS} background jobs already running (bash_list shows them; bash_kill frees a slot) — run this one in the foreground or wait` };
+    }
+    const id = `b${++this.seq}`;
+    const ac = new AbortController();
+    const rec: JobRecord = {
+      info: { id, command, status: "running", startedAt: Date.now(), dropped: 0, drained: false },
+      buf: "", cursor: 0, ac,
+      done: Promise.resolve(),
+    };
+    const dec = new TextDecoder();
+    const observe: SpawnObserver = {
+      onSpawn: (pid) => { rec.info.pid = pid; },
+      onChunk: (_stream, bytes) => { this.append(rec, dec.decode(bytes, { stream: true })); },
+    };
+    this.jobs.set(id, rec);
+    rec.done = getExecutor().run(command, cwd, ac.signal, observe).then(
+      (r) => {
+        // A killed job's non-zero exit is the kill, not the command's verdict — say which happened.
+        if (rec.info.status === "killed") { this.finish(rec); return; }
+        rec.info.status = r.code === 0 ? "exited" : "failed";
+        rec.info.exitCode = r.code;
+        // The observer streamed the bytes; the result's assembled text is the SAME output a foreground
+        // run would have returned, so appending it would double every line. Only the tail of a run that
+        // produced nothing through the taps (a rung that does not observe) is taken from the result.
+        if (rec.buf === "" && r.text !== "") this.append(rec, r.text);
+        this.finish(rec);
+      },
+      (e: unknown) => {
+        rec.info.status = "failed";
+        this.append(rec, `\n[job runner threw: ${e instanceof Error ? e.message : String(e)}]`);
+        this.finish(rec);
+      },
+    );
+    return { ok: true, info: { ...rec.info } };
+  }
+
+  private append(rec: JobRecord, text: string): void {
+    if (text === "") return;
+    rec.buf += text;
+    if (rec.buf.length > RING_CHARS) {
+      const cut = rec.buf.length - RING_CHARS;
+      rec.buf = rec.buf.slice(cut);
+      rec.info.dropped += cut;
+      // the cursor moves with the window; what a reader has not read yet and lost is reported at read time
+      rec.cursor = Math.max(0, rec.cursor - cut);
+    }
+  }
+
+  private finish(rec: JobRecord): void {
+    rec.info.finishedAt = Date.now();
+    const info: JobInfo = { ...rec.info };
+    for (const l of this.listeners) l(info);
+    // ONE note, through the queue the loop already drains — never an interrupt, never a poll
+    const how = rec.info.status === "killed" ? "killed" : `exit=${rec.info.exitCode}`;
+    this.opts.notify?.push(`background job ${rec.info.id} finished (${how}): ${clip(rec.info.command, 60)} — bash_output ${rec.info.id} reads what it printed`);
+    this.reap();
+  }
+
+  /** Read only what is NEW since the last read. `lost` is unread output the ring dropped: a reader that
+   *  is told "you missed 40k characters" can act on it; one that is silently handed a gap cannot. */
+  read(id: string): { ok: false; reason: string } | { ok: true; info: JobInfo; text: string; more: boolean; lost: number } {
+    const rec = this.jobs.get(id);
+    if (!rec) return { ok: false, reason: `no background job "${id}" in this session (bash_list shows them; a finished job is dropped after its output has been read)` };
+    const lostBefore = rec.info.dropped;
+    const fresh = rec.buf.slice(rec.cursor);
+    const text = fresh.slice(0, MAX_READ);
+    rec.cursor += text.length;
+    const more = rec.cursor < rec.buf.length;
+    if (!more && rec.info.status !== "running") { rec.info.drained = true; this.reap(); }
+    return { ok: true, info: { ...rec.info }, text, more, lost: lostBefore };
+  }
+
+  /** Kill a job through the executor's own abort path — the tree, not just the launcher. */
+  kill(id: string): { ok: boolean; reason?: string; info?: JobInfo } {
+    const rec = this.jobs.get(id);
+    if (!rec) return { ok: false, reason: `no background job "${id}" in this session` };
+    if (rec.info.status !== "running") return { ok: true, info: { ...rec.info } };
+    rec.info.status = "killed";
+    rec.ac.abort();
+    return { ok: true, info: { ...rec.info } };
+  }
+
+  killAll(): number {
+    let n = 0;
+    for (const j of this.jobs.values()) if (j.info.status === "running") { this.kill(j.info.id); n++; }
+    return n;
+  }
+
+  /** Wait for every job to settle (surface shutdown / tests). */
+  async drain(): Promise<void> { await Promise.allSettled([...this.jobs.values()].map((j) => j.done)); }
+
+  dispose(): void { this.killAll(); this.unbind?.(); this.listeners.clear(); }
+
+  /** Drop drained finished jobs beyond KEEP_FINISHED, oldest first. A finished job whose output nobody
+   *  has read is NEVER dropped: that output is the only record the command ever ran. */
+  private reap(): void {
+    const done = [...this.jobs.values()].filter((j) => j.info.status !== "running" && j.info.drained);
+    if (done.length <= KEEP_FINISHED) return;
+    done.sort((a, b) => (a.info.finishedAt ?? 0) - (b.info.finishedAt ?? 0));
+    for (const j of done.slice(0, done.length - KEEP_FINISHED)) this.jobs.delete(j.info.id);
+  }
+}
+
+const clip = (s: string, n: number): string => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+
+// ---------- the one manager a runtime installs ----------
+//
+// bashTool has to reach the manager without every call site threading it, and a runtime must be able to
+// exist without one (the `tools` listing, the gauntlet, a unit test): so `run_in_background` with no
+// manager installed is a refusal that names the surface, never a silent foreground run. A background
+// request that quietly ran in the foreground would block the run it was asked not to block.
+
+let installed: BashJobManager | null = null;
+
+export function installJobManager(m: BashJobManager | null): void { installed = m; }
+export function hasJobManager(): boolean { return installed !== null; }
+export function jobManager(): BashJobManager | null { return installed; }
+
+export function startBashJob(command: string, cwd: string): { ok: true; info: JobInfo } | { ok: false; reason: string } {
+  if (!installed) return { ok: false, reason: "background jobs are not available on this surface — run the command in the foreground (drop run_in_background)" };
+  return installed.start(command, cwd);
+}

package/src/tools/design.ts

@@ -0,0 +1,151 @@
+/** design_audit / design_direction — the agent's half of the design protocol (design/rules.ts).
+ *
+ *  Split like provider_list/provider_edit (and task/task_status) for the same reason: reading must
+ *  never cost a prompt, writing must be visible.
+ *    - design_audit is kind "read" -> policy action file.read, auto-allowed under the gated rules and
+ *      in plan mode. Checking your own work has to be free, or it will not happen.
+ *    - design_direction is kind "custom" -> action tool.design_direction, PROMPT under the gated rules
+ *      (cli/runtime.ts buildCfg), denied in plan mode by the blanket tool.* rule, allowed under yolo.
+ *      It writes the project's design identity, and the approval card is where the human sees exactly
+ *      what is being recorded on their behalf. It is asked ONCE per project, which is the whole design
+ *      of the feature -- so the one prompt is the point, not friction.
+ *
+ *  design_direction deliberately cannot invent a direction: `set` records what the human chose. The
+ *  model is expected to have asked first (the prompt section says so). Nothing here can enforce that
+ *  -- what it can do is keep the record honest and put the write in front of a human once. */
+
+import { isAbsolute, relative, resolve } from "node:path";
+import type { Tool, ToolOutput } from "../core/types.ts";
+import { auditFiles, auditProject, formatFindings, type Finding } from "../design/audit.ts";
+import {
+  designPath, loadDirection, parseDirection, renderDirection, saveDirection,
+  type DesignDirection,
+} from "../design/direction.ts";
+
+/** Resolve a caller-supplied path against the run's cwd and refuse to leave it: an audit is about
+ *  THIS project's files, and a read tool that wanders is a read tool nobody can reason about. */
+function insideCwd(cwd: string, p: string): string | null {
+  const abs = isAbsolute(p) ? resolve(p) : resolve(cwd, p);
+  const rel = relative(resolve(cwd), abs);
+  return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? null : abs;
+}
+
+export function designAuditTool(): Tool {
+  return {
+    schema: {
+      name: "design_audit",
+      description:
+        "Check interface code for the patterns that arrive when nobody decided (a webfont loaded without a choice, amber doing accent duty, the three-up feature grid, a centred full-viewport hero, the violet-to-blue gradient, nothing but square corners) and for drift from the direction this project recorded in .rovecode/design.json. Run it on the SOURCE TREE, not on a fetched page: a built page measures the framework's output, not the design. Pass the page files you touched along with the components they import, because density and centring are scored per page and 'no rounded corner anywhere' is scored per project. It reports evidence, not verdicts: each finding says what it counted, so you can fix it or explain why it is wrong here. Never prompts, never writes.",
+      args: {
+        type: "object",
+        properties: {
+          files: { type: "array", items: { type: "string" }, description: "paths inside the project to audit (html/css/jsx/tsx/vue/svelte)" },
+          source: { type: "string", description: "audit this markup/CSS directly instead of reading files" },
+          ignore: { type: "array", items: { type: "string" }, description: "rule ids to skip (the full table is in docs/design.md): cliche-font, font-deviation, font-named-not-loaded, cliche-accent-amber, accent-deviation, template-grid, template-icons, reflex-hero, cliche-gradient, off-palette, decoration-density, rule-line-density, everything-centered, all-square" },
+        },
+      },
+    },
+    kind: "read",
+    sequential: false,
+    async execute(args, ctx): Promise<ToolOutput> {
+      const a = (args && typeof args === "object" ? args : {}) as { files?: string[]; source?: string; ignore?: string[] };
+      const direction = loadDirection(ctx.cwd);
+      const ignore = a.ignore ?? [];
+      const findings: Finding[] = [];
+
+      // `source` is one pathless page: auditProject treats a lone file as a page so pasted markup still
+      // gets the page-scoped density and centring checks (auditSource alone is file-scope by design).
+      if (typeof a.source === "string" && a.source.length > 0) {
+        findings.push(...auditProject([{ path: "source", text: a.source }], { direction, ignore }));
+      }
+      const paths = a.files ?? [];
+      if (paths.length > 0) {
+        const resolved: string[] = [];
+        const outside: string[] = [];
+        for (const p of paths) {
+          const abs = insideCwd(ctx.cwd, p);
+          if (abs === null) outside.push(p); else resolved.push(abs);
+        }
+        if (outside.length > 0) {
+          return { ok: false, output: `design_audit only reads files inside the project. Outside: ${outside.join(", ")}` };
+        }
+        findings.push(...auditFiles(resolved, { direction, ignore }).map((f) => ({
+          ...f, ...(f.file !== undefined ? { file: relative(resolve(ctx.cwd), f.file) || f.file } : {}),
+        })));
+      }
+      if (paths.length === 0 && (a.source === undefined || a.source.length === 0)) {
+        return { ok: false, output: "design_audit needs `files` (paths inside the project) or `source` (markup/CSS text)." };
+      }
+      return { ok: true, output: formatFindings(findings, direction), data: { findings, direction } };
+    },
+  };
+}
+
+export function designDirectionTool(): Tool {
+  return {
+    schema: {
+      name: "design_direction",
+      description:
+        "Read or record this project's design direction (.rovecode/design.json). `get` returns the recorded direction, or says none is recorded. `set` records the direction THE HUMAN CHOSE after you proposed three — do not call it with a direction you picked yourself. The one exception is a headless run where nothing can ask a human: then build ONE direction and record it with provisional:true and the other two in `alternatives`, so the next interactive session asks before more UI is built. Recording it is what makes the choice a once-per-project question and lets design_audit check later screens for consistency.",
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["get", "set"] },
+          name: { type: "string", description: "short name of the chosen direction, as presented to the human" },
+          rationale: { type: "string", description: "one line: why it suits this product" },
+          palette: { type: "object", description: "chosen colours, e.g. {\"ink\":\"#0b1a2e\",\"accent\":\"#c2410c\"}" },
+          typeface: { type: "object", description: "{\"display\":\"...\",\"text\":\"...\"}" },
+          corners: { type: "string", enum: ["sharp", "soft", "round"] },
+          layout: { type: "string", enum: ["centered", "left", "asymmetric", "grid"] },
+          density: { type: "string", enum: ["tight", "regular", "airy"] },
+          sectionOrder: { type: "array", items: { type: "string" }, description: "the page's blocks in order, e.g. [\"hero\",\"proof\",\"pricing\",\"faq\"]" },
+          heroPattern: { type: "string", description: "the hero pattern by name, e.g. \"command-first\" or \"product-forward\"" },
+          typeScale: { type: "array", items: { type: "number" }, description: "the chosen type steps, e.g. [14,16,20,28,44]" },
+          motion: { type: "string", description: "the motion rule in the human's words, e.g. \"one entrance per section, no loops\"" },
+          copyRegister: { type: "string", description: "how the copy reads, e.g. \"technical, names and numbers, no marketing verbs\"" },
+          notes: { type: "string", description: "what the audit cannot infer: imagery, what to avoid here" },
+          provisional: { type: "boolean", description: "true ONLY when no human could be asked (a headless run): you built to one direction to get unblocked. Never true when a human answered." },
+          alternatives: { type: "array", items: { type: "string" }, description: "with provisional: the names of the directions you did NOT build, so the next interactive session can offer them" },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "custom",
+    sequential: true,
+    // `get` reads .rovecode/design.json and writes nothing; `set` records the project's design
+    // identity. Only the second is worth a human's attention, so the two get their own policy
+    // resource (types.ts Tool.resource) instead of sharing one rule under the tool name. Anything
+    // that is not the literal "get" is treated as the write: an unknown action must not read as
+    // the safer of the two.
+    resource(args: unknown): string {
+      const a = args && typeof args === "object" ? (args as Record<string, unknown>) : undefined;
+      return a?.["action"] === "get" ? "get" : "set";
+    },
+    async execute(args, ctx): Promise<ToolOutput> {
+      const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+      if (a["action"] === "get") {
+        const d = loadDirection(ctx.cwd);
+        return d === null
+          ? { ok: true, output: `No design direction recorded for this project (${designPath(ctx.cwd)} does not exist). Propose three distinct directions and let the human choose before writing UI. If nothing here can ask a human, build ONE and record it with provisional: true.` }
+          : { ok: true, output: renderDirection(d), data: d };
+      }
+      if (a["action"] !== "set") return { ok: false, output: "design_direction: action must be \"get\" or \"set\"." };
+
+      const parsed: DesignDirection | null = parseDirection(a);
+      if (parsed === null) {
+        return { ok: false, output: "design_direction set needs at least `name` — the short name of the direction the human chose." };
+      }
+      // Who chose is DERIVED, never taken from the call: `provisional` means the agent picked, its
+      // absence means a human did. Trusting the model with both fields lets one contradict the other,
+      // and the whole point of the field is that it can be believed. Stamped on every write, so a
+      // record always says who — absent is only ever a file written before the field existed.
+      parsed.chosenBy = parsed.provisional === true ? "agent" : "human";
+      const path = saveDirection(ctx.cwd, parsed);
+      if (parsed.provisional === true) {
+        const alts = parsed.alternatives === undefined ? "" : ` The alternatives (${parsed.alternatives.join(", ")}) are recorded with it.`;
+        return { ok: true, output: `Recorded "${parsed.name}" in ${path} as PROVISIONAL — you chose it, not the human.${alts} Build to it and say so in your final summary, naming what you did not build. The next interactive session asks before more UI is written.`, data: parsed };
+      }
+      return { ok: true, output: `Recorded "${parsed.name}" in ${path}. Later UI in this project is built to it, and design_audit checks against it.`, data: parsed };
+    },
+  };
+}