@getpipher/armory-fleet 0.11.1 → 0.12.0

package/src/tools/fleet.ts

@@ -0,0 +1,179 @@
+// SPEC-6-3 §9 — the model-callable fleet tool surface for workflows.
+// Thin delegation to WorkflowController via a getter (prevents duplicate registration).
+import { Type, type Static } from "typebox"
+
+import type { WorkflowController } from "../workflows/runtime/controller.ts"
+import type { WorkflowStartInput, WorkflowRunState, WorkflowStartReceipt } from "../workflows/runtime/types.ts"
+import type { WorkflowRunResult } from "../workflows/runner.ts"
+
+export interface FleetToolDeps {
+  getController: () => WorkflowController
+}
+
+export const fleetParams = Type.Object({
+  action: Type.Union([Type.Literal("workflow"), Type.Literal("workflow_control")], { description: "The fleet workflow action." }),
+  // workflow action
+  script: Type.Optional(Type.String({ description: "The JS workflow script (for action: 'workflow')." })),
+  name: Type.Optional(Type.String({ description: "Save-as name (for action: 'workflow')." })),
+  workflowName: Type.Optional(Type.String({ description: "Run a saved workflow by name." })),
+  overwrite: Type.Optional(Type.Boolean({ description: "Overwrite an existing saved workflow." })),
+  args: Type.Optional(Type.Unknown({ description: "Args passed to the script as `args`." })),
+  background: Type.Optional(Type.Boolean({ description: "Non-blocking (default true)." })),
+  resumeFromRunId: Type.Optional(Type.String({ description: "Edit-and-resume: replay the unchanged prefix, re-run the edited suffix." })),
+  maxAgents: Type.Optional(Type.Number({ description: "Hard cap on total agent() calls." })),
+  concurrency: Type.Optional(Type.Number({ description: "Parallel agent() concurrency." })),
+  agentRetries: Type.Optional(Type.Number({ description: "Default per-agent retries." })),
+  agentTimeoutMs: Type.Optional(Type.Number({ description: "Default per-agent timeoutMs." })),
+  tokenBudget: Type.Optional(Type.Number({ description: "Run-level token budget." })),
+  // workflow_control action
+  control: Type.Optional(Type.Union([Type.Literal("list"), Type.Literal("status"), Type.Literal("pause"), Type.Literal("resume"), Type.Literal("stop")], { description: "The control operation." })),
+  runId: Type.Optional(Type.String({ description: "The workflow runId (for status/pause/resume/stop)." })),
+})
+
+export type FleetInput = Static<typeof fleetParams>
+
+export function createFleetTool(deps: FleetToolDeps) {
+  return {
+    name: "fleet",
+    label: "Fleet",
+    description: "Run + control armory-fleet workflows (JS orchestration with agent/parallel/pipeline/phase + journaled resume).",
+    promptSnippet: "Run or control a fleet workflow",
+    promptGuidelines: [
+      "Use action 'workflow' to run a JS workflow script or a saved workflow by name.",
+      "Use action 'workflow_control' with control 'list'/'status'/'pause'/'resume'/'stop' to manage a running workflow by runId.",
+      "Pass resumeFromRunId to edit-and-resume: the unchanged agent() prefix replays from cache; edited + new calls re-run.",
+    ],
+    parameters: fleetParams,
+    async execute(_id: string, params: FleetInput, signal: AbortSignal | null, _onUpdate: unknown, _ctx: unknown) {
+      let controller: WorkflowController
+      try {
+        controller = deps.getController()
+      } catch {
+        return { isError: true, content: [{ type: "text" as const, text: "workflow runtime not initialized for this session" }] }
+      }
+
+      try {
+        if (params.action === "workflow") {
+          return await handleWorkflowAction(controller, params, signal)
+        }
+        return await handleControlAction(controller, params)
+      } catch (e) {
+        return { isError: true, content: [{ type: "text" as const, text: (e as Error).message }] }
+      }
+    },
+  }
+}
+
+async function handleWorkflowAction(controller: WorkflowController, params: FleetInput, signal: AbortSignal | null) {
+  const hasScript = params.script !== undefined
+  const hasName = params.workflowName !== undefined
+
+  if (hasScript && hasName) {
+    return { isError: true, content: [{ type: "text" as const, text: "provide exactly one of script or workflowName" }] }
+  }
+  if (!hasScript && !hasName) {
+    return { isError: true, content: [{ type: "text" as const, text: "action 'workflow' requires `script` or `workflowName`" }] }
+  }
+
+  // resumeFromRunId → editAndResume
+  if (params.resumeFromRunId) {
+    const result = await controller.editAndResume(params.resumeFromRunId, params.script ?? "")
+    return serializeRunResult(result)
+  }
+
+  // Build the delegated WorkflowStartInput with conditional spreads (exact deepEqual match).
+  const input: WorkflowStartInput = {
+    mode: "auto",
+    ...(params.script !== undefined ? { script: params.script } : {}),
+    ...(params.workflowName !== undefined ? { workflowName: params.workflowName } : {}),
+    ...(params.name !== undefined ? { name: params.name } : {}),
+    ...(params.overwrite !== undefined ? { overwrite: params.overwrite } : {}),
+    ...(params.args !== undefined ? { args: params.args } : {}),
+    ...(params.background !== undefined ? { background: params.background } : {}),
+    ...(params.concurrency !== undefined ? { concurrency: params.concurrency } : {}),
+    ...(params.agentRetries !== undefined ? { agentRetries: params.agentRetries } : {}),
+    ...(params.agentTimeoutMs !== undefined ? { agentTimeoutMs: params.agentTimeoutMs } : {}),
+    ...(params.tokenBudget !== undefined ? { tokenBudget: params.tokenBudget } : {}),
+    ...(params.maxAgents !== undefined ? { maxAgents: params.maxAgents } : {}),
+  }
+
+  // Foreground: forward the tool signal. Background: detach (no signal).
+  const isForeground = params.background === false
+  const ctx = isForeground && signal ? { signal } : undefined
+
+  const result = await controller.start(input, ctx)
+  return serializeRunResult(result)
+}
+
+async function handleControlAction(controller: WorkflowController, params: FleetInput) {
+  const control = params.control ?? "list"
+
+  if (control === "list") {
+    const runs = controller.runs()
+    return {
+      content: [{ type: "text" as const, text: `workflows: ${runs.length ? runs.map((r) => r.runId).join(", ") : "(none running)"}` }],
+      details: { runs: runs.map(summarizeRun) },
+    }
+  }
+
+  if (!params.runId) {
+    return { isError: true, content: [{ type: "text" as const, text: `control '${control}' requires \`runId\`` }] }
+  }
+
+  if (control === "status") {
+    const run = controller.getRun(params.runId)
+    if (!run) {
+      return { isError: true, content: [{ type: "text" as const, text: `workflow '${params.runId}' not found` }] }
+    }
+    return { content: [{ type: "text" as const, text: `workflow ${run.runId}: ${run.status}` }], details: { run: summarizeRun(run) } }
+  }
+
+  if (control === "pause") {
+    controller.pause(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: paused` }], details: { runId: params.runId, status: "paused" } }
+  }
+
+  if (control === "resume") {
+    const receipt = await controller.resume(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: resumed` }], details: { receipt } }
+  }
+
+  if (control === "stop") {
+    await controller.stop(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: stopped` }], details: { runId: params.runId, status: "aborted" } }
+  }
+
+  return { isError: true, content: [{ type: "text" as const, text: `unknown control '${control}'` }] }
+}
+
+function summarizeRun(run: WorkflowRunState): Record<string, unknown> {
+  return {
+    runId: run.runId,
+    name: run.name,
+    status: run.status,
+    startedAt: run.startedAt,
+    ...(run.endedAt !== undefined ? { endedAt: run.endedAt } : {}),
+    currentPhase: run.currentPhase,
+    phases: run.phases,
+    childRunIds: run.childRunIds,
+    tokenTotal: run.tokenTotal,
+    costTotal: run.costTotal,
+    ...(run.error ? { error: run.error } : {}),
+  }
+}
+
+function serializeRunResult(result: WorkflowStartReceipt | WorkflowRunResult) {
+  if ("status" in result && result.status === "background") {
+    return {
+      content: [{ type: "text" as const, text: `workflow ${result.runId}: background` }],
+      details: { runId: result.runId, status: "background" },
+    }
+  }
+  const r = result as WorkflowRunResult
+  const isError = r.status === "aborted" || r.status === "failed"
+  return {
+    content: [{ type: "text" as const, text: isError ? (r.error ?? r.status) : `workflow ${r.runId}: ${r.status}` }],
+    details: { runId: r.runId, status: r.status },
+    isError: isError || undefined,
+  }
+}

package/src/workflows/builtin/adversarial-review.js

@@ -0,0 +1,19 @@
+export const meta = {
+  name: 'adversarial-review',
+  description: 'Red-team + blue-team review with judge panel',
+  phases: [{ title: 'Attack' }, { title: 'Defend' }, { title: 'Judge' }],
+}
+
+phase('Attack')
+const vulns = await parallel([
+  () => agent('Find injection vulnerabilities in this code.', { tier: 'medium' }),
+  () => agent('Find logic errors and race conditions.', { tier: 'medium' }),
+  () => agent('Find authentication bypass vectors.', { tier: 'medium' }),
+])
+
+phase('Defend')
+const defenses = await parallel(vulns.map((v) => () => agent(`Propose a fix for: ${v}`, { tier: 'low' })))
+
+phase('Judge')
+const winner = await judgePanel([...vulns, ...defenses], { judges: 3, rubric: 'severity and fixability' })
+return { vulnerabilities: vulns, defenses, verdict: winner }

package/src/workflows/builtin/code-review.js

@@ -0,0 +1,13 @@
+export const meta = {
+  name: 'code-review',
+  description: '7 parallel review angles plus verification',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+
+phase('Review')
+const angles = ['security', 'correctness', 'performance', 'readability', 'edge-cases', 'tests', 'api-design']
+const findings = await parallel(angles.map((angle) => () => agent(`Review this diff for ${angle} issues. Report concrete findings only.`, { tier: 'medium' })))
+
+phase('Verify')
+const verified = await verify(findings.join('\n---\n'), { reviewers: 2, lens: 'false positives' })
+return { findings, verified }

package/src/workflows/builtin/codebase-audit.js

@@ -0,0 +1,16 @@
+export const meta = {
+  name: 'codebase-audit',
+  description: 'File-tree scan with completeness check',
+  phases: [{ title: 'Scan' }, { title: 'Audit' }],
+}
+
+phase('Scan')
+const files = await loopUntilDry({
+  round: (n) => n < 4 ? agent(`List files in dir ${n}. Return a JSON array of file path strings.`, { tier: 'low', schema: { type: 'array' }, retries: 1 }) : [],
+  consecutiveEmpty: 2,
+  maxRounds: 6,
+})
+
+phase('Audit')
+const checked = await verify(`Found ${files.length} files.`, { reviewers: 1, lens: 'missing test coverage' })
+return { files, checked }

package/src/workflows/builtin/deep-research.js

@@ -0,0 +1,12 @@
+export const meta = {
+  name: 'deep-research',
+  description: '3-round discovery loop with de-duplication',
+  phases: [{ title: 'Discover' }, { title: 'Synthesize' }],
+}
+
+phase('Discover')
+const topics = await loopUntilDry({ round: (n) => n < 3 ? agent(`Find unique sources for round ${n}. Return a JSON array of source strings.`, { tier: 'low', schema: { type: 'array' }, retries: 1 }) : [], consecutiveEmpty: 2, maxRounds: 5 })
+
+phase('Synthesize')
+const summary = await agent(`Synthesize these ${topics.length} sources into a coherent report.`, { tier: 'medium' })
+return { sources: topics, summary }

package/src/workflows/builtin/multi-perspective.js

@@ -0,0 +1,17 @@
+export const meta = {
+  name: 'multi-perspective',
+  description: '4 personas review the same artifact',
+  phases: [{ title: 'Review' }, { title: 'Merge' }],
+}
+
+phase('Review')
+const personas = ['product manager', 'security engineer', 'UX designer', 'dev-ops lead']
+const reviews = await parallel(personas.map((p) => () => agent(`Review this artifact as a ${p}. Focus on your domain only.`, { tier: 'medium' })))
+
+phase('Merge')
+const merged = await gate(
+  async (feedback, n) => n === 0 ? agent(`Initial synthesis of ${reviews.length} reviews.`, { tier: 'low' }) : agent(`Revise synthesis: ${feedback}`, { tier: 'low' }),
+  (v) => typeof v === 'string' && v.length > 100 ? { ok: true } : { ok: false, feedback: 'more detail needed' },
+  { attempts: 3 },
+)
+return { reviews, synthesis: merged }

package/src/workflows/helpers/checkpoint.ts

@@ -0,0 +1,15 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — script-level human gate. Standalone (NOT CheckpointFn reuse).
+ *  Interactive: resolves via ctx.onCheckpoint. Headless: returns opts.default (or aborts). */
+export async function checkpoint(
+  prompt: string,
+  opts: { kind?: "confirm" | "input" | "select"; choices?: string[]; default?: unknown; headless?: "default" | "abort"; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<unknown> {
+  // Interactive bridge present → use it (the Workflows view resolves the pending checkpoint).
+  if (ctx.onCheckpoint) return ctx.onCheckpoint(prompt, opts as Record<string, unknown>);
+  const headless = opts.headless ?? "default";
+  if (headless === "abort") throw new Error("checkpoint abort: headless mode with no UI");
+  return opts.default ?? true;
+}

package/src/workflows/helpers/completeness-check.ts

@@ -0,0 +1,18 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — judge whether results fully satisfy taskArgs via one agent. Returns null if agent can't judge. */
+export async function completenessCheck(
+  taskArgs: unknown,
+  results: unknown,
+  ctx: HelperCtx,
+  opts: { tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+): Promise<{ complete: boolean; missing?: string[] } | null> {
+  const prompt = `You are a completeness judge. Given the task args and the results, decide if the results fully satisfy the task.\nTask args: ${JSON.stringify(taskArgs)}\nResults: ${JSON.stringify(results)}\nRespond as JSON: {"complete": boolean, "missing": string[]}`;
+  const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+  if (!res || res.status !== "completed") return null;
+  try {
+    const parsed = JSON.parse(res.finalText) as { complete?: boolean; missing?: string[] };
+    if (typeof parsed.complete !== "boolean") return null;
+    return { complete: parsed.complete, ...(Array.isArray(parsed.missing) ? { missing: parsed.missing } : {}) };
+  } catch { return null; }
+}

package/src/workflows/helpers/gate.ts

@@ -0,0 +1,22 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — run thunk, validate; on fail re-run with feedback up to `attempts`. */
+export async function gate(
+  thunk: (feedback: string | undefined, attempt: number) => unknown | Promise<unknown>,
+  validator: (value: unknown) => { ok: boolean; feedback?: string } | Promise<{ ok: boolean; feedback?: string }>,
+  opts: { attempts?: number } = {},
+  ctx: HelperCtx,
+): Promise<{ ok: boolean; value: unknown; attempts: number }> {
+  const attempts = opts.attempts ?? 3;
+  let feedback: string | undefined;
+  let lastValue: unknown;
+  for (let n = 0; n < attempts; n++) {
+    const value = await thunk(feedback, n);
+    lastValue = value;
+    const verdict = await validator(value);
+    if (verdict.ok) return { ok: true, value, attempts: n + 1 };
+    feedback = verdict.feedback;
+  }
+  // exhausted: return the last value from within the attempts budget (no extra run).
+  return { ok: false, value: lastValue, attempts };
+}

package/src/workflows/helpers/index.ts

@@ -0,0 +1,8 @@
+export type { HelperCtx, HelperSpawnResult } from "./types.ts";
+export { retry } from "./retry.ts";
+export { gate } from "./gate.ts";
+export { completenessCheck } from "./completeness-check.ts";
+export { loopUntilDry } from "./loop-until-dry.ts";
+export { verify } from "./verify.ts";
+export { judgePanel } from "./judge-panel.ts";
+export { checkpoint } from "./checkpoint.ts";

package/src/workflows/helpers/judge-panel.ts

@@ -0,0 +1,33 @@
+import type { HelperCtx } from "./types.ts";
+
+interface Judgment { score: number; reason?: string }
+interface PanelResult { index: number; attempt: unknown; score: number; judgments: Judgment[] }
+
+/** SPEC-6-3 §3.3 — N judges score every attempt; highest average score wins. Closes 6-2.1. */
+export async function judgePanel(
+  attempts: unknown[],
+  opts: { judges?: number; rubric?: string; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<PanelResult | undefined> {
+  if (attempts.length === 0) return undefined;
+  const judges = opts.judges ?? 3;
+  const rubric = opts.rubric ?? "overall quality and correctness";
+  const perAttempt: Judgment[][] = attempts.map(() => []);
+  for (let j = 0; j < judges; j++) {
+    for (let a = 0; a < attempts.length; a++) {
+      const prompt = `You are judge ${j + 1} of ${judges}. Score this attempt on a 0-10 scale.\nRubric: ${rubric}\nAttempt ${a}: ${JSON.stringify(attempts[a])}\nRespond as JSON: {"score": number, "reason": string}`;
+      const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+      if (res && res.status === "completed") {
+        try { const p = JSON.parse(res.finalText) as { score?: number; reason?: string }; perAttempt[a]!.push({ score: typeof p.score === "number" ? p.score : 0, ...(p.reason ? { reason: p.reason } : {}) }); }
+        catch { perAttempt[a]!.push({ score: 0 }); }
+      } else { perAttempt[a]!.push({ score: 0 }); }
+    }
+  }
+  let best: PanelResult | undefined;
+  for (let a = 0; a < attempts.length; a++) {
+    const js = perAttempt[a]!;
+    const score = js.reduce((s, x) => s + x.score, 0) / (js.length || 1);
+    if (!best || score > best.score) best = { index: a, attempt: attempts[a], score, judgments: js };
+  }
+  return best;
+}

package/src/workflows/helpers/loop-until-dry.ts

@@ -0,0 +1,21 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — discovery loop: call round(n) → items; de-dupe by key; stop after consecutiveEmpty empty rounds or maxRounds. */
+export async function loopUntilDry(
+  opts: { round: (roundIndex: number) => unknown[] | Promise<unknown[]>; key?: (item: unknown) => string; consecutiveEmpty?: number; maxRounds?: number },
+  ctx: HelperCtx,
+): Promise<unknown[]> {
+  const consecutiveEmpty = opts.consecutiveEmpty ?? 2;
+  const maxRounds = opts.maxRounds ?? 50;
+  const key = opts.key ?? ((item: unknown) => JSON.stringify(item));
+  const seen = new Set<string>();
+  const acc: unknown[] = [];
+  let emptyStreak = 0;
+  for (let n = 0; n < maxRounds; n++) {
+    const items = await opts.round(n);
+    const fresh = (Array.isArray(items) ? items : []).filter((it) => { const k = key(it); if (seen.has(k)) return false; seen.add(k); return true; });
+    for (const f of fresh) acc.push(f);
+    if (fresh.length === 0) { emptyStreak++; if (emptyStreak >= consecutiveEmpty) break; } else emptyStreak = 0;
+  }
+  return acc;
+}

package/src/workflows/helpers/retry.ts

@@ -0,0 +1,17 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — retry a thunk up to `attempts`; `until` decides when to stop. */
+export async function retry(
+  thunk: (attempt: number) => unknown | Promise<unknown>,
+  opts: { attempts?: number; until?: (result: unknown) => boolean } = {},
+  ctx: HelperCtx,
+): Promise<unknown> {
+  const attempts = opts.attempts ?? 3;
+  const until = opts.until ?? (() => true);
+  let last: unknown;
+  for (let n = 0; n < attempts; n++) {
+    try { last = await thunk(n); } catch { continue; } // recoverable: try again
+    if (until(last)) return last;
+  }
+  return last;
+}

package/src/workflows/helpers/types.ts

@@ -0,0 +1,19 @@
+import type { WorkflowJournal } from "../journal.ts";
+
+export interface HelperSpawnResult {
+  finalText: string;
+  runId: string;
+  status: "completed" | "failed";
+  costTotal?: number;
+  tokenTotal?: number;
+}
+
+export interface HelperCtx {
+  spawn: (prompt: string, opts?: { agent?: string; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number }) => Promise<HelperSpawnResult | null>;
+  journal: WorkflowJournal;
+  runId: string;
+  budget?: { spent: () => number; remaining: () => number };
+  onCheckpoint?: (prompt: string, opts: Record<string, unknown>) => Promise<unknown>;
+  getModelContextWindow?: (model: string) => number | undefined;
+  nextCallIndex: () => number;
+}

package/src/workflows/helpers/verify.ts

@@ -0,0 +1,27 @@
+import type { HelperCtx } from "./types.ts";
+
+const REAL_RE = /\b(real|valid|correct|true|confirmed|legit)\b/i;
+
+function judgeVote(text: string): { real: boolean; reason?: string } {
+  return { real: REAL_RE.test(text), reason: text.slice(0, 200) };
+}
+
+/** SPEC-6-3 §3.3 — N reviewers vote; real = realCount/total >= threshold (default 0.5). */
+export async function verify(
+  item: unknown,
+  opts: { reviewers?: number; threshold?: number; lens?: string | string[]; tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }> {
+  const reviewers = opts.reviewers ?? 2;
+  const threshold = opts.threshold ?? 0.5;
+  const lens = opts.lens ? ` Focus lens: ${Array.isArray(opts.lens) ? opts.lens.join(", ") : opts.lens}.` : "";
+  const prompt = `You are an independent reviewer. Decide if the following item is REAL/valid.\nItem: ${JSON.stringify(item)}${lens}\nRespond with "real" or "fake" + a one-line reason.`;
+  const votes: Array<{ real: boolean; reason?: string }> = [];
+  for (let i = 0; i < reviewers; i++) {
+    const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    if (!res || res.status !== "completed") { votes.push({ real: false, reason: "reviewer failed" }); continue; }
+    votes.push(judgeVote(res.finalText));
+  }
+  const realCount = votes.filter((v) => v.real).length;
+  return { real: realCount / reviewers >= threshold, realCount, total: reviewers, votes };
+}

package/src/workflows/journal.ts

@@ -0,0 +1,76 @@
+// SPEC-6-3 — the per-workflow positional-call-index journal.
+// Append-only JSONL at <dir>/<runId>.jsonl. Crash-safe: a partial last line is discarded.
+// Separate from RunLog (per-agent conversations/) and RunJournal (per-lifecycle runs/).
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WorkflowStartedEvent { type: "wf:started"; runId: string; script: string; args?: unknown; phases?: { title: string }[]; mode: "auto" | "checkpointed"; ts: number; }
+export interface AgentCallEvent { type: "agent:call"; callIndex: number; label: string; phase: string; prompt: string; opts: Record<string, unknown>; childRunId?: string; ts: number; }
+export interface AgentResultEvent { type: "agent:result"; callIndex: number; childRunId: string; result: unknown; status: "completed" | "failed"; costTotal?: number; tokenTotal?: number; ts: number; }
+export interface HelperCallEvent { type: "helper:call"; callIndex: number; name: string; args: unknown; ts: number; }
+export interface HelperResultEvent { type: "helper:result"; callIndex: number; name: string; result: unknown; ts: number; }
+export interface CheckpointEvent { type: "checkpoint"; callIndex: number; prompt: string; response: unknown; ts: number; }
+export interface WorkflowCompletedEvent { type: "wf:completed"; runId: string; result: unknown; costTotal?: number; tokenTotal?: number; ts: number; }
+export interface WorkflowAbortedEvent { type: "wf:aborted"; runId: string; reason: string; ts: number; }
+
+export interface WorkflowProgressJournalEvent {
+  type: "wf:progress";
+  kind: "started" | "phase" | "child-started" | "child-completed" | "child-failed" | "helper-started" | "helper-completed" | "log" | "checkpoint" | "checkpoint-resolved" | "completed" | "failed" | "aborted";
+  runId: string;
+  status: string;
+  currentPhase: string;
+  phases: Array<{ title: string; agents: number; cached: number; reRun: number }>;
+  childRunIds: string[];
+  logs: string[];
+  tokenTotal: number;
+  costTotal: number;
+  checkpoint?: { prompt: string; opts: Record<string, unknown> };
+  ts: number;
+}
+
+export type WorkflowJournalEvent =
+  | WorkflowStartedEvent | AgentCallEvent | AgentResultEvent | HelperCallEvent
+  | HelperResultEvent | CheckpointEvent | WorkflowCompletedEvent | WorkflowAbortedEvent
+  | WorkflowProgressJournalEvent;
+
+const WORKFLOW_TERMINAL = new Set<WorkflowJournalEvent["type"]>(["wf:completed", "wf:aborted"]);
+
+export class WorkflowJournal {
+  constructor(private readonly dir: string) {}
+
+  private file(runId: string): string { return join(this.dir, `${runId}.jsonl`); }
+
+  append(runId: string, event: WorkflowJournalEvent): void {
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      appendFileSync(this.file(runId), JSON.stringify(event) + "\n", "utf8");
+    } catch {
+      // best-effort: never fail the workflow because the journal couldn't persist.
+    }
+  }
+
+  replay(runId: string): WorkflowJournalEvent[] {
+    const f = this.file(runId);
+    if (!existsSync(f)) return [];
+    const events: WorkflowJournalEvent[] = [];
+    for (const line of readFileSync(f, "utf8").split("\n")) {
+      if (!line) continue;
+      try { events.push(JSON.parse(line) as WorkflowJournalEvent); }
+      catch { /* partial last line (crash mid-append) — discard */ }
+    }
+    return events;
+  }
+
+  scanNonTerminal(): string[] {
+    if (!existsSync(this.dir)) return [];
+    const ids: string[] = [];
+    for (const f of readdirSync(this.dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const runId = f.slice(0, -".jsonl".length);
+      const events = this.replay(runId);
+      const last = events[events.length - 1];
+      if (last && !WORKFLOW_TERMINAL.has(last.type)) ids.push(runId);
+    }
+    return ids;
+  }
+}

package/src/workflows/keyword.ts

@@ -0,0 +1,22 @@
+// SPEC-6-3 §9 — bounded keyword authorization for workflow capability.
+// Returns a bounded system hint when the prompt mentions "workflow"/"workflows"
+// as a standalone word (not as part of an identifier or file path).
+
+const WORKFLOW_KEYWORD = /(?:^|[^A-Za-z0-9_])workflows?(?=$|[^A-Za-z0-9_])/i
+
+export function workflowKeywordHint(prompt: string): string | undefined {
+  const match = prompt.match(WORKFLOW_KEYWORD)
+  if (!match) return undefined
+
+  const fullMatch = match[0]!
+  // If the match includes a preceding non-word char, check if it's a path separator.
+  const firstChar = fullMatch[0]!
+  if (firstChar === "/" || firstChar === ".") return undefined
+
+  // Check the character after "workflow" in the original string.
+  const afterIdx = (match.index ?? 0) + fullMatch.length
+  const afterChar = prompt[afterIdx]
+  if (afterChar === "-" || afterChar === ".") return undefined
+
+  return "workflow capability authorized — use action:'workflow' with a script or workflowName"
+}