privateer-agent 0.3.6 → 0.4.0

package/src/remote/subagentChannel.ts

@@ -0,0 +1,261 @@
+// Child → parent approval/prompt relay for subagents.
+//
+// pi-subagents runs each subagent as a headless child `pi` process with stdin
+// IGNORED (`-p --mode json`), so the child's permission gate has no interactive
+// way to reach a human. When the child is guarded by privateer's moat (the
+// discovered gate shim) a gated action would otherwise just fail-closed (deny).
+// This module gives that child a way OUT: it writes its approval request to a
+// per-session directory on disk; the PARENT privateer session (which owns the
+// RemoteBridge / relay to the app) watches that directory, relays the request to
+// the phone for Allow/Deny, and writes the answer back as a reply file the child
+// is polling for.
+//
+// Why our own channel and not pi-subagents' supervisor channel: we own BOTH
+// processes, and the gate ask is a Pi permission decision — not a
+// `contact_supervisor` tool call — so piggy-backing on pi-subagents' internal
+// channel would couple us to its provisioning. A privateer-owned dir, addressed
+// by an env var we set (inherited through pi-subagents' `{...process.env}` spawn),
+// is fully under our control and unit-testable without a live Pi.
+//
+// Transport shape (mirrors pi-subagents' own request/reply-file dance so the
+// semantics are familiar): `<dir>/requests/<id>.json` written atomically by the
+// child; `<dir>/replies/<id>.json` written atomically by the parent; the parent
+// deletes the request once answered. Everything is fail-closed: no parent, a gone
+// controller, a timeout, or an abort all resolve the child to "deny"/null.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+// The env var carrying the channel dir to a subagent child. Set by the parent into
+// its OWN process.env before subagents spawn, so pi-subagents' `{...process.env}`
+// spawn inherits it into every (possibly nested) child.
+export const SUBAGENT_CHANNEL_ENV = "PRIVATEER_SUBAGENT_CHANNEL";
+
+// A relayed permission approval. `kind`/`title`/`detail` mirror PermissionRequest
+// so the parent can hand it straight to the bridge's requestApproval.
+export interface ApprovalAsk {
+  type: "approval";
+  kind?: string;
+  title: string;
+  detail: string;
+}
+
+// A relayed selection prompt (an extension's ctx.ui.select in the child).
+export interface SelectAsk {
+  type: "select";
+  title: string;
+  options: { value: string; label: string; hint?: string }[];
+  current?: string;
+}
+
+// A relayed free-form text prompt (an extension's ctx.ui.input in the child).
+export interface InputAsk {
+  type: "input";
+  title: string;
+  placeholder?: string;
+}
+
+export type SubagentAsk = ApprovalAsk | SelectAsk | InputAsk;
+
+// The parent's answer. `decision` for approvals ("allow"/"deny"); `value` for
+// select/input (the chosen value / typed line, or null for a dismiss/deny).
+export interface SubagentReply {
+  decision?: "allow" | "deny";
+  value?: string | null;
+}
+
+interface RequestEnvelope {
+  id: string;
+  ask: SubagentAsk;
+  // The subagent that raised it, for display/audit (best-effort; from env).
+  agent?: string;
+}
+
+interface ReplyEnvelope {
+  id: string;
+  reply: SubagentReply;
+}
+
+// Deterministic per-session channel dir. Keyed by the PARENT session id so a parent
+// watches exactly the children it spawned, and two concurrent parents never cross
+// wires. Under the OS temp dir (world-unreadable 0700), never the repo/agent dir.
+export function channelDirForSession(sessionId: string): string {
+  const safe = sessionId.replace(/[^\w.-]+/g, "_") || "session";
+  return join(tmpdir(), "privateer-subagent-channels", safe);
+}
+
+function requestsDir(dir: string): string {
+  return join(dir, "requests");
+}
+function repliesDir(dir: string): string {
+  return join(dir, "replies");
+}
+
+// Create the channel dir tree (idempotent). Parent calls this before advertising the
+// env var; child tolerates a missing tree by treating it as "no parent" (deny).
+export function ensureChannelDir(dir: string): void {
+  mkdirSync(requestsDir(dir), { recursive: true, mode: 0o700 });
+  mkdirSync(repliesDir(dir), { recursive: true, mode: 0o700 });
+}
+
+// Atomic JSON write: write a sibling temp file then rename, so a reader never sees a
+// half-written file (rename is atomic within a dir on POSIX).
+function writeJsonAtomic(path: string, value: unknown): void {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function readJson<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function safeUnlink(path: string): void {
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    /* already gone */
+  }
+}
+
+// ── child side ───────────────────────────────────────────────────────────────
+
+export interface AskOptions {
+  timeoutMs?: number;
+  pollMs?: number;
+  signal?: AbortSignal;
+  agent?: string;
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60_000; // match pi-subagents' 10-min ask ceiling
+const DEFAULT_POLL_MS = 200;
+
+// Forward an ask to the parent and await its reply. Resolves to the reply, or null
+// on timeout / abort / no channel — every non-answer is a fail-closed null so the
+// caller (the gate) denies. Safe to call from a headless child with no stdio.
+export async function askParent(dir: string, ask: SubagentAsk, opts: AskOptions = {}): Promise<SubagentReply | null> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  const id = randomUUID();
+  const reqPath = join(requestsDir(dir), `${id}.json`);
+  const replyPath = join(repliesDir(dir), `${id}.json`);
+  try {
+    ensureChannelDir(dir);
+    writeJsonAtomic(reqPath, { id, ask, agent: opts.agent } satisfies RequestEnvelope);
+  } catch {
+    return null; // no channel / unwritable → fail closed
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  try {
+    for (;;) {
+      if (opts.signal?.aborted) return null;
+      const reply = readJson<ReplyEnvelope>(replyPath);
+      if (reply && reply.id === id) return reply.reply ?? null;
+      if (Date.now() >= deadline) return null;
+      await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())), opts.signal);
+    }
+  } finally {
+    // Best-effort cleanup so a timed-out/aborted request doesn't linger and a stale
+    // reply doesn't confuse a later run (ids are unique, but keep the dir tidy).
+    safeUnlink(reqPath);
+    safeUnlink(replyPath);
+  }
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (ms <= 0) return resolve();
+    const t = setTimeout(done, ms);
+    const onAbort = () => done();
+    function done() {
+      clearTimeout(t);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// ── parent side ──────────────────────────────────────────────────────────────
+
+export interface WatcherHandle {
+  stop: () => void;
+}
+
+// The parent's answerer: given a child's ask, return the reply (relaying to the app
+// and awaiting the human, in the real wiring). Returning a rejecting/denying reply
+// or throwing both fail closed — the watcher writes a deny/null reply on a throw.
+export type AskHandler = (ask: SubagentAsk, meta: { id: string; agent?: string }) => Promise<SubagentReply>;
+
+export interface WatchOptions {
+  pollMs?: number;
+  onError?: (err: unknown) => void;
+}
+
+// Watch the channel for child requests, answer each via `handler`, and write the
+// reply back (then delete the request). Requests are handled at most once — an id is
+// marked in-flight before the async handler runs so a fast poll can't double-serve.
+// A handler that throws yields a fail-closed reply (deny / null value). Returns a
+// handle whose stop() ends the poll loop.
+export function watchSubagentChannel(dir: string, handler: AskHandler, opts: WatchOptions = {}): WatcherHandle {
+  const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+  const inFlight = new Set<string>();
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const failClosed = (ask: SubagentAsk): SubagentReply =>
+    ask.type === "approval" ? { decision: "deny" } : { value: null };
+
+  const serve = (id: string, env: RequestEnvelope): void => {
+    inFlight.add(id);
+    void Promise.resolve()
+      .then(() => handler(env.ask, { id, agent: env.agent }))
+      .catch((err) => {
+        opts.onError?.(err);
+        return failClosed(env.ask);
+      })
+      .then((reply) => {
+        try {
+          writeJsonAtomic(join(repliesDir(dir), `${id}.json`), { id, reply } satisfies ReplyEnvelope);
+        } catch (err) {
+          opts.onError?.(err);
+        } finally {
+          safeUnlink(join(requestsDir(dir), `${id}.json`));
+          inFlight.delete(id);
+        }
+      });
+  };
+
+  const tick = (): void => {
+    if (stopped) return;
+    try {
+      ensureChannelDir(dir);
+      for (const name of readdirSync(requestsDir(dir))) {
+        if (!name.endsWith(".json")) continue;
+        const id = name.slice(0, -5);
+        if (inFlight.has(id)) continue;
+        const env = readJson<RequestEnvelope>(join(requestsDir(dir), name));
+        if (env && env.id === id && env.ask) serve(id, env);
+      }
+    } catch (err) {
+      opts.onError?.(err);
+    }
+    if (!stopped) timer = setTimeout(tick, pollMs);
+  };
+
+  tick();
+
+  return {
+    stop: () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+  };
+}

package/src/remote/subagentRelay.ts

@@ -0,0 +1,126 @@
+// Adapters that connect the subagent approval channel (src/remote/subagentChannel.ts)
+// to the two ends that use it:
+//
+//   • CHILD side — makeChildGateAsk(): an `Asker` the discovered permission-gate uses
+//     as its `localAsk` when running inside a subagent child. Instead of denying a
+//     gated action headlessly, it forwards the approval to the parent and maps the
+//     reply to an AskOutcome. Fail-closed: no channel / timeout / deny → "deny".
+//
+//   • PARENT side — startParentApprovalRelay(): a top-level privateer session ensures
+//     the channel dir, advertises it to descendants via env, and watches it — relaying
+//     each child ask to the app over its RemoteBridge (remoteAsk / selectRemote /
+//     inputRemote) and writing the answer back. When no controller is attached the
+//     bridge's own fail-closed posture denies, so an undriven terminal never
+//     auto-approves a subagent's gated action.
+//
+// The channel dir is per ROOT parent and inherited by every (nested) descendant, so
+// an approval raised at any subagent depth reaches the one session that holds the app
+// relay. A subagent child never starts its own watcher — it only forwards.
+
+import type { PermissionRequest } from "../permissions/gate.ts";
+import type { AskOutcome, Asker } from "../permissions/modeGate.ts";
+import type { SelectRequest, InputRequest } from "./remoteBridge.ts";
+import {
+  askParent,
+  watchSubagentChannel,
+  ensureChannelDir,
+  channelDirForSession,
+  SUBAGENT_CHANNEL_ENV,
+  type SubagentAsk,
+  type SubagentReply,
+  type WatcherHandle,
+} from "./subagentChannel.ts";
+import { randomUUID } from "node:crypto";
+
+// True when this process IS a subagent child (pi-subagents sets PI_SUBAGENT_CHILD=1).
+export function isSubagentChild(): boolean {
+  return process.env.PI_SUBAGENT_CHILD === "1";
+}
+
+// The channel dir advertised to this process (set by the root parent, inherited by
+// every child through the environment). Undefined → no relay wired → fail closed.
+export function inheritedChannelDir(): string | undefined {
+  const d = process.env[SUBAGENT_CHANNEL_ENV]?.trim();
+  return d || undefined;
+}
+
+// This subagent's role name (for display/audit on the parent), best-effort from env.
+function childAgentName(): string | undefined {
+  return process.env.PI_SUBAGENT_CHILD_AGENT?.trim() || undefined;
+}
+
+// ── child side ───────────────────────────────────────────────────────────────
+
+// Build the `localAsk` a subagent child's gate should use: forward the approval to
+// the parent over the inherited channel. A child NEVER returns "always" (it must not
+// mutate the human's allowlist/mode); only "allow"/"deny". If no channel is wired,
+// or the parent doesn't answer, it denies — the same fail-closed stance as a headless
+// gate with no UI.
+export function makeChildGateAsk(dir: string): Asker {
+  const agent = childAgentName();
+  return async (req: PermissionRequest): Promise<AskOutcome> => {
+    const ask: SubagentAsk = { type: "approval", kind: req.kind, title: req.title, detail: req.detail };
+    const reply = await askParent(dir, ask, { agent });
+    return reply?.decision === "allow" ? "allow" : "deny";
+  };
+}
+
+// ── parent side ──────────────────────────────────────────────────────────────
+
+// The subset of RemoteBridge the parent relay needs. RemoteBridge implements it.
+export interface ApprovalRelayBridge {
+  isConnected(): boolean;
+  remoteAsk(req: PermissionRequest, signal?: AbortSignal): Promise<AskOutcome>;
+  selectRemote(req: SelectRequest, signal?: AbortSignal): Promise<string | null>;
+  inputRemote(req: InputRequest, signal?: AbortSignal): Promise<string | null>;
+}
+
+// Map one child ask to the app over the bridge and return the reply. When no
+// controller is attached the bridge fails closed (remoteAsk→"deny", select/input→
+// null), so an undriven terminal denies a subagent's gated action rather than
+// auto-approving it.
+export async function relayAskToApp(bridge: ApprovalRelayBridge, ask: SubagentAsk): Promise<SubagentReply> {
+  switch (ask.type) {
+    case "approval": {
+      const outcome = await bridge.remoteAsk({
+        tool: "subagent",
+        kind: (ask.kind as PermissionRequest["kind"]) ?? "bash",
+        title: ask.title,
+        detail: ask.detail,
+      });
+      return { decision: outcome === "deny" ? "deny" : "allow" };
+    }
+    case "select": {
+      const value = await bridge.selectRemote({ title: ask.title, options: ask.options, current: ask.current });
+      return { value };
+    }
+    case "input": {
+      const value = await bridge.inputRemote({ title: ask.title, placeholder: ask.placeholder });
+      return { value };
+    }
+  }
+}
+
+export interface ParentRelayHandle extends WatcherHandle {
+  dir: string;
+}
+
+// Start the parent-side approval relay for a top-level session. Ensures the channel
+// dir, advertises it to descendants via SUBAGENT_CHANNEL_ENV (only if not already
+// set — a nested privateer session, which shouldn't happen, must not clobber the
+// root's), and watches it, relaying each ask to the app over `bridge`. Returns a
+// handle whose stop() ends the watcher (call on session teardown).
+//
+// No-op-ish for a subagent child: a child must never watch (it has no app relay) — it
+// only forwards. Callers are top-level sessions, but this guards anyway.
+export function startParentApprovalRelay(
+  bridge: ApprovalRelayBridge,
+  opts: { onError?: (err: unknown) => void } = {},
+): ParentRelayHandle | null {
+  if (isSubagentChild()) return null;
+  const dir = inheritedChannelDir() ?? channelDirForSession(`${process.pid}-${randomUUID()}`);
+  process.env[SUBAGENT_CHANNEL_ENV] = dir; // advertise to children spawned after this
+  ensureChannelDir(dir);
+  const watcher = watchSubagentChannel(dir, (ask) => relayAskToApp(bridge, ask), { onError: opts.onError });
+  return { dir, stop: watcher.stop };
+}

package/src/remote/workflowsControl.ts

@@ -0,0 +1,132 @@
+/**
+ * Workflow management for the app (§8.3).
+ *
+ * The sibling of routinesControl.ts / channelsControl.ts, for declarative workflow
+ * graphs. UI-agnostic: nothing here imports React or the relay — the caller (the
+ * daemon) owns the frame plumbing, the signed-frame gate (authorizeControl), and the
+ * run seam. Like routines, workflows are owned by the DAEMON (they run on its resident
+ * scheduler / on-demand), so this control is wired into the daemon's own relay.
+ *
+ * A workflow file is an EXECUTABLE artifact (it can carry `script` steps), so the
+ * daemon MUST verify the account signature on every mutating frame (workflows_save /
+ * remove / run) via guardControl BEFORE calling save/remove/run here — a forged save
+ * would plant a script step, a forged run would execute one. `list`/`get` are read-only.
+ *
+ * Scheduling is NOT here: a workflow is triggered by a routines.json entry naming it
+ * (§8.3), so enabled/cron/bookkeeping live in the routines layer. This control only
+ * creates/edits/removes the graph and runs one on demand.
+ */
+import {
+  loadWorkflows,
+  loadWorkflow,
+  findWorkflow,
+  saveWorkflow,
+  removeWorkflow,
+} from "../workflows/store.ts";
+import { Workflow, validateWorkflow, newWorkflowId } from "../workflows/schema.ts";
+
+// A compact summary for the app's list screen — cheap to render, no full graph. The
+// editor fetches the whole Workflow separately via `get`.
+export interface WorkflowSummary {
+  id: string;
+  name: string;
+  description?: string;
+  entryPoint: string;
+  // Counts across the flat graph, so the card can show "5 steps · 2 gates" at a glance.
+  stepCount: number;
+  gateCount: number;
+  scriptCount: number;
+}
+
+export interface WorkflowsControl {
+  // All saved workflows as summaries, sorted by name.
+  list(): WorkflowSummary[];
+  // The full graph for one workflow (the app's editor), or undefined if absent.
+  get(idOrName: string): Workflow | undefined;
+  // Create (no workflow.id) or overwrite (existing id) a workflow. Validates the strict
+  // schema AND the route graph; rejects a name that collides with a different workflow.
+  save(draft: unknown): { ok: boolean; message?: string; id?: string };
+  // Remove a workflow by id or name. ok:false when nothing matched.
+  remove(idOrName: string): { ok: boolean; message?: string };
+  // Run a workflow now (fire-and-forget on the daemon). ok:false when not found or the
+  // runner isn't wired.
+  run(idOrName: string): { ok: boolean; message?: string };
+}
+
+function summarize(wf: Workflow): WorkflowSummary {
+  return {
+    id: wf.workflow.id,
+    name: wf.workflow.name,
+    description: wf.workflow.description,
+    entryPoint: wf.workflow.entry_point,
+    stepCount: wf.steps.length + wf.parallel.length + wf.for_each.length,
+    gateCount: wf.steps.filter((s) => s.type === "human_gate").length,
+    scriptCount: wf.steps.filter((s) => s.type === "script").length,
+  };
+}
+
+// Pull an id out of an untrusted draft's header without trusting its shape.
+function draftId(draft: unknown): string | undefined {
+  const header = (draft as { workflow?: { id?: unknown } } | null)?.workflow;
+  return typeof header?.id === "string" ? header.id : undefined;
+}
+
+export function makeWorkflowsControl(opts: {
+  // Fire a workflow now — injected by the daemon (it owns the runner + its seams).
+  // Absent → run is reported unavailable rather than silently dropped (mirrors routines).
+  runNow?: (wf: Workflow) => void;
+}): WorkflowsControl {
+  return {
+    list(): WorkflowSummary[] {
+      return loadWorkflows().map(summarize);
+    },
+
+    get(idOrName: string): Workflow | undefined {
+      return loadWorkflow((idOrName ?? "").trim());
+    },
+
+    save(draft: unknown): { ok: boolean; message?: string; id?: string } {
+      // An edit keeps the draft's id; a create mints a fresh one. We inject the id into
+      // the header BEFORE parsing so the required `workflow.id` is always present and the
+      // client can't smuggle a malformed one (the schema + workflowFilePath re-check shape).
+      const existingId = draftId(draft);
+      const id = existingId ?? newWorkflowId();
+      const header = (draft as { workflow?: Record<string, unknown> } | null)?.workflow ?? {};
+      const candidate = { ...(draft as object), workflow: { ...header, id } };
+
+      const parsed = Workflow.safeParse(candidate);
+      if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        return { ok: false, message: `Invalid workflow: ${first ? `${first.path.join(".")} — ${first.message}` : "schema error"}.` };
+      }
+      const wf = parsed.data;
+
+      const graphErrors = validateWorkflow(wf);
+      if (graphErrors.length > 0) return { ok: false, message: `Invalid graph: ${graphErrors[0]}.` };
+
+      // A rename must not collide with a *different* workflow's name (mirrors routines).
+      const clash = loadWorkflows().find(
+        (w) => w.workflow.name.toLowerCase() === wf.workflow.name.toLowerCase() && w.workflow.id !== id,
+      );
+      if (clash) return { ok: false, message: `A workflow named "${wf.workflow.name}" already exists.` };
+
+      saveWorkflow(wf);
+      return { ok: true, id, message: existingId ? `Updated "${wf.workflow.name}".` : `Created "${wf.workflow.name}".` };
+    },
+
+    remove(idOrName: string): { ok: boolean; message?: string } {
+      const removed = removeWorkflow((idOrName ?? "").trim());
+      return removed
+        ? { ok: true, message: `Removed "${removed.workflow.name}".` }
+        : { ok: false, message: "Not found." };
+    },
+
+    run(idOrName: string): { ok: boolean; message?: string } {
+      const wf = findWorkflow(loadWorkflows(), (idOrName ?? "").trim());
+      if (!wf) return { ok: false, message: "Not found." };
+      if (!opts.runNow) return { ok: false, message: "The runner can't run this right now." };
+      opts.runNow(wf);
+      return { ok: true, message: `Running "${wf.workflow.name}" now.` };
+    },
+  };
+}

