@worca/app 1.0.0 → 1.1.1

package/src/core/workspace-scan.mjs

@@ -33,6 +33,7 @@ import {
 } from './worktree.mjs';
 import { runWorkspaceScan } from './phases.mjs';
 import { fanoutCap, mapWithCap } from './fanout.mjs';
+import { modelHasBaseUrlRouting } from './config.mjs';
 
 // The scanning agent's name in the prompt-role/registry sense (drives the .md body
 // it loads; the MOCK_ROLE marker differs — workspace-scan — and is set inside
@@ -298,6 +299,9 @@ class WorkspaceScan extends EventEmitter {
       // ctxFanOut(ctx) -> ctx.fanOut (no node) -> grants Task/Agent so the agent
       // can dispatch investigators (scan-fanout).
       fanOut: true,
+      // No node on this ctx: ctxEndpointRouted reads the ctx-level flag, so the
+      // scanner's fan-out block degrades the same way a routed node's does.
+      endpointRouted: modelHasBaseUrlRouting(this.claude.model),
       claudeOpts: {
         permissionMode: this.claude.permissionMode || 'acceptEdits',
         model: this.claude.model,

package/src/core/worktree.mjs

@@ -49,12 +49,17 @@ const BRANCH_STOPWORDS = new Set([
 // 30 s on large repos — give them a longer leash before the SIGKILL deadline.
 const SLOW_GIT_TIMEOUT_MS = 120_000;
 
-/** Run git and resolve to { ok, stdout, stderr, code }. Never throws. */
-function git(cwd, args, { signal, timeout = 30_000 } = {}) {
+/** Run git and resolve to { ok, stdout, stderr, code }. Never throws.
+ *  `env` is MERGED OVER process.env (never a replacement): the git binary and the
+ *  credential helper need PATH/HOME. Only the Ask Worca callers pass it. */
+function git(cwd, args, { signal, timeout = 30_000, env, maxBytes = 0 } = {}) {
   return new Promise((res) => {
     let child;
     try {
-      child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], signal });
+      child = spawn('git', args, {
+        cwd, stdio: ['ignore', 'pipe', 'pipe'], signal,
+        ...(env ? { env: { ...process.env, ...env } } : {}),
+      });
     } catch (err) {
       res({ ok: false, stdout: '', stderr: err.message, code: -1 });
       return;
@@ -73,7 +78,24 @@ function git(cwd, args, { signal, timeout = 30_000 } = {}) {
           done({ ok: false, stdout, stderr: stderr ? `git timed out: ${stderr}` : 'git timed out', code: -1 });
         }, timeout)
       : null;
-    child.stdout?.on('data', (b) => (stdout += b.toString()));
+    // `maxBytes` caps the CAPTURE (review of PR #376): the Ask `git` tool re-runs a
+    // command per `offset` page, so `log -p --all` on a big repo accumulated the
+    // whole history in memory every page. Past the cap the child is killed and
+    // the result is `ok` with `truncated: true` — the caller says so and pages
+    // within what it got.
+    let captured = 0;
+    let truncated = false;
+    child.stdout?.on('data', (b) => {
+      if (truncated) return;
+      captured += b.length;
+      stdout += b.toString();
+      if (maxBytes > 0 && captured > maxBytes) {
+        truncated = true;
+        stdout = Buffer.from(stdout, 'utf8').subarray(0, maxBytes).toString('utf8');
+        try { child.kill('SIGKILL'); } catch { /* gone */ }
+        done({ ok: true, stdout, stderr, code: 0, truncated: true });
+      }
+    });
     child.stderr?.on('data', (b) => (stderr += b.toString()));
     child.on('error', (err) => done({ ok: false, stdout, stderr: stderr || err.message, code: -1 }));
     child.on('close', (code) => done({ ok: code === 0, stdout, stderr, code: code ?? -1 }));
@@ -185,7 +207,9 @@ export async function worktreePathForBranch(projectDir, branch) {
   if (!r.ok) return null;
   let curPath = null;
   for (const line of r.stdout.split(/\r?\n/)) {
-    if (line.startsWith('worktree ')) curPath = line.slice('worktree '.length).trim();
+    // git prints '/'-separated paths even on Windows; resolve() gives callers the
+    // native form they compare against (createWorktree's own worktreeDir).
+    if (line.startsWith('worktree ')) curPath = resolve(line.slice('worktree '.length).trim());
     else if (line.startsWith('branch ')) {
       const ref = line.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
       if (ref === branch) return curPath;
@@ -302,8 +326,16 @@ export async function removeWorktree({ projectDir, worktreeDir, branch, force =
       : ['worktree', 'remove', worktreeDir];
     const r = await git(projectDir, args, { timeout: SLOW_GIT_TIMEOUT_MS });
     steps.push({ step: 'worktree-remove', ok: r.ok, stderr: r.stderr.trim() });
-    if (force) {
-      const fsRes = await rm(worktreeDir, { recursive: true, force: true })
+    // fs backstop whenever the checkout survives the git remove — not only on
+    // force. Git for Windows routinely leaves the directory behind (a read-only
+    // packed object, or a file a scanner/just-exited git still holds → EBUSY),
+    // which left detached run roots and worktrees on disk. Retry to ride out the
+    // transient lock; a no-op on POSIX where git already emptied the dir.
+    // ...but only when git REPORTED success and still left the dir behind (the
+    // Windows leftover). A non-force refusal on a dirty worktree (r.ok === false)
+    // must keep the checkout — deleting it would discard uncommitted agent work.
+    if (force || (r.ok && existsSync(worktreeDir))) {
+      const fsRes = await rm(worktreeDir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 })
         .then(() => null)
         .catch((e) => e.message);
       if (fsRes) steps.push({ step: 'rm-dir', ok: false, stderr: fsRes });
@@ -318,6 +350,65 @@ export async function removeWorktree({ projectDir, worktreeDir, branch, force =
   return { ok: steps.every((s) => s.ok), steps };
 }
 
+/**
+ * Create a DETACHED worktree at `worktreeDir` checking out `ref` — the Ask
+ * Worca inspection checkout (ask-worca-worktrees-design.md §3). Detached by
+ * construction: no branch is created, locked or deleted, so the pipeline
+ * branch-in-use check (M2) never sees these. The caller (ask/worktrees.mjs)
+ * owns path construction and containment; this validates only the ref (M1
+ * doctrine: reject option-injection before git parses argv) and throws on a
+ * fatal git failure with the same AbortError stamp createWorktree uses.
+ */
+export async function createDetachedWorktree({ projectDir, worktreeDir, ref, signal } = {}) {
+  if (!projectDir) throw new Error('projectDir required');
+  if (!worktreeDir) throw new Error('worktreeDir required');
+  if (!(await isValidSourceRef(projectDir, ref))) {
+    throw new Error(`ref is not a valid commit-ish: ${JSON.stringify(ref ?? null)}`);
+  }
+  await git(projectDir, ['worktree', 'prune']);
+  const r = await git(projectDir, ['worktree', 'add', '--detach', '--', worktreeDir, ref],
+    { signal, timeout: SLOW_GIT_TIMEOUT_MS });
+  if (!r.ok) {
+    const err = new Error(`git worktree add --detach failed: ${r.stderr.trim() || `exit ${r.code}`}`);
+    if (signal?.aborted) err.name = 'AbortError';
+    throw err;
+  }
+  const head = await git(worktreeDir, ['rev-parse', 'HEAD']);
+  return { worktreeDir, commit: head.ok ? head.stdout.trim() : null };
+}
+
+/** HEAD commit sha of any checkout (worktree or repo), or null. */
+export async function worktreeHead(dir) {
+  const r = await git(dir, ['rev-parse', 'HEAD']);
+  return r.ok ? r.stdout.trim() : null;
+}
+
+/**
+ * Env for every Ask Worca git spawn (spec §8). Pager OFF and — load-bearing —
+ * NEVER prompt: an https/ssh fetch with no cached credential would otherwise
+ * block on a terminal/askpass prompt until the SLOW_GIT_TIMEOUT_MS SIGKILL,
+ * holding the MCP call open for two minutes. GIT_ASKPASS/SSH_ASKPASS='' stop the
+ * GUI askpass fallback too. NOTE we deliberately do NOT set GIT_CONFIG_GLOBAL:
+ * the keychain credential helper for https fetch lives in the user's global
+ * config (E3), so nuking it would break authenticated fetch; the external-diff
+ * exec vector is closed per-invocation in the tool handler with
+ * `-c diff.external=` + `--no-ext-diff` instead.
+ */
+export const ASK_GIT_ENV = Object.freeze({
+  GIT_PAGER: 'cat', PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', SSH_ASKPASS: '',
+});
+
+/**
+ * Raw capture runner for the Ask Worca `git` MCP tool. The ONLY gate between a
+ * model-authored argv and this spawn is ask/git-allowlist.mjs — callers pass
+ * exclusively its validated output. Spawn semantics identical to every other
+ * helper here ({ok, stdout, stderr, code}, never throws), plus the ASK_GIT_ENV
+ * hardening and the caller's abort signal.
+ */
+export function runGitCapture(cwd, args, { signal, timeoutMs = SLOW_GIT_TIMEOUT_MS, maxBytes = 0 } = {}) {
+  return git(cwd, args, { signal, timeout: timeoutMs, env: ASK_GIT_ENV, maxBytes });
+}
+
 /**
  * Stage every remaining change and render a binary-capable patch against HEAD
  * DIRECTLY INTO outFile (no in-memory patch string — agent-created artifacts can

package/src/shared/graph/agent-meta.mjs

@@ -0,0 +1,278 @@
+// src/shared/graph/agent-meta.mjs
+// Agent metadata v2: ONE normalizer + validator for the registry loader (skip +
+// warn), the agent store (hard 400), the Agents-view port editor (live hints)
+// and agent-gen's read-back check. Pure — shared code cannot import
+// claude-runner.mjs, so the mock-role vocabulary is INJECTED.
+import { PORT_TYPES, MAX_PORTS_PER_SIDE, PORT_ID_RE } from './constants.mjs';
+
+const AGENT_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+// PORT_ID_RE is P1's, NOT a local copy: spec §3 puts it in constants.mjs
+// precisely so the store's 400, P1's seed guard and the composer's editor hint
+// can never disagree. It is the STRICT lowerCamel form `/^[a-z][A-Za-z0-9]{0,31}$/`
+// — no `_`, no `-` (see the Q&A; `in_1` and `in-1` are INVALID port ids).
+/** The engine synthesizes a type-agnostic `await` gate on every agent node, so
+ *  the id is RESERVED on BOTH sides and no sidecar may declare it. */
+const RESERVED_PORT_ID = 'await';
+const DOMAIN_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const COLORS = new Set(['green', 'peach', 'red', 'blue', 'violet', 'amber']);
+const RUNNER_TYPES = new Set(['producer', 'verifier', 'clarifier']);
+const INPUT_AS = new Set(['file', 'answers', 'fix-review', 'worktree']);
+/** The port type each non-default `as` renderer requires. `file` is the default
+ *  and is materialized on NON-VOID inputs only, which makes `worktree` the only
+ *  `as` a void input takes. */
+const AS_REQUIRES_TYPE = { answers: 'json', 'fix-review': 'md', worktree: 'void' };
+const OUTPUT_WHEN = new Set(['always', 'blocking', 'clean']);
+const OUTPUT_STORES = new Set(['run', 'project']);
+const WORKSPACE_STRATEGIES = new Set(['explore', 'task', 'review']);
+const FILENAME_TOKENS = new Set(['cycle', 'vsuffix', 'base']);
+/** Sort key a sidecar that omits `order` gets. Exported so the registry loader
+ *  (agent-registry.mjs normalizeMeta) backfills the SAME value this normalizer
+ *  does — a sidecar validateMetaV2 certifies must never vanish from the registry. */
+export const DEFAULT_ORDER = 999;
+const TYPES = [...PORT_TYPES].filter((t) => t !== 'any');   // `any` is engine-only, never declarable
+
+/** `{key: meta}` from a registry LIST (the /api/agents payload shape). */
+export function indexByKey(list) {
+  const out = {};
+  for (const m of Array.isArray(list) ? list : []) {
+    if (m && typeof m === 'object' && typeof m.key === 'string' && m.key) out[m.key] = m;
+  }
+  return out;
+}
+
+/** The palette one-liner and the generic system-prompt fallback: the NON-VOID
+ *  ids per side; an all-void side falls back to its declared ids so the sentence
+ *  never degenerates to "produces .". */
+export function derivePortSummary(meta) {
+  const ids = (ports) => {
+    const list = Array.isArray(ports) ? ports.filter(Boolean) : [];
+    const nonVoid = list.filter((p) => p.type !== 'void');
+    return (nonVoid.length ? nonVoid : list).map((p) => p.id);
+  };
+  const reads = ids(meta?.inputs);
+  const writes = ids(meta?.outputs);
+  if (!writes.length) return reads.length ? `Reads ${reads.join(', ')}.` : '';
+  if (!reads.length) return `Produces ${writes.join(', ')}.`;
+  return `Reads ${reads.join(', ')}; produces ${writes.join(', ')}.`;
+}
+
+/** Pure validation for the store's 400 path. Silent by design — the load path warns. */
+export function validateMetaV2(raw, opts = {}) {
+  return { errors: normalizeAgentMeta(raw, { ...opts, warn: () => {} }).errors };
+}
+
+/**
+ * @param {object} raw parsed sidecar
+ * @param {{mockWriterRoles?:Set<string>, warn?:(msg:string)=>void}} [opts]
+ * @returns {{meta:object|null, errors:string[]}} meta is meaningful only when errors is empty
+ */
+export function normalizeAgentMeta(raw, opts = {}) {
+  const errors = [];
+  const err = (msg) => errors.push(msg);
+  const warn = typeof opts.warn === 'function' ? opts.warn : () => {};
+  if (!raw || typeof raw !== 'object') return { errors: ['meta must be an object'], meta: null };
+
+  const key = typeof raw.key === 'string' ? raw.key.trim() : '';
+  if (!key) err('key is required');
+  else if (!AGENT_KEY_RE.test(key)) err(`key "${key}" is not a valid agent key`);
+  if (raw.metaVersion !== 2) err('sidecar requires metaVersion 2');
+  if (!RUNNER_TYPES.has(raw.runnerType)) err(`runnerType must be one of ${[...RUNNER_TYPES].join(', ')}`);
+  const runnerType = RUNNER_TYPES.has(raw.runnerType) ? raw.runnerType : 'producer';
+
+  const order = raw.order === undefined ? DEFAULT_ORDER : Number(raw.order);
+  if (!Number.isFinite(order)) err('order must be a number');
+
+  // agentFile is a PATH: the registry joins it onto the layer's agents dir and
+  // reads it as the agent's system prompt AND for its `tools:` frontmatter, so
+  // it takes the SAME basename rule as verdict.filename / outputs[].filename.
+  // A non-<key>.md basename stays legal — every built-in uses worca-cc-<role>.md.
+  const agentFile = typeof raw.agentFile === 'string' && raw.agentFile.trim() ? raw.agentFile.trim() : null;
+  if (agentFile && (/[\\/]/.test(agentFile) || agentFile.includes('..'))) {
+    err(`agentFile "${agentFile}" must be a plain basename`);
+  }
+
+  const verdict = readVerdict(raw.verdict, err);
+  if (runnerType === 'verifier' && !verdict) err('runnerType "verifier" requires verdict: { filename }');
+
+  const inputs = readInputs(raw.inputs, err, warn);
+  const outputs = readOutputs(raw.outputs, !!verdict, err);
+  if (runnerType === 'clarifier' && !outputs.some((p) => p.type === 'json')) {
+    err('runnerType "clarifier" requires at least one json output port');
+  }
+  // Two outputs may share one filename template only with an identical type (the
+  // refiner's clean/blocking plan arms); allocation then yields ONE path.
+  const typeByTemplate = new Map();
+  for (const p of outputs) {
+    if (!p.filename) continue;
+    const prev = typeByTemplate.get(p.filename);
+    if (prev === undefined) typeByTemplate.set(p.filename, p.type);
+    else if (prev !== p.type) err(`outputs: filename template "${p.filename}" is shared by ports of different types`);
+  }
+
+  // Scope coercion mirrors color: anything but the explicit 'workspace-only'
+  // marker is a normal project agent, so a typo fails safe to a VISIBLE agent.
+  const scope = raw.scope === 'workspace-only' ? 'workspace-only' : 'project';
+  if (raw.sideEffect !== undefined && raw.sideEffect !== 'code') err('sideEffect must be "code" when present');
+  if (raw.workspaceStrategy !== undefined && !WORKSPACE_STRATEGIES.has(raw.workspaceStrategy)) {
+    err(`workspaceStrategy must be one of ${[...WORKSPACE_STRATEGIES].join(', ')}`);
+  }
+  let workspaceVariantOf = null;
+  if (raw.workspaceVariantOf !== undefined) {
+    const target = typeof raw.workspaceVariantOf === 'string' ? raw.workspaceVariantOf.trim() : '';
+    if (!AGENT_KEY_RE.test(target)) err('workspaceVariantOf must be an agent key');
+    else if (target === key) err('workspaceVariantOf must not reference the agent itself');
+    else if (scope !== 'workspace-only') err('workspaceVariantOf requires scope "workspace-only"');
+    else workspaceVariantOf = target;
+  }
+  // An unknown mockRole is a WARNING, never a 400: the field is dropped and the
+  // generic mock-role fallback chain applies.
+  let mockRole = null;
+  if (raw.mockRole !== undefined) {
+    const role = typeof raw.mockRole === 'string' ? raw.mockRole.trim() : '';
+    const vocab = opts.mockWriterRoles instanceof Set ? opts.mockWriterRoles : null;
+    if (!vocab || vocab.has(role)) mockRole = role || null;
+    else warn(`[agent-registry] ${key || '<unkeyed>'}.mockRole: unknown mock role "${role}"; ignored (the generic mock chain applies)`);
+  }
+
+  const asksQuestions = !!raw.asksQuestions;
+  const meta = {
+    metaVersion: 2,
+    key,
+    displayName: typeof raw.displayName === 'string' && raw.displayName.trim() ? raw.displayName.trim() : key,
+    description: typeof raw.description === 'string' ? raw.description : '',
+    color: COLORS.has(raw.color) ? raw.color : 'amber',
+    icon: typeof raw.icon === 'string' ? raw.icon : '',
+    agentFile,
+    runnerType,
+    scope,
+    domain: typeof raw.domain === 'string' && DOMAIN_RE.test(raw.domain) ? raw.domain : 'general',
+    fanOut: !!raw.fanOut,
+    asksQuestions,
+    questionsLocked: asksQuestions && !!raw.questionsLocked,
+    questionsDefault: asksQuestions && !!raw.questionsDefault,
+    order: Number.isFinite(order) ? order : DEFAULT_ORDER,
+    promptHints: typeof raw.promptHints === 'string' ? raw.promptHints : '',
+    requiresSkills: Array.isArray(raw.requiresSkills)
+      ? raw.requiresSkills.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+      : [],
+    inputs,
+    outputs,
+    portSummary: '',
+  };
+  meta.portSummary = derivePortSummary(meta);
+  // Capability defaults are applied at READ time, never written into the entry:
+  // an absent field means "the default", so a v2 entry stays diffable against
+  // the sidecar that produced it.
+  if (verdict) meta.verdict = verdict;
+  if (raw.sideEffect === 'code') meta.sideEffect = 'code';
+  if (mockRole) meta.mockRole = mockRole;
+  if (raw.wantsRequest) meta.wantsRequest = true;
+  if (raw.workspaceFanOut) meta.workspaceFanOut = true;
+  if (WORKSPACE_STRATEGIES.has(raw.workspaceStrategy)) meta.workspaceStrategy = raw.workspaceStrategy;
+  if (workspaceVariantOf) meta.workspaceVariantOf = workspaceVariantOf;
+  if (raw.placeable !== undefined && !raw.placeable) meta.placeable = false;
+  return { errors, meta };
+}
+
+function readVerdict(raw, err) {
+  if (raw === undefined) return null;
+  const filename = raw && typeof raw === 'object' && typeof raw.filename === 'string' ? raw.filename.trim() : '';
+  if (!filename) { err('verdict must be an object with a filename'); return null; }
+  if (/[\\/]/.test(filename) || filename.includes('..')) {
+    err(`verdict filename "${filename}" must be a plain basename`);
+    return null;
+  }
+  return { filename };
+}
+
+function readPortHead(raw, side, seen, err) {
+  if (!raw || typeof raw !== 'object') { err(`${side}: each port must be an object`); return null; }
+  const id = typeof raw.id === 'string' ? raw.id.trim() : '';
+  if (id === RESERVED_PORT_ID) {
+    err(`${side}: port id "${RESERVED_PORT_ID}" is reserved — the engine synthesizes the await gate port on every agent node`);
+    return null;
+  }
+  if (!PORT_ID_RE.test(id)) { err(`${side}: bad port id "${id}"`); return null; }
+  if (seen.has(id)) { err(`${side}: duplicate port id "${id}"`); return null; }
+  seen.add(id);
+  if (!TYPES.includes(raw.type)) { err(`${side}.${id}: type must be one of ${TYPES.join(', ')}`); return null; }
+  const port = { id, type: raw.type };
+  if (typeof raw.label === 'string' && raw.label.trim()) port.label = raw.label.trim();
+  if (typeof raw.description === 'string' && raw.description.trim()) port.description = raw.description.trim();
+  if (raw.type === 'void' && (raw.filename !== undefined || raw.store !== undefined)) {
+    err(`${side}.${id}: void ports carry no filename or store`);
+  }
+  return port;
+}
+
+function readInputs(raw, err, warn) {
+  if (!Array.isArray(raw)) { err('inputs must be an array'); return []; }
+  if (raw.length > MAX_PORTS_PER_SIDE) err(`inputs: at most ${MAX_PORTS_PER_SIDE} ports per side (got ${raw.length})`);
+  const seen = new Set();
+  const out = [];
+  for (const p of raw) {
+    const port = readPortHead(p, 'inputs', seen, err);
+    if (!port) continue;
+    // A loop receiver is excused from the first-execution barrier, so `loop` and
+    // `required` can never both hold. Coerced rather than rejected — but it is
+    // authoring intent quietly overruled, hence the warning.
+    const loop = !!p.loop;
+    let required = p.required === undefined ? true : !!p.required;
+    if (loop && required) {
+      warn(`[agent-registry] inputs.${port.id}: loop:true forces required:false (a loop receiver is never a barrier)`);
+      required = false;
+    }
+    port.required = required;
+    if (loop) port.loop = true;
+    if (p.expands) {
+      if (port.type !== 'json') err(`inputs.${port.id}: expands is only legal on json inputs`);
+      else port.expands = true;
+    }
+    if (p.as !== undefined) {
+      const need = Object.hasOwn(AS_REQUIRES_TYPE, p.as) ? AS_REQUIRES_TYPE[p.as] : null;
+      if (!INPUT_AS.has(p.as)) err(`inputs.${port.id}: as must be one of ${[...INPUT_AS].join(', ')}`);
+      else if (need ? port.type !== need : port.type === 'void') {
+        err(`inputs.${port.id}: as "${p.as}" requires a ${need || 'non-void'} port (got ${port.type})`);
+      } else port.as = p.as;
+    } else if (port.type !== 'void') port.as = 'file';
+    if (typeof p.directive === 'string' && p.directive.trim()) port.directive = p.directive;
+    out.push(port);
+  }
+  return out;
+}
+
+function readOutputs(raw, hasVerdict, err) {
+  if (!Array.isArray(raw)) { err('outputs must be an array'); return []; }
+  if (raw.length === 0) err('at least one output port is required');
+  if (raw.length > MAX_PORTS_PER_SIDE) err(`outputs: at most ${MAX_PORTS_PER_SIDE} ports per side (got ${raw.length})`);
+  const seen = new Set();
+  const out = [];
+  for (const p of raw) {
+    const port = readPortHead(p, 'outputs', seen, err);
+    if (!port) continue;
+    const when = p.when === undefined ? 'always' : p.when;
+    if (!OUTPUT_WHEN.has(when)) err(`outputs.${port.id}: when must be one of ${[...OUTPUT_WHEN].join(', ')}`);
+    else {
+      if (when !== 'always' && !hasVerdict) {
+        err(`outputs.${port.id}: when "${when}" requires the agent to declare verdict: { filename }`);
+      }
+      port.when = when;
+    }
+    if (port.type !== 'void') {
+      const filename = typeof p.filename === 'string' ? p.filename.trim() : '';
+      const tokens = [...filename.matchAll(/\{([^}]*)\}/g)].map((m) => m[1]).filter((t) => !FILENAME_TOKENS.has(t));
+      if (!filename) err(`outputs.${port.id}: ${port.type} outputs require a filename template`);
+      else if (/[\\/]/.test(filename) || filename.includes('..')) {
+        err(`outputs.${port.id}: filename "${filename}" must be a plain basename`);
+      } else if (tokens.length) {
+        err(`outputs.${port.id}: filename "${filename}" uses unknown token(s) ${tokens.map((t) => `{${t}}`).join(', ')}`);
+      } else port.filename = filename;
+      const store = p.store === undefined ? 'run' : p.store;
+      if (!OUTPUT_STORES.has(store)) err(`outputs.${port.id}: store must be one of ${[...OUTPUT_STORES].join(', ')}`);
+      else port.store = store;
+      port.artifactKind = typeof p.artifactKind === 'string' && p.artifactKind.trim() ? p.artifactKind.trim() : port.id;
+    }
+    out.push(port);
+  }
+  return out;
+}

package/src/shared/graph/constants.mjs

@@ -0,0 +1,105 @@
+// src/shared/graph/constants.mjs
+// The frozen vocabulary of the v2 template model: node kinds, port types, the
+// synthesized await gate, the flow cards' port tables, id shapes and limits.
+// Pure data + one pure function — imported unchanged by the engine, the
+// server's 422 path, the tests and the browser (served at /src/shared).
+
+/** Templates this model understands. v1 rows carry `version: 1`. */
+export const TEMPLATE_VERSION = 2;
+
+/** Every node kind a template may carry (palette order). */
+export const KINDS = Object.freeze(['agent', 'task', 'end', 'and', 'or', 'combine']);
+
+/** The flow cards: every kind that is not a spawned agent. They are pure engine
+ *  executions — instant, $0, no spawn. */
+export const FLOW_KINDS = Object.freeze(['task', 'end', 'and', 'or', 'combine']);
+
+/** The flow cards' DISPLAY names — one label per FLOW_KIND. The single copy:
+ *  the run manifest (`manifest.mjs` cell labels), the run monitor and the
+ *  New-pipeline loop caption all read this table, so a flow card can never be
+ *  called 'OR' on one surface and 'n_or' on another. */
+export const FLOW_LABEL = Object.freeze({ task: 'Task', end: 'End', and: 'AND', or: 'OR', combine: 'Combine' });
+
+/** Port payload types. 'any' is engine-internal: it lives only on AND inputs,
+ *  OR ports before resolution, End's `result` and the synthesized `await` gate —
+ *  never declarable in agent meta. */
+export const PORT_TYPES = Object.freeze(['md', 'json', 'void', 'any']);
+
+/** Max ports per side of one card (agent meta inputs/outputs, gate arity). */
+export const MAX_PORTS_PER_SIDE = 8;
+
+/** Per-wire loop budget when neither the overlay nor `wire.config` sets one. */
+export const DEFAULT_MAX_CYCLES = 3;
+
+/** The universal gate input every agent card gets: synthesized by portsFn and
+ *  appended LAST to the agent's declared inputs. Never stored in a template and
+ *  never declared in meta ('await' is a reserved port id on both sides). It
+ *  accepts a wire from ANY output type and its payload is discarded — pure
+ *  sequencing: no file, no renderer, no directive, no mode effect. */
+export const AWAIT_PORT = Object.freeze({ id: 'await', type: 'any', required: false, synthetic: true });
+
+/** Task card — the graph's single source: zero inputs, one always-firing md
+ *  output carrying the rendered task md. */
+export const TASK_PORTS = Object.freeze({
+  inputs: Object.freeze([]),
+  outputs: Object.freeze([Object.freeze({ id: 'task', type: 'md', when: 'always' })]),
+});
+
+/** End card — the graph's single sink: one single-wire input, zero outputs. The
+ *  token arriving on its wire completes the run. */
+export const END_PORTS = Object.freeze({
+  inputs: Object.freeze([Object.freeze({ id: 'result', type: 'any', required: true, loop: false, expands: false })]),
+  outputs: Object.freeze([]),
+});
+
+/**
+ * Ports of a gate card at a given arity. AND is the pure synchronizer (`any`
+ * ins, ONE static `void` out, fires when all ins are fresh, payloads discarded);
+ * OR is the payload-forwarding valve (fires on any fresh in, re-emits that
+ * payload — its in/out types RESOLVE FROM WIRING, so `any` here is the
+ * pre-resolution placeholder); Combine is the md AND-join.
+ * @param {'and'|'or'|'combine'} kind
+ * @param {number} arity clamped to [2, MAX_PORTS_PER_SIDE]
+ * @returns {{inputs: Array<object>, outputs: Array<object>}}
+ */
+export function gatePorts(kind, arity) {
+  const n = Math.min(MAX_PORTS_PER_SIDE, Math.max(2, Math.floor(Number(arity)) || 2));
+  const inType = kind === 'combine' ? 'md' : 'any';
+  const inputs = [];
+  for (let i = 1; i <= n; i += 1) {
+    inputs.push(Object.freeze({ id: `in${i}`, type: inType, required: true, loop: false, expands: false }));
+  }
+  const outType = kind === 'and' ? 'void' : kind === 'combine' ? 'md' : 'any';
+  return Object.freeze({
+    inputs: Object.freeze(inputs),
+    outputs: Object.freeze([Object.freeze({ id: 'out', type: outType, when: 'always' })]),
+  });
+}
+
+/** Minted node ids are `n_` + 8 base36; the seed graphs use readable `n_<word>`
+ *  ids. Both shapes match. */
+export const NODE_ID_RE = /^n_[a-z0-9]{1,32}$/;
+
+/** Minted wire ids are `w_` + 8 base36; the seed graphs use `w1`..`w17`. Both
+ *  shapes match — the underscore is optional. */
+export const WIRE_ID_RE = /^w_?[a-z0-9]{1,32}$/;
+
+/** Port ids are lowerCamel, at most 32 chars (`task`, `revise`, `in1`, `await`). */
+export const PORT_ID_RE = /^[a-z][A-Za-z0-9]{0,31}$/;
+
+/** The two ledger rows every run writes for its own bookends (P8 makes them
+ *  `exec` rows keyed exactly so). Shared by the run monitor and the CLI so
+ *  neither counts them as executions or progress. */
+export const BOOKEND_EXECUTION_IDS = Object.freeze(['x:preflight:1', 'x:done:1']);
+
+/** Structural ceilings the validator enforces (override per call with
+ *  `validateGraph(tpl, portsFn, { limits })`). */
+export const LIMITS = Object.freeze({
+  maxNodes: 80,
+  maxWires: 200,
+  maxPortsPerSide: MAX_PORTS_PER_SIDE,
+  minArity: 2,
+  maxArity: MAX_PORTS_PER_SIDE,
+  maxCycles: 20,
+  maxNameLen: 80,
+});