@0xtiby/toby 1.1.0 → 1.3.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.tsx
 import meow from "meow";
-import { render, Text as Text14 } from "ink";
+import { render } from "ink";
 
 // src/commands/plan.tsx
 import { useState as useState3, useEffect as useEffect2, useMemo as useMemo2 } from "react";
@@ -65,11 +65,18 @@ var SpecStatusEntrySchema = z.object({
   iterations: z.array(IterationSchema),
   stopReason: StopReasonSchema.optional()
 });
+var SessionStateSchema = z.enum(["active", "interrupted"]);
+var SessionSchema = z.object({
+  name: z.string(),
+  cli: z.string(),
+  specs: z.array(z.string()),
+  state: SessionStateSchema,
+  startedAt: z.string().datetime()
+});
 var StatusSchema = z.object({
   specs: z.record(z.string(), SpecStatusEntrySchema),
-  sessionName: z.string().optional(),
-  lastCli: z.string().optional()
-});
+  session: SessionSchema.optional()
+}).strip();
 
 // src/lib/paths.ts
 import path from "path";
@@ -112,6 +119,243 @@ function ensureLocalDir(cwd) {
   return dir;
 }
 
+// src/lib/help.ts
+var SPEC_FLAGS = [
+  { name: "--spec=<query>", description: "Target spec(s) by name, slug, number, or list" },
+  { name: "--specs=<names>", description: "Alias for --spec" },
+  { name: "--all", description: "Process all matching specs" },
+  { name: "--iterations=<n>", description: "Override iteration count" },
+  { name: "--verbose", description: "Show full CLI output" },
+  { name: "--transcript", description: "Save session transcript to file" },
+  { name: "--cli=<name>", description: "Override AI CLI (claude, codex, opencode)" },
+  { name: "--session=<name>", description: "Name the session for branch/PR naming" }
+];
+var commandHelp = {
+  plan: {
+    summary: "Plan specs with AI loop engine",
+    usage: ["$ toby plan [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby plan --spec=auth --cli=claude --session=auth-feature",
+        description: 'Plan the auth spec using Claude, naming the session "auth-feature"'
+      },
+      {
+        command: "toby plan --spec=auth,payments --iterations=3 --verbose",
+        description: "Plan auth and payments specs with 3 iterations, showing full output"
+      },
+      {
+        command: "toby plan --all --transcript",
+        description: "Plan all pending specs and save a transcript of the session"
+      }
+    ]
+  },
+  build: {
+    summary: "Build tasks one-per-spawn with AI",
+    usage: ["$ toby build [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby build --spec=auth --cli=claude --session=auth-feature",
+        description: 'Build the auth spec using Claude, resuming "auth-feature"'
+      },
+      {
+        command: "toby build --all --iterations=5 --transcript",
+        description: "Build all planned specs with up to 5 iterations, saving transcripts"
+      },
+      {
+        command: "toby build --spec=2 --verbose",
+        description: "Build spec #2 with full CLI output visible"
+      }
+    ]
+  },
+  resume: {
+    summary: "Resume an interrupted build session",
+    usage: ["$ toby resume [options]"],
+    flags: [
+      { name: "--iterations=<n>", description: "Override iteration count" },
+      { name: "--verbose", description: "Show full CLI output" },
+      { name: "--transcript", description: "Save session transcript to file" }
+    ],
+    examples: [
+      {
+        command: "toby resume",
+        description: "Resume the most recent interrupted session from where it left off"
+      },
+      {
+        command: "toby resume --iterations=10 --verbose",
+        description: "Resume with 10 iterations per spec and full CLI output"
+      },
+      {
+        command: "toby resume --transcript",
+        description: "Resume and save a transcript of the resumed session"
+      }
+    ]
+  },
+  init: {
+    summary: "Initialize toby in current project",
+    usage: ["$ toby init [options]"],
+    flags: [
+      {
+        name: "--plan-cli=<name>",
+        description: "Set plan CLI (claude, codex, opencode)"
+      },
+      { name: "--plan-model=<id>", description: "Set plan model" },
+      {
+        name: "--build-cli=<name>",
+        description: "Set build CLI (claude, codex, opencode)"
+      },
+      { name: "--build-model=<id>", description: "Set build model" },
+      { name: "--specs-dir=<path>", description: "Set specs directory" },
+      {
+        name: "--verbose",
+        description: "Enable verbose output in config"
+      }
+    ],
+    examples: [
+      {
+        command: "toby init",
+        description: "Launch the interactive setup wizard"
+      },
+      {
+        command: "toby init --plan-cli=claude --build-cli=claude --specs-dir=specs",
+        description: "Non-interactive init with required flags (for CI/agents)"
+      },
+      {
+        command: "toby init --plan-cli=codex --build-cli=codex --specs-dir=specs --verbose",
+        description: "Initialize with Codex for both phases, verbose enabled"
+      }
+    ]
+  },
+  status: {
+    summary: "Show project status",
+    usage: ["$ toby status [options]"],
+    flags: [
+      {
+        name: "--spec=<query>",
+        description: "Show status for a specific spec by name, slug, or number"
+      }
+    ],
+    examples: [
+      {
+        command: "toby status",
+        description: "Show status overview for all specs in the project"
+      },
+      {
+        command: "toby status --spec=auth",
+        description: "Show detailed status for the auth spec"
+      }
+    ]
+  },
+  config: {
+    summary: "Manage configuration",
+    usage: [
+      "$ toby config                           Interactive config editor",
+      "$ toby config get <key>                 Show a config value (dot-notation)",
+      "$ toby config set <key> <value>         Set a config value",
+      "$ toby config set <k>=<v> [<k>=<v>...]  Batch set values"
+    ],
+    flags: [],
+    examples: [
+      {
+        command: "toby config",
+        description: "Open the interactive config editor"
+      },
+      {
+        command: "toby config get plan.cli",
+        description: "Show the configured plan CLI"
+      },
+      {
+        command: "toby config set plan.cli=claude build.iterations=5",
+        description: "Batch set plan CLI to claude and build iterations to 5"
+      }
+    ]
+  },
+  clean: {
+    summary: "Delete session transcripts",
+    usage: ["$ toby clean [options]"],
+    flags: [
+      {
+        name: "--force",
+        description: "Skip confirmation prompt (required in non-TTY)"
+      }
+    ],
+    examples: [
+      {
+        command: "toby clean",
+        description: "Delete all transcripts with confirmation prompt"
+      },
+      {
+        command: "toby clean --force",
+        description: "Delete all transcripts without confirmation (for CI/agents)"
+      }
+    ]
+  }
+};
+function formatCommandHelp(command2, help) {
+  const lines = [];
+  lines.push(`toby ${command2} \u2014 ${help.summary}`);
+  lines.push("");
+  lines.push("Usage");
+  for (const usage of help.usage) {
+    lines.push(`  ${usage}`);
+  }
+  if (help.flags.length > 0) {
+    lines.push("");
+    lines.push("Options");
+    const maxName = Math.max(...help.flags.map((f) => f.name.length));
+    for (const flag of help.flags) {
+      lines.push(`  ${flag.name.padEnd(maxName)}   ${flag.description}`);
+    }
+  }
+  lines.push("");
+  lines.push("Examples");
+  const exampleBlocks = help.examples.map(
+    (ex) => `  $ ${ex.command}
+    ${ex.description}`
+  );
+  lines.push(exampleBlocks.join("\n\n"));
+  lines.push("");
+  return lines.join("\n");
+}
+function formatErrorWithHint(message, validValues, example) {
+  const lines = [];
+  if (validValues) {
+    lines.push(`\u2717 ${message}. Valid options: ${validValues.join(", ")}`);
+  } else {
+    lines.push(`\u2717 ${message}`);
+  }
+  if (example) {
+    lines.push("");
+    lines.push("Example:");
+    lines.push(`  $ ${example}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function formatGlobalHelp(version2) {
+  const maxCmd = Math.max(
+    ...Object.keys(commandHelp).map((c) => c.length)
+  );
+  const cmdLines = Object.entries(commandHelp).map(([name, h]) => `  ${name.padEnd(maxCmd)}   ${h.summary}`).join("\n");
+  return [
+    `toby v${version2} \u2014 AI-assisted development loop engine`,
+    "",
+    "Usage",
+    "  $ toby <command> [options]",
+    "",
+    "Commands",
+    cmdLines,
+    "",
+    "Options",
+    "  --help       Show help (use with a command for details)",
+    "  --version    Show version",
+    "",
+    "Run toby <command> --help for command-specific options and examples.",
+    ""
+  ].join("\n");
+}
+
 // src/lib/config.ts
 function readConfigFile(filePath) {
   try {
@@ -154,7 +398,13 @@ function writeConfig(config, filePath) {
 }
 function validateCliName(cli2) {
   if (cli2 && !CLI_NAMES.includes(cli2)) {
-    throw new Error(`Unknown CLI: ${cli2}. Must be one of: ${CLI_NAMES.join(", ")}`);
+    throw new Error(
+      formatErrorWithHint(
+        `Unknown CLI: ${cli2}`,
+        [...CLI_NAMES],
+        "toby plan --cli=claude --spec=auth"
+      )
+    );
   }
 }
 function resolveCommandConfig(config, command2, flags2 = {}) {
@@ -539,6 +789,28 @@ function addIteration(status, specName, iteration) {
     }
   };
 }
+function createSession(name, cli2, specs) {
+  return {
+    name,
+    cli: cli2,
+    specs,
+    state: "active",
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function updateSessionState(status, state) {
+  if (!status.session) return status;
+  return {
+    ...status,
+    session: { ...status.session, state }
+  };
+}
+function clearSession(status) {
+  return { specs: status.specs };
+}
+function hasResumableSession(status) {
+  return status.session?.state === "active" || status.session?.state === "interrupted";
+}
 function updateSpecStatus(status, specName, newStatus) {
   const entry = getSpecStatus(status, specName);
   return {
@@ -739,16 +1011,19 @@ function useCommandRunner(options) {
       if (filtered.length === 0) {
         setErrorMessage(emptyMessage ?? "No specs found.");
         setPhase("error");
-        exit();
         return;
       }
       setSpecs(filtered);
     } catch (err) {
       setErrorMessage(err.message);
       setPhase("error");
-      exit(new Error(err.message));
     }
   }, [phase]);
+  useEffect(() => {
+    if (phase === "error" && errorMessage) {
+      exit(new Error(errorMessage));
+    }
+  }, [phase, errorMessage]);
   useEffect(() => {
     if (phase !== "multi" || selectedSpecs.length > 0) return;
     if (!flags2.spec) return;
@@ -1180,14 +1455,10 @@ function Plan(flags2) {
 import { useState as useState4, useEffect as useEffect3, useMemo as useMemo3 } from "react";
 import { Text as Text4, Box as Box4 } from "ink";
 import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
-function detectResume(specEntry, currentCli, lastCli) {
+function resolveResumeSessionId(specEntry, currentCli, sessionCli) {
+  if (currentCli !== sessionCli) return void 0;
   const lastIteration = specEntry?.iterations.at(-1);
-  const isCrashResume = !!(specEntry?.status !== "done" && lastIteration?.state === "in_progress");
-  const isExhaustedResume = !!(specEntry?.status !== "done" && specEntry?.stopReason === "max_iterations");
-  const needsResume = isCrashResume || isExhaustedResume;
-  const isSameCli = currentCli === lastCli;
-  const sessionId = isSameCli && isCrashResume ? lastIteration?.sessionId ?? void 0 : void 0;
-  return { isCrashResume, isExhaustedResume, needsResume, sessionId };
+  return lastIteration?.sessionId ?? void 0;
 }
 async function runSpecBuild(options) {
   const { spec, iterations, cli: cli2, model, cwd, callbacks } = options;
@@ -1236,7 +1507,6 @@ async function runSpecBuild(options) {
         tokensUsed: null
       };
       status = addIteration(status, spec.name, iterationRecord);
-      status = { ...status, sessionName: options.session, lastCli: cli2 };
       writeStatus(status, cwd);
     },
     onIterationComplete: (iterResult) => {
@@ -1314,20 +1584,22 @@ async function executeBuild(flags2, callbacks = {}, cwd = process.cwd(), abortSi
   if (!found) {
     throw new Error(`Spec '${flags2.spec}' not found`);
   }
-  const status = readStatus(cwd);
+  let status = readStatus(cwd);
   const specEntry = status.specs[found.name];
+  if (specEntry?.status === "done") {
+    throw new Error(`Spec '${found.name}' is already done. Reset its status in .toby/status.json to rebuild.`);
+  }
   if (!specEntry || specEntry.status !== "planned" && specEntry.status !== "building") {
     throw new Error(`No plan found for ${found.name}. Run 'toby plan --spec=${flags2.spec}' first.`);
   }
   const existingIterations = specEntry.iterations.length;
-  const resume = detectResume(specEntry, commandConfig.cli, status.lastCli);
-  const session = flags2.session || (resume.needsResume ? status.sessionName : null) || computeSpecSlug(found.name);
-  if (resume.isCrashResume) {
-    const isSameCli = commandConfig.cli === status.lastCli;
-    const resumeType = isSameCli ? "continuing session" : `switching from ${status.lastCli} to ${commandConfig.cli}`;
-    callbacks.onOutput?.(`Resuming session "${session}" (${resumeType})`);
-  } else if (resume.isExhaustedResume) {
-    callbacks.onOutput?.(`\u26A0 Previous build exhausted iterations without completing. Resuming in worktree "${session}"...`);
+  const session = flags2.session || status.session?.name || computeSpecSlug(found.name);
+  const sessionCli = status.session?.cli ?? commandConfig.cli;
+  const resumeSessionId = resolveResumeSessionId(specEntry, commandConfig.cli, sessionCli);
+  if (!status.session) {
+    const sessionObj = createSession(session, commandConfig.cli, [found.name]);
+    status = { ...status, session: sessionObj };
+    writeStatus(status, cwd);
   }
   return withTranscript(
     { flags: flags2, config, command: "build", specName: found.name },
@@ -1343,7 +1615,7 @@ async function executeBuild(flags2, callbacks = {}, cwd = process.cwd(), abortSi
         templateVars: config.templateVars,
         specsDir: config.specsDir,
         session,
-        sessionId: resume.sessionId,
+        sessionId: resumeSessionId,
         specIndex: 1,
         specCount: 1,
         specs: [found.name],
@@ -1352,7 +1624,14 @@ async function executeBuild(flags2, callbacks = {}, cwd = process.cwd(), abortSi
         callbacks,
         writer
       });
-      return { ...result, needsResume: resume.needsResume };
+      let finalStatus = readStatus(cwd);
+      if (result.specDone) {
+        finalStatus = clearSession(finalStatus);
+      } else {
+        finalStatus = updateSessionState(finalStatus, "interrupted");
+      }
+      writeStatus(finalStatus, cwd);
+      return result;
     }
   );
 }
@@ -1374,62 +1653,99 @@ async function executeBuildAll(flags2, callbacks = {}, cwd = process.cwd(), abor
   }
   const built = [];
   const specNames = planned.map((s) => s.name);
-  const status = readStatus(cwd);
+  let status = readStatus(cwd);
+  const buildable = planned.filter((spec) => {
+    const entry = status.specs[spec.name];
+    return entry?.status !== "done";
+  });
   const commandConfig = resolveCommandConfig(config, "build", {
     cli: flags2.cli,
     iterations: flags2.iterations
   });
-  const anyNeedsResume = planned.some((spec) => {
-    return detectResume(status.specs[spec.name], commandConfig.cli, status.lastCli).needsResume;
-  });
-  const session = flags2.session || (anyNeedsResume ? status.sessionName : null) || generateSessionName();
+  const session = flags2.session || status.session?.name || generateSessionName();
+  const sessionCli = status.session?.cli ?? commandConfig.cli;
+  const existingSession = status.session;
+  if (!existingSession) {
+    const sessionObj2 = createSession(session, commandConfig.cli, specNames);
+    status = { ...status, session: sessionObj2 };
+    writeStatus(status, cwd);
+  } else {
+    status = updateSessionState(status, "active");
+    writeStatus(status, cwd);
+  }
+  const sessionObj = status.session;
   return withTranscript(
     { flags: { ...flags2, session: flags2.session ?? session }, config, command: "build" },
     void 0,
     async (writer) => {
-      for (let i = 0; i < planned.length; i++) {
-        const spec = planned[i];
-        writer?.writeSpecHeader(i + 1, planned.length, spec.name);
-        callbacks.onSpecStart?.(spec.name, i, planned.length);
-        const specEntry = status.specs[spec.name];
-        const existingIterations = specEntry?.iterations.length ?? 0;
-        const resume = detectResume(specEntry, commandConfig.cli, status.lastCli);
-        if (resume.isCrashResume) {
-          const lastIteration = specEntry?.iterations.at(-1);
-          callbacks.onOutput?.(
-            `\u26A0 [${spec.name}] Previous build interrupted (iteration ${lastIteration?.iteration} was in progress). Resuming...`
-          );
-        } else if (resume.isExhaustedResume) {
-          callbacks.onOutput?.(
-            `\u26A0 [${spec.name}] Previous build exhausted iterations without completing. Resuming in same worktree...`
-          );
+      try {
+        for (let i = 0; i < buildable.length; i++) {
+          const spec = buildable[i];
+          const specIndex = planned.indexOf(spec) + 1;
+          writer?.writeSpecHeader(specIndex, planned.length, spec.name);
+          callbacks.onSpecStart?.(spec.name, specIndex - 1, planned.length);
+          const specEntry = status.specs[spec.name];
+          const existingIterations = specEntry?.iterations.length ?? 0;
+          const resumeSessionId = resolveResumeSessionId(specEntry, commandConfig.cli, sessionCli);
+          const { result } = await runSpecBuild({
+            spec,
+            promptName: "PROMPT_BUILD",
+            existingIterations,
+            iterations: commandConfig.iterations,
+            cli: commandConfig.cli,
+            model: commandConfig.model,
+            templateVars: config.templateVars,
+            specsDir: config.specsDir,
+            session,
+            sessionId: resumeSessionId,
+            specIndex,
+            specCount: planned.length,
+            specs: specNames,
+            cwd,
+            abortSignal,
+            callbacks: {
+              onPhase: callbacks.onPhase,
+              onIteration: callbacks.onIteration,
+              onEvent: callbacks.onEvent,
+              onOutput: callbacks.onOutput
+            },
+            writer
+          });
+          built.push(result);
+          callbacks.onSpecComplete?.(result);
+          if (!result.specDone) {
+            let currentStatus = readStatus(cwd);
+            currentStatus = updateSessionState(currentStatus, "interrupted");
+            writeStatus(currentStatus, cwd);
+            const allSpecNames = sessionObj.specs;
+            const doneSpecs = allSpecNames.filter((name) => {
+              return currentStatus.specs[name]?.status === "done";
+            });
+            const remainingSpecs = allSpecNames.filter((name) => !doneSpecs.includes(name));
+            callbacks.onOutput?.(
+              `Session "${sessionObj.name}" interrupted at ${spec.name} (${result.error ? "error" : "incomplete"}).`
+            );
+            callbacks.onOutput?.(
+              `Completed: ${doneSpecs.join(", ") || "none"} (${doneSpecs.length}/${allSpecNames.length})`
+            );
+            callbacks.onOutput?.(
+              `Remaining: ${remainingSpecs.join(", ")} (${remainingSpecs.length}/${allSpecNames.length})`
+            );
+            callbacks.onOutput?.("Run 'toby resume' to continue.");
+            break;
+          }
         }
-        const { result } = await runSpecBuild({
-          spec,
-          promptName: "PROMPT_BUILD",
-          existingIterations,
-          iterations: commandConfig.iterations,
-          cli: commandConfig.cli,
-          model: commandConfig.model,
-          templateVars: config.templateVars,
-          specsDir: config.specsDir,
-          session,
-          sessionId: resume.sessionId,
-          specIndex: i + 1,
-          specCount: planned.length,
-          specs: specNames,
-          cwd,
-          abortSignal,
-          callbacks: {
-            onPhase: callbacks.onPhase,
-            onIteration: callbacks.onIteration,
-            onEvent: callbacks.onEvent,
-            onOutput: callbacks.onOutput
-          },
-          writer
-        });
-        built.push({ ...result, needsResume: resume.needsResume });
-        callbacks.onSpecComplete?.({ ...result, needsResume: resume.needsResume });
+      } catch (err) {
+        if (err instanceof AbortError) {
+          const currentStatus = readStatus(cwd);
+          writeStatus(updateSessionState(currentStatus, "interrupted"), cwd);
+        }
+        throw err;
+      }
+      const finalStatus = readStatus(cwd);
+      const allDone = sessionObj.specs.every((name) => finalStatus.specs[name]?.status === "done");
+      if (allDone) {
+        writeStatus(clearSession(finalStatus), cwd);
       }
       return { built };
     }
@@ -2696,13 +3012,123 @@ function Clean({ force }) {
   return null;
 }
 
+// src/commands/resume.tsx
+import { useState as useState9, useEffect as useEffect8, useRef as useRef2 } from "react";
+import { Box as Box9, Text as Text10, useApp as useApp5 } from "ink";
+import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
+async function executeResume(flags2, callbacks = {}, cwd = process.cwd(), abortSignal) {
+  const status = readStatus(cwd);
+  if (!hasResumableSession(status)) {
+    throw new Error(
+      "No active session to resume. Use 'toby build --spec=<name>' to start a new build."
+    );
+  }
+  const session = status.session;
+  const config = loadConfig(cwd);
+  const commandConfig = resolveCommandConfig(config, "build", {
+    iterations: flags2.iterations
+  });
+  const allSpecs = discoverSpecs(cwd, config);
+  const incompleteNames = [];
+  const missingNames = [];
+  for (const specName of session.specs) {
+    const entry = status.specs[specName];
+    if (entry?.status === "done") {
+      callbacks.onOutput?.(`  \u2713 ${specName} (done, skipping)`);
+      continue;
+    }
+    const found = findSpec(allSpecs, specName);
+    if (!found) {
+      missingNames.push(specName);
+      callbacks.onOutput?.(`  \u26A0 ${specName} (not found in specs/, skipping)`);
+      continue;
+    }
+    incompleteNames.push(specName);
+  }
+  if (missingNames.length === session.specs.length) {
+    throw new Error(
+      "All session specs are missing from specs/ directory. Cannot resume."
+    );
+  }
+  if (incompleteNames.length === 0) {
+    throw new Error(
+      missingNames.length > 0 ? "All remaining session specs are missing from specs/. Nothing to resume." : "All specs in this session are already done. Nothing to resume."
+    );
+  }
+  const specsToResume = incompleteNames.map((name) => findSpec(allSpecs, name));
+  callbacks.onOutput?.(`Resuming session "${session.name}" with ${specsToResume.length} spec(s):`);
+  for (const spec of specsToResume) {
+    callbacks.onOutput?.(`  \u2192 ${spec.name}`);
+  }
+  const updatedStatus = updateSessionState(status, "active");
+  writeStatus(updatedStatus, cwd);
+  const buildFlags = {
+    spec: void 0,
+    all: true,
+    iterations: flags2.iterations ?? commandConfig.iterations,
+    verbose: flags2.verbose ?? false,
+    transcript: flags2.transcript,
+    cli: commandConfig.cli,
+    session: session.name
+  };
+  return executeBuildAll(buildFlags, callbacks, cwd, abortSignal, specsToResume);
+}
+function Resume(props) {
+  const { exit } = useApp5();
+  const [phase, setPhase] = useState9("loading");
+  const [messages, setMessages] = useState9([]);
+  const [result, setResult] = useState9(null);
+  const [errorMessage, setErrorMessage] = useState9("");
+  const abortController = useRef2(new AbortController());
+  useEffect8(() => {
+    const callbacks = {
+      onOutput: (msg) => setMessages((prev) => [...prev, msg])
+    };
+    setPhase("building");
+    executeResume(props, callbacks, void 0, abortController.current.signal).then((r) => {
+      setResult(r);
+      setPhase("done");
+    }).catch((err) => {
+      if (abortController.current.signal.aborted) return;
+      setErrorMessage(err.message);
+      setPhase("error");
+    });
+    return () => {
+      abortController.current.abort();
+    };
+  }, []);
+  useEffect8(() => {
+    if (phase === "done" || phase === "error") {
+      const timer = setTimeout(() => exit(), 100);
+      return () => clearTimeout(timer);
+    }
+  }, [phase, exit]);
+  if (phase === "error") {
+    return /* @__PURE__ */ jsx10(Text10, { color: "red", children: errorMessage });
+  }
+  if (phase === "done" && result) {
+    const totalIter = result.built.reduce((s, r) => s + r.totalIterations, 0);
+    const totalTok = result.built.reduce((s, r) => s + r.totalTokens, 0);
+    return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", children: [
+      messages.map((msg, i) => /* @__PURE__ */ jsx10(Text10, { dimColor: true, children: msg }, i)),
+      /* @__PURE__ */ jsx10(Text10, { color: "green", children: `\u2713 Resume complete (${result.built.length} spec(s) built)` }),
+      result.built.map((r) => /* @__PURE__ */ jsx10(Text10, { children: `  ${r.specName}: ${r.totalIterations} iterations, ${r.totalTokens} tokens${r.specDone ? " [done]" : ""}` }, r.specName)),
+      /* @__PURE__ */ jsx10(Text10, { dimColor: true, children: `  Total: ${totalIter} iterations, ${totalTok} tokens` })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", children: [
+    messages.map((msg, i) => /* @__PURE__ */ jsx10(Text10, { dimColor: true, children: msg }, i)),
+    /* @__PURE__ */ jsx10(Text10, { dimColor: true, children: "Resuming build..." })
+  ] });
+}
+
 // src/components/Welcome.tsx
-import { useState as useState10, useEffect as useEffect9, useMemo as useMemo6 } from "react";
-import { Box as Box12, Text as Text13, useApp as useApp5, useStdout as useStdout2 } from "ink";
+import { useState as useState11, useEffect as useEffect10, useMemo as useMemo6 } from "react";
+import { Box as Box13, Text as Text14, useApp as useApp6, useStdout as useStdout2 } from "ink";
 
 // src/components/hamster/HamsterWheel.tsx
-import { useState as useState9, useEffect as useEffect8, useMemo as useMemo5 } from "react";
-import { Box as Box9, Text as Text10, useStdout } from "ink";
+import { useState as useState10, useEffect as useEffect9, useMemo as useMemo5 } from "react";
+import { Box as Box10, Text as Text11, useStdout } from "ink";
 
 // src/components/hamster/palette.ts
 var PALETTE = {
@@ -2861,7 +3287,7 @@ function generateWheelPixels(cx, cy, outerRadius, innerRadius, spokeAngle, aspec
 }
 
 // src/components/hamster/HamsterWheel.tsx
-import { jsx as jsx10 } from "react/jsx-runtime";
+import { jsx as jsx11 } from "react/jsx-runtime";
 function buildGrid(width, height) {
   return Array.from(
     { length: height },
@@ -2944,9 +3370,9 @@ function HamsterWheel({
     heightProp,
     columns
   );
-  const [frame, setFrame] = useState9(0);
-  const [spokeAngle, setSpokeAngle] = useState9(0);
-  useEffect8(() => {
+  const [frame, setFrame] = useState10(0);
+  const [spokeAngle, setSpokeAngle] = useState10(0);
+  useEffect9(() => {
     if (speed === 0 || isStatic) return;
     const interval = computeInterval(HAMSTER_BASE_INTERVAL, speed);
     const id = setInterval(() => {
@@ -2954,7 +3380,7 @@ function HamsterWheel({
     }, interval);
     return () => clearInterval(id);
   }, [speed, isStatic]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (speed === 0 || isStatic) return;
     const interval = computeInterval(WHEEL_BASE_INTERVAL, speed);
     const id = setInterval(() => {
@@ -2994,60 +3420,61 @@ function HamsterWheel({
     return buildColorRuns(grid, resolvedWidth, resolvedHeight);
   }, [resolvedWidth, resolvedHeight, frame, spokeAngle, isStatic]);
   if (isStatic) {
-    return /* @__PURE__ */ jsx10(Text10, { children: "  \u{1F439} toby" });
+    return /* @__PURE__ */ jsx11(Text11, { children: "  \u{1F439} toby" });
   }
-  return /* @__PURE__ */ jsx10(Box9, { flexDirection: "column", children: renderedRows.map((runs, y) => /* @__PURE__ */ jsx10(Text10, { children: runs.map((run, i) => /* @__PURE__ */ jsx10(Text10, { color: run.fg, backgroundColor: run.bg, children: run.char.repeat(run.length) }, i)) }, y)) });
+  return /* @__PURE__ */ jsx11(Box10, { flexDirection: "column", children: renderedRows.map((runs, y) => /* @__PURE__ */ jsx11(Text11, { children: runs.map((run, i) => /* @__PURE__ */ jsx11(Text11, { color: run.fg, backgroundColor: run.bg, children: run.char.repeat(run.length) }, i)) }, y)) });
 }
 
 // src/components/InfoPanel.tsx
-import { Box as Box10, Text as Text11 } from "ink";
-import { jsx as jsx11, jsxs as jsxs9 } from "react/jsx-runtime";
+import { Box as Box11, Text as Text12 } from "ink";
+import { jsx as jsx12, jsxs as jsxs10 } from "react/jsx-runtime";
 var formatTokens = (n) => new Intl.NumberFormat().format(n);
 function StatRow({ label, value }) {
-  return /* @__PURE__ */ jsxs9(Box10, { children: [
-    /* @__PURE__ */ jsxs9(Text11, { dimColor: true, children: [
+  return /* @__PURE__ */ jsxs10(Box11, { children: [
+    /* @__PURE__ */ jsxs10(Text12, { dimColor: true, children: [
       String(label).padStart(9),
       "  "
     ] }),
-    /* @__PURE__ */ jsx11(Text11, { children: value })
+    /* @__PURE__ */ jsx12(Text12, { children: value })
   ] });
 }
 function InfoPanel({ version: version2, stats }) {
-  return /* @__PURE__ */ jsxs9(Box10, { flexDirection: "column", children: [
-    /* @__PURE__ */ jsxs9(Text11, { bold: true, color: "#f0a030", children: [
+  return /* @__PURE__ */ jsxs10(Box11, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs10(Text12, { bold: true, color: "#f0a030", children: [
       "toby v",
       version2
     ] }),
-    stats !== null && /* @__PURE__ */ jsxs9(Box10, { flexDirection: "column", marginTop: 1, children: [
-      /* @__PURE__ */ jsx11(StatRow, { label: "Specs", value: stats.totalSpecs }),
-      /* @__PURE__ */ jsx11(StatRow, { label: "Planned", value: stats.planned }),
-      /* @__PURE__ */ jsx11(StatRow, { label: "Done", value: stats.done }),
-      /* @__PURE__ */ jsx11(StatRow, { label: "Tokens", value: formatTokens(stats.totalTokens) })
+    stats !== null && /* @__PURE__ */ jsxs10(Box11, { flexDirection: "column", marginTop: 1, children: [
+      /* @__PURE__ */ jsx12(StatRow, { label: "Specs", value: stats.totalSpecs }),
+      /* @__PURE__ */ jsx12(StatRow, { label: "Planned", value: stats.planned }),
+      /* @__PURE__ */ jsx12(StatRow, { label: "Done", value: stats.done }),
+      /* @__PURE__ */ jsx12(StatRow, { label: "Tokens", value: formatTokens(stats.totalTokens) })
     ] })
   ] });
 }
 
 // src/components/MainMenu.tsx
-import { Text as Text12, Box as Box11 } from "ink";
+import { Text as Text13, Box as Box12 } from "ink";
 import SelectInput3 from "ink-select-input";
-import { jsx as jsx12, jsxs as jsxs10 } from "react/jsx-runtime";
+import { jsx as jsx13, jsxs as jsxs11 } from "react/jsx-runtime";
 var MENU_ITEMS = [
   { label: "plan", value: "plan", description: "Plan specs with AI loop engine" },
   { label: "build", value: "build", description: "Build tasks one-per-spawn with AI" },
+  { label: "resume", value: "resume", description: "Resume an interrupted build session" },
   { label: "status", value: "status", description: "Show project status" },
   { label: "config", value: "config", description: "Manage configuration" }
 ];
 function MenuItem({ isSelected = false, label, description }) {
-  return /* @__PURE__ */ jsxs10(Box11, { children: [
-    /* @__PURE__ */ jsx12(Text12, { color: isSelected ? "blue" : void 0, children: label.padEnd(10) }),
-    description && /* @__PURE__ */ jsxs10(Text12, { dimColor: true, children: [
+  return /* @__PURE__ */ jsxs11(Box12, { children: [
+    /* @__PURE__ */ jsx13(Text13, { color: isSelected ? "blue" : void 0, children: label.padEnd(10) }),
+    description && /* @__PURE__ */ jsxs11(Text13, { dimColor: true, children: [
       "\u2014 ",
       description
     ] })
   ] });
 }
 function MainMenu({ onSelect }) {
-  return /* @__PURE__ */ jsx12(Box11, { flexDirection: "column", children: /* @__PURE__ */ jsx12(
+  return /* @__PURE__ */ jsx13(Box12, { flexDirection: "column", children: /* @__PURE__ */ jsx13(
     SelectInput3,
     {
       items: MENU_ITEMS,
@@ -3102,163 +3529,102 @@ function computeProjectStats(cwd) {
 }
 
 // src/components/Welcome.tsx
-import { jsx as jsx13, jsxs as jsxs11 } from "react/jsx-runtime";
+import { jsx as jsx14, jsxs as jsxs12 } from "react/jsx-runtime";
 var NARROW_THRESHOLD = 60;
 function Welcome({ version: version2 }) {
-  const { exit } = useApp5();
+  const { exit } = useApp6();
   const { stdout } = useStdout2();
-  const [selectedCommand, setSelectedCommand] = useState10(null);
+  const [selectedCommand, setSelectedCommand] = useState11(null);
   const stats = useMemo6(() => computeProjectStats(), []);
   const isNarrow = (stdout.columns ?? 80) < NARROW_THRESHOLD;
-  useEffect9(() => {
+  useEffect10(() => {
     if (selectedCommand === "status") {
       const timer = setTimeout(() => exit(), 0);
       return () => clearTimeout(timer);
     }
   }, [selectedCommand, exit]);
   if (selectedCommand === "plan") {
-    return /* @__PURE__ */ jsx13(Plan, {});
+    return /* @__PURE__ */ jsx14(Plan, {});
   }
   if (selectedCommand === "build") {
-    return /* @__PURE__ */ jsx13(Build, {});
+    return /* @__PURE__ */ jsx14(Build, {});
+  }
+  if (selectedCommand === "resume") {
+    return /* @__PURE__ */ jsx14(Resume, {});
   }
   if (selectedCommand === "status") {
-    return /* @__PURE__ */ jsx13(Status, { version: version2 });
+    return /* @__PURE__ */ jsx14(Status, { version: version2 });
   }
   if (selectedCommand === "config") {
-    return /* @__PURE__ */ jsx13(ConfigEditor, { version: version2 });
+    return /* @__PURE__ */ jsx14(ConfigEditor, { version: version2 });
   }
-  return /* @__PURE__ */ jsxs11(Box12, { flexDirection: "column", gap: 1, children: [
-    isNarrow ? /* @__PURE__ */ jsxs11(Box12, { flexDirection: "column", children: [
-      /* @__PURE__ */ jsxs11(Text13, { bold: true, color: "#f0a030", children: [
+  return /* @__PURE__ */ jsxs12(Box13, { flexDirection: "column", gap: 1, children: [
+    isNarrow ? /* @__PURE__ */ jsxs12(Box13, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs12(Text14, { bold: true, color: "#f0a030", children: [
         "\u{1F439} toby v",
         version2
       ] }),
-      stats !== null && /* @__PURE__ */ jsxs11(Text13, { children: [
-        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: "Specs: " }),
-        /* @__PURE__ */ jsx13(Text13, { children: stats.totalSpecs }),
-        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Planned: " }),
-        /* @__PURE__ */ jsx13(Text13, { children: stats.planned }),
-        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Done: " }),
-        /* @__PURE__ */ jsx13(Text13, { children: stats.done }),
-        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Tokens: " }),
-        /* @__PURE__ */ jsx13(Text13, { children: formatTokens(stats.totalTokens) })
+      stats !== null && /* @__PURE__ */ jsxs12(Text14, { children: [
+        /* @__PURE__ */ jsx14(Text14, { dimColor: true, children: "Specs: " }),
+        /* @__PURE__ */ jsx14(Text14, { children: stats.totalSpecs }),
+        /* @__PURE__ */ jsx14(Text14, { dimColor: true, children: " \xB7 Planned: " }),
+        /* @__PURE__ */ jsx14(Text14, { children: stats.planned }),
+        /* @__PURE__ */ jsx14(Text14, { dimColor: true, children: " \xB7 Done: " }),
+        /* @__PURE__ */ jsx14(Text14, { children: stats.done }),
+        /* @__PURE__ */ jsx14(Text14, { dimColor: true, children: " \xB7 Tokens: " }),
+        /* @__PURE__ */ jsx14(Text14, { children: formatTokens(stats.totalTokens) })
       ] })
-    ] }) : /* @__PURE__ */ jsxs11(Box12, { flexDirection: "row", gap: 2, children: [
-      /* @__PURE__ */ jsx13(HamsterWheel, {}),
-      /* @__PURE__ */ jsx13(InfoPanel, { version: version2, stats })
+    ] }) : /* @__PURE__ */ jsxs12(Box13, { flexDirection: "row", gap: 2, children: [
+      /* @__PURE__ */ jsx14(HamsterWheel, {}),
+      /* @__PURE__ */ jsx14(InfoPanel, { version: version2, stats })
     ] }),
-    /* @__PURE__ */ jsx13(MainMenu, { onSelect: setSelectedCommand })
+    /* @__PURE__ */ jsx14(MainMenu, { onSelect: setSelectedCommand })
   ] });
 }
 
-// src/cli.tsx
-import { jsx as jsx14 } from "react/jsx-runtime";
-function Help({ version: version2 }) {
-  return /* @__PURE__ */ jsx14(Text14, { children: `toby v${version2} \u2014 AI-assisted development loop engine
-
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-  clean    Delete all transcript files
-
-Options
-  --help       Show this help
-  --version    Show version
-
-Spec Selection
-  --spec=<name>       Single spec or comma-separated (e.g. --spec=auth,payments)
-  --specs=<names>     Alias for --spec` });
-}
-function UnknownCommand({ command: command2 }) {
-  return /* @__PURE__ */ jsx14(Text14, { color: "red", children: `Unknown command: ${command2}
-Run "toby --help" for available commands.` });
-}
-var cli = meow(
-  `
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-  clean    Delete all transcript files
-
-Plan Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Plan all pending specs
-  --iterations=<n>   Override iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Build Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Build all planned specs in order
-  --iterations=<n>   Override max iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Status Options
-  --spec=<query>     Show status for a spec by name, slug, or number
-
-Init Options
-  --plan-cli=<name>    Set plan CLI (claude, codex, opencode)
-  --plan-model=<id>    Set plan model
-  --build-cli=<name>   Set build CLI (claude, codex, opencode)
-  --build-model=<id>   Set build model
-  --specs-dir=<path>   Set specs directory
-  --verbose            Enable verbose output in config
-
-Config Subcommands
-  config             Interactive config editor
-  config get <key>   Show a config value (dot-notation)
-  config set <key> <value>  Set a config value
-  config set <k>=<v> [<k>=<v>...]  Batch set config values
+// src/lib/cli-meta.ts
+var COMMAND_NAMES = Object.keys(commandHelp);
+var MEOW_FLAGS = {
+  help: { type: "boolean", default: false },
+  spec: { type: "string" },
+  specs: { type: "string" },
+  all: { type: "boolean", default: false },
+  iterations: { type: "number" },
+  verbose: { type: "boolean", default: false },
+  transcript: { type: "boolean" },
+  cli: { type: "string" },
+  planCli: { type: "string" },
+  planModel: { type: "string" },
+  buildCli: { type: "string" },
+  buildModel: { type: "string" },
+  specsDir: { type: "string" },
+  session: { type: "string" },
+  force: { type: "boolean", default: false }
+};
+var MEOW_FLAG_NAMES = Object.keys(MEOW_FLAGS);
 
-Clean Options
-  --force    Skip confirmation prompt
-`,
-  {
-    importMeta: import.meta,
-    flags: {
-      spec: { type: "string" },
-      specs: { type: "string" },
-      all: { type: "boolean", default: false },
-      iterations: { type: "number" },
-      verbose: { type: "boolean", default: false },
-      transcript: { type: "boolean" },
-      cli: { type: "string" },
-      planCli: { type: "string" },
-      planModel: { type: "string" },
-      buildCli: { type: "string" },
-      buildModel: { type: "string" },
-      specsDir: { type: "string" },
-      session: { type: "string" },
-      force: { type: "boolean", default: false }
-    }
-  }
-);
+// src/cli.tsx
+import { jsx as jsx15 } from "react/jsx-runtime";
+function writeUnknownCommandError(command2) {
+  process.stderr.write(
+    formatErrorWithHint(
+      `Unknown command: ${command2}`,
+      COMMAND_NAMES,
+      "toby --help"
+    )
+  );
+}
+var cli = meow("", {
+  importMeta: import.meta,
+  autoHelp: false,
+  flags: MEOW_FLAGS
+});
 ensureGlobalDir();
 var resolvedSpec = cli.flags.specs ?? cli.flags.spec;
 var flags = { ...cli.flags, spec: resolvedSpec };
 var commands = {
   plan: {
-    render: (flags2) => /* @__PURE__ */ jsx14(
+    render: (flags2) => /* @__PURE__ */ jsx15(
       Plan,
       {
         spec: flags2.spec,
@@ -3273,7 +3639,7 @@ var commands = {
     waitForExit: true
   },
   build: {
-    render: (flags2) => /* @__PURE__ */ jsx14(
+    render: (flags2) => /* @__PURE__ */ jsx15(
       Build,
       {
         spec: flags2.spec,
@@ -3288,7 +3654,7 @@ var commands = {
     waitForExit: true
   },
   init: {
-    render: (flags2, _input, version2) => /* @__PURE__ */ jsx14(
+    render: (flags2, _input, version2) => /* @__PURE__ */ jsx15(
       Init,
       {
         version: version2,
@@ -3303,21 +3669,32 @@ var commands = {
     waitForExit: true
   },
   status: {
-    render: (flags2, _input, version2) => /* @__PURE__ */ jsx14(Status, { spec: flags2.spec, version: version2 })
+    render: (flags2, _input, version2) => /* @__PURE__ */ jsx15(Status, { spec: flags2.spec, version: version2 })
+  },
+  resume: {
+    render: (flags2) => /* @__PURE__ */ jsx15(
+      Resume,
+      {
+        iterations: flags2.iterations,
+        verbose: flags2.verbose,
+        transcript: flags2.transcript
+      }
+    ),
+    waitForExit: true
   },
   clean: {
-    render: (flags2) => /* @__PURE__ */ jsx14(Clean, { force: flags2.force }),
+    render: (flags2) => /* @__PURE__ */ jsx15(Clean, { force: flags2.force }),
     waitForExit: true
   },
   config: {
     render: (_flags, input, version2) => {
       const [, subcommand, ...rest] = input;
-      if (!subcommand) return /* @__PURE__ */ jsx14(ConfigEditor, { version: version2 });
+      if (!subcommand) return /* @__PURE__ */ jsx15(ConfigEditor, { version: version2 });
       if (subcommand === "set" && rest.some((arg) => arg.includes("="))) {
-        return /* @__PURE__ */ jsx14(ConfigSetBatch, { pairs: rest.filter((arg) => arg.includes("=")) });
+        return /* @__PURE__ */ jsx15(ConfigSetBatch, { pairs: rest.filter((arg) => arg.includes("=")) });
       }
       const [configKey, value] = rest;
-      return /* @__PURE__ */ jsx14(
+      return /* @__PURE__ */ jsx15(
         Config,
         {
           subcommand,
@@ -3332,12 +3709,24 @@ var commands = {
 };
 var version = cli.pkg.version ?? "0.0.0";
 var [command] = cli.input;
-if (!command) {
+if (cli.flags.help) {
+  if (!command || command in commands) {
+    if (command && command in commandHelp) {
+      process.stdout.write(formatCommandHelp(command, commandHelp[command]));
+    } else {
+      process.stdout.write(formatGlobalHelp(version));
+    }
+    process.exitCode = 0;
+  } else {
+    writeUnknownCommandError(command);
+    process.exitCode = 1;
+  }
+} else if (!command) {
   if (process.stdin.isTTY) {
-    const app = render(/* @__PURE__ */ jsx14(Welcome, { version }));
+    const app = render(/* @__PURE__ */ jsx15(Welcome, { version }));
     await app.waitUntilExit();
   } else {
-    render(/* @__PURE__ */ jsx14(Help, { version })).unmount();
+    process.stdout.write(formatGlobalHelp(version));
   }
 } else if (command in commands) {
   const entry = commands[command];
@@ -3348,6 +3737,6 @@ if (!command) {
     app.unmount();
   }
 } else {
-  render(/* @__PURE__ */ jsx14(UnknownCommand, { command })).unmount();
+  writeUnknownCommandError(command);
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xtiby/toby",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "AI-assisted development loop engine CLI",
   "repository": {
     "type": "git",