package/src/routines/store.ts

@@ -209,10 +209,14 @@ export function drainPendingRelay(): PendingRelay[] {
 // disk until a later flush succeeds. Unlike PendingRelay this carries `status`, so
 // the sealed envelope the app opens can render ok/error without re-parsing markdown.
 export interface PendingCloud {
-  routine: string;
+  routine: string; // the routine name OR ad-hoc task title (see `kind`)
   at: string; // ISO timestamp
   status: "ok" | "error";
   content: string;
+  // What produced this — a scheduled routine (default, for back-compat with items
+  // written before ad-hoc tasks existed) or an app-submitted one-shot task. Preserved
+  // so the flush re-seals with the right `kind` and the app labels it correctly.
+  kind?: "routine" | "task";
 }
 
 function pendingCloudPath(): string {

package/src/workflows/expr.ts

@@ -0,0 +1,4 @@
+// The confined workflow expression/template engine now lives in the standalone
+// `privateer-workflow` package (its canonical home). This module re-exports it so the
+// daemon's existing `../workflows/expr.ts` import paths keep working unchanged.
+export * from "privateer-workflow/expr";

package/src/workflows/runner.ts

@@ -0,0 +1,8 @@
+// The workflow runner now lives in the standalone `privateer-workflow` package (its
+// canonical home). This module re-exports it so the daemon's existing
+// `../workflows/runner.ts` import paths keep working unchanged.
+//
+// The daemon wires the runner's injected RunnerDeps to its own capabilities (headless
+// runSession, relay approvals, gated child processes, the cloud outbox) in daemon/index.ts
+// — that seam is unchanged; only the engine's source moved out to the shared package.
+export * from "privateer-workflow/runner";

package/src/workflows/schema.ts

@@ -0,0 +1,5 @@
+// The declarative workflow schema now lives in the standalone `privateer-workflow` package
+// (its canonical home). This module re-exports it so the daemon's existing
+// `../workflows/schema.ts` import paths (schema.ts is also the store's dependency) keep
+// working unchanged.
+export * from "privateer-workflow/schema";

package/src/workflows/store.ts

@@ -0,0 +1,108 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "../config/paths.ts";
+import { Workflow, validateWorkflow } from "./schema.ts";
+
+/**
+ * Workflow persistence — the sibling of routines/store.ts, but ONE FILE PER WORKFLOW.
+ *
+ * Routines are many small records in a single routines.json; a workflow is a larger,
+ * authored graph, so each lives in its own file under ~/.privateer/workflows/ (§8.3).
+ * The canonical on-disk format the app writes is `w-<id>.json`. Hand-authored `*.yaml`
+ * is a deliberate follow-up (needs a YAML parser + an async loader) — this skeleton
+ * stays dependency-free by reading/writing JSON only.
+ *
+ * A workflow file is an EXECUTABLE control artifact (it can run `script` steps), so —
+ * exactly like routines.json — every file is written owner-only (0600) inside the
+ * owner-only (0700) global dir. The signed-frame gate (workflowsControl + authorizeControl)
+ * is what stops the untrusted relay from writing one; these fs perms stop other local
+ * users from reading/altering it (the §6.5 machine-local trust root).
+ */
+
+export function workflowsDir(): string {
+  return join(globalDir(), "workflows");
+}
+
+// The canonical path for a workflow id. Ids are `w-<ts>` (see newWorkflowId) — already
+// filesystem-safe — but we re-assert the shape so a hostile id can never escape the dir.
+export function workflowFilePath(id: string): string {
+  if (!/^w-[a-zA-Z0-9]+$/.test(id)) throw new Error(`unsafe workflow id "${id}"`);
+  return join(workflowsDir(), `${id}.json`);
+}
+
+function tryChmod(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    /* non-POSIX filesystem or insufficient perms — nothing we can do */
+  }
+}
+
+// Parse + fully validate one file's contents into a Workflow, or null if it's corrupt,
+// fails the strict schema, or has a broken route graph. Per-file so ONE bad file never
+// hides the rest (unlike routines' single-file all-or-nothing load).
+function parseWorkflow(raw: string): Workflow | null {
+  try {
+    const parsed = Workflow.parse(JSON.parse(raw));
+    if (validateWorkflow(parsed).length > 0) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// All valid workflows on disk, sorted by name. Corrupt/invalid files are skipped, not
+// thrown — a hand-mangled file shouldn't take down the daemon or the app's list.
+export function loadWorkflows(): Workflow[] {
+  const dir = workflowsDir();
+  if (!existsSync(dir)) return [];
+  const out: Workflow[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) continue; // .yaml authoring is a follow-up
+    try {
+      const wf = parseWorkflow(readFileSync(join(dir, entry), "utf8"));
+      if (wf) out.push(wf);
+    } catch {
+      /* unreadable file — skip */
+    }
+  }
+  return out.sort((a, b) => a.workflow.name.localeCompare(b.workflow.name));
+}
+
+// Look up by id first, then by (case-insensitive) name — mirrors findRoutine.
+export function findWorkflow(workflows: Workflow[], idOrName: string): Workflow | undefined {
+  const needle = idOrName.trim().toLowerCase();
+  return (
+    workflows.find((w) => w.workflow.id === idOrName) ??
+    workflows.find((w) => w.workflow.name.toLowerCase() === needle)
+  );
+}
+
+// Load a single workflow by id or name (the app's editor fetches the full graph).
+export function loadWorkflow(idOrName: string): Workflow | undefined {
+  return findWorkflow(loadWorkflows(), idOrName);
+}
+
+// Write a workflow to its own file (create or overwrite by id). Caller has already
+// schema-validated it (workflowsControl.save) — we re-assert nothing here beyond the
+// id-shape guard in workflowFilePath.
+export function saveWorkflow(wf: Workflow): void {
+  const dir = workflowsDir();
+  mkdirSync(dir, { recursive: true });
+  tryChmod(dir, 0o700);
+  const path = workflowFilePath(wf.workflow.id);
+  writeFileSync(path, JSON.stringify(wf, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  tryChmod(path, 0o600);
+}
+
+// Remove a workflow by id or name. Returns the removed workflow, or null if absent.
+export function removeWorkflow(idOrName: string): Workflow | null {
+  const target = findWorkflow(loadWorkflows(), idOrName);
+  if (!target) return null;
+  try {
+    unlinkSync(workflowFilePath(target.workflow.id));
+  } catch {
+    return null; // already gone / unwritable
+  }
+  return target;
+}