syntaur 0.56.0 → 0.58.0

package/dist/index.js

@@ -1483,6 +1483,7 @@ __export(parser_exports, {
   readLog: () => readLog,
   serializeChecklist: () => serializeChecklist,
   serializeChecklistItem: () => serializeChecklistItem,
+  serializeLog: () => serializeLog,
   serializeLogEntry: () => serializeLogEntry,
   serializeMetaToken: () => serializeMetaToken,
   writeChecklist: () => writeChecklist
@@ -1610,27 +1611,60 @@ function statusToMarker(item) {
       return item.session ? `>:${sanitizeSession(item.session)}` : ">";
   }
 }
+function escapeDescription(description) {
+  return description.replace(/\\/g, "\\\\").replace(/#/g, "\\#").replace(/\[/g, "\\[");
+}
+function unescapeDescription(escaped) {
+  let out = "";
+  for (let i = 0; i < escaped.length; i++) {
+    if (escaped[i] === "\\" && i + 1 < escaped.length) {
+      const next = escaped[i + 1];
+      if (next === "\\" || next === "#" || next === "[") {
+        out += next;
+        i++;
+        continue;
+      }
+    }
+    out += escaped[i];
+  }
+  return out;
+}
+function findStructuralCut(rest) {
+  for (let i = 0; i < rest.length; i++) {
+    const ch = rest[i];
+    if (ch !== "#" && ch !== "[") continue;
+    let backslashes = 0;
+    let j = i - 1;
+    while (j >= 0 && rest[j] === "\\") {
+      backslashes++;
+      j--;
+    }
+    if (backslashes % 2 === 1) continue;
+    if (ch === "#") {
+      if (/[a-zA-Z0-9_-]/.test(rest[i + 1] ?? "")) return i;
+    } else {
+      return i;
+    }
+  }
+  return rest.length;
+}
 function parseChecklistItem(line) {
   const match = line.match(ITEM_REGEX);
   if (!match) return null;
   const marker = match[1];
   const rest = match[2];
   const { status, session } = parseStatus2(marker);
-  const idMatch = rest.match(ID_REGEX);
+  const cut = findStructuralCut(rest);
+  const description = unescapeDescription(rest.slice(0, cut).trim());
+  const tail = rest.slice(cut);
+  const idMatch = tail.match(ID_REGEX);
   const id = idMatch ? idMatch[1] : "";
   const tags = [];
   let tagMatch;
   const tagRegex = new RegExp(TAG_REGEX.source, "g");
-  while ((tagMatch = tagRegex.exec(rest)) !== null) {
+  while ((tagMatch = tagRegex.exec(tail)) !== null) {
     tags.push(tagMatch[1]);
   }
-  let description = rest;
-  const firstTagIdx = rest.search(/#[a-zA-Z0-9_-]/);
-  const firstIdIdx = rest.search(/\[t:[a-f0-9]{4}\]/);
-  const cutPoints = [firstTagIdx, firstIdIdx].filter((i) => i >= 0);
-  if (cutPoints.length > 0) {
-    description = rest.slice(0, Math.min(...cutPoints)).trim();
-  }
   const meta = parseMetaToken(line);
   return {
     id,
@@ -1651,7 +1685,7 @@ function parseChecklistItem(line) {
 function serializeChecklistItem(item) {
   const marker = statusToMarker(item);
   const tagStr = item.tags.map((t) => `#${t}`).join(" ");
-  const parts = [`- [${marker}] ${item.description}`];
+  const parts = [`- [${marker}] ${escapeDescription(item.description)}`];
   if (tagStr) parts.push(tagStr);
   parts.push(`[t:${item.id}]`);
   const meta = serializeMetaToken(item);
@@ -1750,6 +1784,18 @@ function serializeLogEntry(entry) {
   if (entry.status) lines.push(`**Status:** ${entry.status}`);
   return lines.join("\n");
 }
+function serializeLog(log) {
+  const header = `---
+workspace: ${log.workspace}
+---
+
+# Todo Log
+`;
+  if (log.entries.length === 0) {
+    return header;
+  }
+  return header + "\n" + log.entries.map(serializeLogEntry).join("\n\n") + "\n";
+}
 function checklistPath(todosDir2, workspace) {
   return resolve3(todosDir2, `${workspace}.md`);
 }
@@ -8435,7 +8481,8 @@ __export(git_worktree_exports, {
   listBranches: () => listBranches,
   listWorktrees: () => listWorktrees,
   recreateWorktree: () => recreateWorktree,
-  removeWorktree: () => removeWorktree
+  removeWorktree: () => removeWorktree,
+  resolveBranchSha: () => resolveBranchSha
 });
 import { spawn } from "child_process";
 import { readFile as readFile11 } from "fs/promises";
@@ -8550,6 +8597,18 @@ async function captureHeadSha(dir) {
   const sha = result.stdout.trim();
   return sha.length > 0 ? sha : null;
 }
+async function resolveBranchSha(repository, branch) {
+  const result = await run("git", [
+    "-C",
+    repository,
+    "rev-parse",
+    "--short",
+    branch
+  ]);
+  if (result.code !== 0) return null;
+  const sha = result.stdout.trim();
+  return sha.length > 0 ? sha : null;
+}
 async function branchCheckedOutAt(repository, branch) {
   const result = await run("git", ["-C", repository, "worktree", "list", "--porcelain"]);
   if (result.code !== 0) return null;
@@ -12688,7 +12747,7 @@ async function scanSessions(opts = {}, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const statMtimeMs = deps.statMtimeMs ?? defaultStatMtimeMs2;
   const openFiles = deps.openFiles ?? defaultOpenFiles;
-  const isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;
+  const isPidAlive2 = deps.isPidAlive ?? defaultIsPidAlive;
   const pidStartedAt = deps.pidStartedAt ?? defaultPidStartedAt;
   const targets = (deps.targets ?? AGENT_TARGETS).filter((t) => t.sessions !== void 0);
   const scanStartMs = now();
@@ -12767,7 +12826,7 @@ async function scanSessions(opts = {}, deps = {}) {
   const sweepCandidates = [];
   for (const row of activeRows) {
     if (row.pid !== null) {
-      const alive = isPidAlive(row.pid) && (!row.pid_started_at || (pidStartedAt(row.pid) ?? row.pid_started_at) === row.pid_started_at);
+      const alive = isPidAlive2(row.pid) && (!row.pid_started_at || (pidStartedAt(row.pid) ?? row.pid_started_at) === row.pid_started_at);
       if (alive) continue;
     }
     if (row.transcript_path) {
@@ -16465,7 +16524,7 @@ ${nextBody}${nextBody.endsWith("\n") ? "" : "\n"}`;
       };
       const entry = formatCommentEntry(comment);
       let next = setTopLevelField(currentContent, "entryCount", String(currentCount + 1));
-      next = setTopLevelField(next, "updated", `"${timestamp}"`);
+      next = setTopLevelField(next, "updated", timestamp);
       if (next.includes("No comments yet.")) {
         next = next.replace("No comments yet.", entry.trimEnd());
       } else {
@@ -16525,7 +16584,7 @@ ${entry}`;
         res.status(500).json({ error: "Failed to update resolved flag" });
         return;
       }
-      const withUpdated = setTopLevelField(next, "updated", `"${nowTimestamp()}"`);
+      const withUpdated = setTopLevelField(next, "updated", nowTimestamp());
       await writeFileForce(commentsPath, withUpdated);
       const assignment = await getAssignmentDetail(projectsDir2, projectSlug, assignmentSlug);
       res.json({ assignment });
@@ -17994,7 +18053,7 @@ async function appendCommentTo(assignmentDir, assignmentRef, req2, res, reloadDe
   };
   const entry = formatCommentEntry(comment);
   let next = setTopLevelField(currentContent, "entryCount", String(currentCount + 1));
-  next = setTopLevelField(next, "updated", `"${timestamp}"`);
+  next = setTopLevelField(next, "updated", timestamp);
   if (next.includes("No comments yet.")) {
     next = next.replace("No comments yet.", entry.trimEnd());
   } else {
@@ -18037,7 +18096,7 @@ async function toggleCommentResolvedAt(assignmentDir, commentId, req2, res, relo
     res.status(500).json({ error: "Failed to update resolved flag" });
     return;
   }
-  const withUpdated = setTopLevelField(next, "updated", `"${nowTimestamp()}"`);
+  const withUpdated = setTopLevelField(next, "updated", nowTimestamp());
   await writeFileForce(commentsPath, withUpdated);
   const assignment = await reloadDetail();
   res.json({ assignment });
@@ -21505,6 +21564,119 @@ async function readEvents(jobId) {
 import { createHash as createHash3 } from "crypto";
 import { open as open4, readFile as readFile22, stat as stat3, unlink as unlink6 } from "fs/promises";
 import { resolve as resolve32 } from "path";
+
+// src/schedules/triggers.ts
+import { Cron } from "croner";
+
+// src/schedules/reset-window.ts
+var FIVE_HOURS_MS = 5 * 60 * 60 * 1e3;
+var ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1e3;
+function windowLengthMs(anchor) {
+  return anchor.windowKind === "weekly" ? ONE_WEEK_MS : FIVE_HOURS_MS;
+}
+function predictReset(_provider, anchor) {
+  const start = Date.parse(anchor.windowStartIso);
+  if (Number.isNaN(start)) {
+    throw new Error(`Invalid reset anchor windowStartIso: ${anchor.windowStartIso}`);
+  }
+  return new Date(start + windowLengthMs(anchor)).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function verifyReset(provider, anchor, now) {
+  const reset = predictReset(provider, anchor);
+  if (now.getTime() >= Date.parse(reset)) return { eligible: true };
+  return { eligible: false, rescheduleToIso: reset };
+}
+
+// src/schedules/triggers.ts
+function iso(d) {
+  return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function isRecurring(trigger) {
+  return trigger.kind === "cron";
+}
+var notDue = { due: false };
+function evaluateTrigger(job, ctx) {
+  const consumed = new Set(job.attempt.consumedEdges);
+  const result = evaluateKind(job.trigger, job, ctx);
+  if (result.due && result.dedupeKey && consumed.has(result.dedupeKey)) {
+    return { ...result, due: false };
+  }
+  return result;
+}
+function evaluateKind(trigger, job, ctx) {
+  const createdAtMs = Date.parse(job.createdAt);
+  switch (trigger.kind) {
+    case "at": {
+      const at = Date.parse(trigger.at);
+      const due = !Number.isNaN(at) && ctx.now.getTime() >= at;
+      return { due, dedupeKey: `at:${trigger.at}`, nextFireIso: trigger.at };
+    }
+    case "in": {
+      const anchor = Date.parse(trigger.anchorIso);
+      const fireAt = anchor + trigger.durationMs;
+      const due = !Number.isNaN(anchor) && ctx.now.getTime() >= fireAt;
+      const fireIso = Number.isNaN(anchor) ? null : iso(new Date(fireAt));
+      return { due, dedupeKey: `in:${fireAt}`, nextFireIso: fireIso };
+    }
+    case "cron":
+      return evaluateCron(trigger, ctx.now, createdAtMs);
+    case "after-reset":
+      return evaluateAfterReset(trigger, ctx.now);
+    case "when-status":
+      return evaluateWhenStatus(trigger, job, ctx, createdAtMs);
+    case "when-plan-lands":
+      return evaluateWhenPlanLands(ctx, createdAtMs);
+  }
+}
+function evaluateCron(trigger, now, createdAtMs) {
+  let cron;
+  try {
+    cron = new Cron(trigger.expr, trigger.tz ? { timezone: trigger.tz } : {});
+  } catch {
+    return notDue;
+  }
+  const prevs = cron.previousRuns(1, new Date(now.getTime() + 1e3));
+  let prev = prevs.length > 0 ? prevs[0] : null;
+  if (prev && prev.getTime() > now.getTime()) prev = null;
+  if (prev && !Number.isNaN(createdAtMs) && prev.getTime() < createdAtMs) prev = null;
+  const next = cron.nextRun(now);
+  if (!prev) return { due: false, nextFireIso: next ? iso(next) : null };
+  return { due: true, dedupeKey: `cron:${iso(prev)}`, nextFireIso: next ? iso(next) : null };
+}
+function evaluateAfterReset(trigger, now) {
+  const v = verifyReset(trigger.provider, trigger.anchor, now);
+  const predicted = predictReset(trigger.provider, trigger.anchor);
+  if (v.eligible) {
+    return { due: true, dedupeKey: `after-reset:${trigger.anchor.windowStartIso}`, nextFireIso: predicted };
+  }
+  return { due: false, nextFireIso: predicted, rescheduleToIso: v.rescheduleToIso };
+}
+function evaluateWhenStatus(trigger, job, ctx, createdAtMs) {
+  const fm = ctx.assignment;
+  if (!fm) return notDue;
+  const history = fm.statusHistory ?? [];
+  for (let i = job.attempt.cursor; i < history.length; i++) {
+    const atMs = Date.parse(history[i].at);
+    const afterCreation = Number.isNaN(createdAtMs) || Number.isNaN(atMs) || atMs >= createdAtMs;
+    if (history[i].to === trigger.status && afterCreation) {
+      return { due: true, dedupeKey: `status:${i}:${history[i].at}`, nextCursor: i + 1 };
+    }
+  }
+  return { due: false, nextCursor: history.length };
+}
+function evaluateWhenPlanLands(ctx, createdAtMs) {
+  const fm = ctx.assignment;
+  if (!fm) return notDue;
+  const approval = fm.planApproval;
+  if (!approval) return notDue;
+  const approvedMs = Date.parse(approval.at);
+  if (!Number.isNaN(createdAtMs) && !Number.isNaN(approvedMs) && approvedMs < createdAtMs) {
+    return notDue;
+  }
+  return { due: true, dedupeKey: `plan:${approval.file}:${approval.digest}` };
+}
+
+// src/schedules/attempt.ts
 init_timestamp();
 
 // src/schedules/types.ts
@@ -21703,6 +21875,15 @@ async function markLaunchFailed(job, reason) {
   await appendEvent(job.id, "launch_failed", { reason });
   return written;
 }
+async function markCompleted(job) {
+  const next = {
+    ...job,
+    attempt: { ...job.attempt, state: "completed", claim: null }
+  };
+  const written = await writeJob(next);
+  await appendEvent(job.id, "completed", { reason: "one-shot session ended" });
+  return written;
+}
 var TransitionError = class extends Error {
   constructor(message) {
     super(message);
@@ -21790,10 +21971,11 @@ function retryJob(id) {
     () => ({ claim: null, lastError: null })
   );
 }
+var ONE_SHOT_COMPLETE_GRACE_MS = 6e4;
 async function reapStale(jobs, deps) {
   const now = deps.now();
   const isLive = deps.isSessionLive ?? (() => true);
-  const out = { reaped: [], stuck: [] };
+  const out = { reaped: [], stuck: [], completed: [] };
   for (const job of jobs) {
     const a = job.attempt;
     if ((a.state === "claimed" || a.state === "launching") && a.claim && now.getTime() > a.claim.expiresAt) {
@@ -21802,7 +21984,17 @@ async function reapStale(jobs, deps) {
       out.reaped.push(job.id);
       continue;
     }
-    if (a.state === "running" && job.limits.maxRuntimeMs && a.runningSince) {
+    if (a.state !== "running") continue;
+    if (!isRecurring(job.trigger) && a.sessionId && a.runningSince) {
+      const graceMs = job.limits.maxRuntimeMs ?? ONE_SHOT_COMPLETE_GRACE_MS;
+      const pastGrace = now.getTime() - Date.parse(a.runningSince) > graceMs;
+      if (pastGrace && !isLive(a.sessionId, a.launchPid)) {
+        await markCompleted(job);
+        out.completed.push(job.id);
+        continue;
+      }
+    }
+    if (job.limits.maxRuntimeMs && a.runningSince) {
       const overrun = now.getTime() - Date.parse(a.runningSince) > job.limits.maxRuntimeMs;
       if (overrun && !isLive(a.sessionId, a.launchPid) && a.lastError !== "stuck:max-runtime") {
         await writeJob({ ...job, attempt: { ...a, lastError: "stuck:max-runtime" } });
@@ -21986,117 +22178,6 @@ init_frontmatter();
 import { readFile as readFile23 } from "fs/promises";
 import { resolve as resolve34 } from "path";
 
-// src/schedules/triggers.ts
-import { Cron } from "croner";
-
-// src/schedules/reset-window.ts
-var FIVE_HOURS_MS = 5 * 60 * 60 * 1e3;
-var ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1e3;
-function windowLengthMs(anchor) {
-  return anchor.windowKind === "weekly" ? ONE_WEEK_MS : FIVE_HOURS_MS;
-}
-function predictReset(_provider, anchor) {
-  const start = Date.parse(anchor.windowStartIso);
-  if (Number.isNaN(start)) {
-    throw new Error(`Invalid reset anchor windowStartIso: ${anchor.windowStartIso}`);
-  }
-  return new Date(start + windowLengthMs(anchor)).toISOString().replace(/\.\d{3}Z$/, "Z");
-}
-function verifyReset(provider, anchor, now) {
-  const reset = predictReset(provider, anchor);
-  if (now.getTime() >= Date.parse(reset)) return { eligible: true };
-  return { eligible: false, rescheduleToIso: reset };
-}
-
-// src/schedules/triggers.ts
-function iso(d) {
-  return d.toISOString().replace(/\.\d{3}Z$/, "Z");
-}
-function isRecurring(trigger) {
-  return trigger.kind === "cron";
-}
-var notDue = { due: false };
-function evaluateTrigger(job, ctx) {
-  const consumed = new Set(job.attempt.consumedEdges);
-  const result = evaluateKind(job.trigger, job, ctx);
-  if (result.due && result.dedupeKey && consumed.has(result.dedupeKey)) {
-    return { ...result, due: false };
-  }
-  return result;
-}
-function evaluateKind(trigger, job, ctx) {
-  const createdAtMs = Date.parse(job.createdAt);
-  switch (trigger.kind) {
-    case "at": {
-      const at = Date.parse(trigger.at);
-      const due = !Number.isNaN(at) && ctx.now.getTime() >= at;
-      return { due, dedupeKey: `at:${trigger.at}`, nextFireIso: trigger.at };
-    }
-    case "in": {
-      const anchor = Date.parse(trigger.anchorIso);
-      const fireAt = anchor + trigger.durationMs;
-      const due = !Number.isNaN(anchor) && ctx.now.getTime() >= fireAt;
-      const fireIso = Number.isNaN(anchor) ? null : iso(new Date(fireAt));
-      return { due, dedupeKey: `in:${fireAt}`, nextFireIso: fireIso };
-    }
-    case "cron":
-      return evaluateCron(trigger, ctx.now, createdAtMs);
-    case "after-reset":
-      return evaluateAfterReset(trigger, ctx.now);
-    case "when-status":
-      return evaluateWhenStatus(trigger, job, ctx, createdAtMs);
-    case "when-plan-lands":
-      return evaluateWhenPlanLands(ctx, createdAtMs);
-  }
-}
-function evaluateCron(trigger, now, createdAtMs) {
-  let cron;
-  try {
-    cron = new Cron(trigger.expr, trigger.tz ? { timezone: trigger.tz } : {});
-  } catch {
-    return notDue;
-  }
-  const prevs = cron.previousRuns(1, new Date(now.getTime() + 1e3));
-  let prev = prevs.length > 0 ? prevs[0] : null;
-  if (prev && prev.getTime() > now.getTime()) prev = null;
-  if (prev && !Number.isNaN(createdAtMs) && prev.getTime() < createdAtMs) prev = null;
-  const next = cron.nextRun(now);
-  if (!prev) return { due: false, nextFireIso: next ? iso(next) : null };
-  return { due: true, dedupeKey: `cron:${iso(prev)}`, nextFireIso: next ? iso(next) : null };
-}
-function evaluateAfterReset(trigger, now) {
-  const v = verifyReset(trigger.provider, trigger.anchor, now);
-  const predicted = predictReset(trigger.provider, trigger.anchor);
-  if (v.eligible) {
-    return { due: true, dedupeKey: `after-reset:${trigger.anchor.windowStartIso}`, nextFireIso: predicted };
-  }
-  return { due: false, nextFireIso: predicted, rescheduleToIso: v.rescheduleToIso };
-}
-function evaluateWhenStatus(trigger, job, ctx, createdAtMs) {
-  const fm = ctx.assignment;
-  if (!fm) return notDue;
-  const history = fm.statusHistory ?? [];
-  for (let i = job.attempt.cursor; i < history.length; i++) {
-    const atMs = Date.parse(history[i].at);
-    const afterCreation = Number.isNaN(createdAtMs) || Number.isNaN(atMs) || atMs >= createdAtMs;
-    if (history[i].to === trigger.status && afterCreation) {
-      return { due: true, dedupeKey: `status:${i}:${history[i].at}`, nextCursor: i + 1 };
-    }
-  }
-  return { due: false, nextCursor: history.length };
-}
-function evaluateWhenPlanLands(ctx, createdAtMs) {
-  const fm = ctx.assignment;
-  if (!fm) return notDue;
-  const approval = fm.planApproval;
-  if (!approval) return notDue;
-  const approvedMs = Date.parse(approval.at);
-  if (!Number.isNaN(createdAtMs) && !Number.isNaN(approvedMs) && approvedMs < createdAtMs) {
-    return notDue;
-  }
-  return { due: true, dedupeKey: `plan:${approval.file}:${approval.digest}` };
-}
-
 // src/schedules/launch-ack.ts
 init_session_id();
 import { readdirSync } from "fs";
@@ -22178,11 +22259,12 @@ async function defaultResolvePlan(job) {
 async function runTick(deps = {}) {
   const now = deps.now ?? (() => /* @__PURE__ */ new Date());
   const attemptDeps = { now, isSessionLive: deps.isSessionLive };
-  const result = { evaluated: 0, fired: [], failed: [], skipped: 0, reaped: [], stuck: [] };
+  const result = { evaluated: 0, fired: [], failed: [], skipped: 0, reaped: [], stuck: [], completed: [] };
   if (deps.reap !== false) {
     const reap = await reapStale(await listJobs(), attemptDeps);
     result.reaped = reap.reaped;
     result.stuck = reap.stuck;
+    result.completed = reap.completed;
   }
   const jobs = await listJobs();
   for (const job of jobs) {
@@ -23537,6 +23619,9 @@ workspace: ${workspace}
         await writeFileForce2(archFile, archContent);
         checklist.items = checklist.items.filter((i) => !completedIds.has(i.id));
         await writeChecklist(todosDir2, checklist);
+        const archivedEntries = new Set(toArchive);
+        log.entries = log.entries.filter((e) => !archivedEntries.has(e));
+        await writeFileForce2(logPath(todosDir2, workspace), serializeLog(log));
         for (const id of completedIds) {
           await deleteAllAttachments(todosDir2, workspace, id);
         }
@@ -24282,6 +24367,9 @@ workspace: ${slug}
         checklist.workspace = slug;
         checklist.items = checklist.items.filter((i) => !completedIds.has(i.id));
         await writeChecklist(todosDir2, checklist);
+        const archivedEntries = new Set(toArchive);
+        log.entries = log.entries.filter((e) => !archivedEntries.has(e));
+        await writeFileForce(logPath(todosDir2, slug), serializeLog(log));
         for (const id of completedIds) {
           await deleteAllAttachments(todosDir2, slug, id);
         }
@@ -26934,9 +27022,11 @@ function createDashboardServer(options) {
       return new Promise((resolvePromise, reject) => {
         server.on("error", (err2) => {
           if (err2.code === "EADDRINUSE") {
-            reject(new Error(
-              `Port ${port} is already in use. Use --port <number> to specify a different port.`
-            ));
+            const inUse = new Error(
+              `Port ${port} is already in use.`
+            );
+            inUse.code = "EADDRINUSE";
+            reject(inUse);
           } else {
             reject(err2);
           }
@@ -26979,6 +27069,54 @@ function createDashboardServer(options) {
 // src/commands/dashboard.ts
 init_paths();
 init_fs();
+
+// src/errors.ts
+var SyntaurError = class extends Error {
+  /** Actionable next step printed as `→ try: <remediation>` on stderr. */
+  remediation;
+  /** Optional non-1 exit code (e.g. doctor's exit 2). Defaults to 1. */
+  code;
+  constructor(message, options = {
+    remediation: ""
+  }) {
+    super(message);
+    this.name = "SyntaurError";
+    this.remediation = options.remediation;
+    this.code = options.code ?? 1;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+function isSyntaurError(error) {
+  return error instanceof SyntaurError;
+}
+function formatCliError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const lines = [`Error: ${message}`];
+  if (isSyntaurError(error) && error.remediation) {
+    lines.push(`\u2192 try: ${error.remediation}`);
+  }
+  return lines.join("\n");
+}
+function exitCodeFor(error) {
+  if (isSyntaurError(error) && Number.isInteger(error.code) && error.code !== 0) {
+    return error.code;
+  }
+  return 1;
+}
+function runCommand(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      console.error(formatCliError(error));
+      process.exit(exitCodeFor(error));
+    }
+  };
+}
+
+// src/commands/dashboard.ts
 function didUserSpecifyDashboardPort(argv = process.argv) {
   return argv.some((arg) => arg === "--port" || arg.startsWith("--port="));
 }
@@ -27054,7 +27192,17 @@ async function dashboardCommand(options) {
     serveStaticUi: mode === "static",
     dashboardDistPath: dashboardDist
   });
-  await server.start();
+  try {
+    await server.start();
+  } catch (err2) {
+    if (err2?.code === "EADDRINUSE") {
+      throw new SyntaurError(`Port ${port} is already in use.`, {
+        remediation: `drop --port to let Syntaur auto-pick a free port, or run "lsof -i :${port}" to find what is holding it`,
+        cause: err2
+      });
+    }
+    throw err2;
+  }
   let viteProcess = null;
   if (mode === "dev") {
     const dashboardDir = resolve45(packageRoot, "dashboard");
@@ -35901,15 +36049,30 @@ var doctorCommand = new Command4("doctor").description("Diagnose Syntaur state a
   }
   try {
     const report = await runChecks({ only: options.only });
+    const FIX_NOOP_NOTE = "--fix is reserved but has no auto-fixable remediations in v1; nothing was changed.";
     if (options.json) {
-      process.stdout.write(renderJson(report) + "\n");
+      if (options.fix) {
+        process.stdout.write(
+          JSON.stringify(
+            { ...report, fix: { fixApplied: false, note: FIX_NOOP_NOTE } },
+            null,
+            2
+          ) + "\n"
+        );
+      } else {
+        process.stdout.write(renderJson(report) + "\n");
+      }
     } else {
       process.stdout.write(renderHuman(report, { verbose: options.verbose ?? false }) + "\n");
     }
-    if (options.fix && !options.json) {
-      process.stdout.write(
-        "\nnote: --fix is reserved but has no auto-fixable remediations in v1.\n"
-      );
+    if (options.fix) {
+      if (!options.json) {
+        process.stdout.write(`
+note: ${FIX_NOOP_NOTE}
+`);
+      }
+      process.stderr.write(`note: ${FIX_NOOP_NOTE}
+`);
     }
     const hasError = report.summary.error > 0;
     process.exit(hasError ? 1 : 0);
@@ -38335,6 +38498,37 @@ init_config2();
 import { Command as Command8 } from "commander";
 init_agent_sessions();
 init_session_db();
+init_terminal_schema();
+
+// src/schedules/liveness.ts
+init_agent_sessions();
+init_session_db();
+function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err2) {
+    const code = err2.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+function isScheduledSessionLive(sessionId, launchPid) {
+  if (sessionId) {
+    let row = null;
+    try {
+      initSessionDb();
+      row = getSessionById(sessionId);
+    } catch {
+      return true;
+    }
+    if (!row) return true;
+    return computeIsLive(row);
+  }
+  if (launchPid == null) return true;
+  return isPidAlive(launchPid);
+}
 
 // src/schedules/launchd.ts
 import { execFileSync as execFileSync5 } from "child_process";
@@ -38462,6 +38656,17 @@ function parseDurationMs(input4) {
   const mult = { s: 1e3, m: 6e4, h: 36e5, d: 864e5 };
   return n * mult[(m[2] ?? "s").toLowerCase()];
 }
+function validateTerminalChoice(value) {
+  if (value == null) return null;
+  const trimmed = value.trim();
+  if (trimmed === "") return null;
+  if (!TERMINAL_CHOICES.includes(trimmed)) {
+    throw new Error(
+      `--terminal "${trimmed}" is not a known choice \u2014 expected one of ${TERMINAL_CHOICES.join("|")}`
+    );
+  }
+  return trimmed;
+}
 function buildTrigger(opts) {
   const chosen = [];
   if (opts.at) chosen.push({ kind: "at", at: opts.at });
@@ -38515,7 +38720,7 @@ scheduleCommand.command("create").description("Create a scheduled job").required
   wrap(async (opts) => {
     const config = await readConfig();
     const agentId = opts.agent ?? pickAgent(config).id;
-    const terminal = opts.terminal ?? null;
+    const terminal = validateTerminalChoice(opts.terminal);
     const unattended = !opts.interactive;
     if (unattended) assertUnattendedTerminalSupported(terminal);
     const limits = defaultLimits();
@@ -38617,15 +38822,15 @@ scheduleCommand.command("reschedule").description("Change a job's trigger and re
 );
 scheduleCommand.command("tick").description("Run one scheduler tick (the one authority): evaluate, fire due, reap").action(
   wrap(async () => {
-    const r = await runTick({ log: (m) => console.error(m) });
+    const r = await runTick({ log: (m) => console.error(m), isSessionLive: isScheduledSessionLive });
     console.log(
-      `tick: evaluated ${r.evaluated}, fired ${r.fired.length}, failed ${r.failed.length}, reaped ${r.reaped.length}, stuck ${r.stuck.length}`
+      `tick: evaluated ${r.evaluated}, fired ${r.fired.length}, failed ${r.failed.length}, reaped ${r.reaped.length}, stuck ${r.stuck.length}, completed ${r.completed.length}`
     );
   })
 );
 scheduleCommand.command("fire-due").description("Internal: fire currently-due jobs without reaping (accelerator path)").action(
   wrap(async () => {
-    const r = await runTick({ reap: false });
+    const r = await runTick({ reap: false, isSessionLive: isScheduledSessionLive });
     console.log(`fire-due: fired ${r.fired.length}, failed ${r.failed.length}`);
   })
 );
@@ -39501,14 +39706,14 @@ sessionCommand.command("resolve-id").description(
 
 // src/commands/worktree.ts
 init_git_worktree();
+import { Command as Command12 } from "commander";
+import { readFile as readFile68 } from "fs/promises";
+import { resolve as resolve95 } from "path";
 init_fs();
 init_paths();
 init_config2();
 init_timestamp();
 init_frontmatter();
-import { Command as Command12 } from "commander";
-import { readFile as readFile68 } from "fs/promises";
-import { resolve as resolve95 } from "path";
 async function readContext2(cwd) {
   const path = resolve95(cwd, ".syntaur", "context.json");
   if (!await fileExists(path)) return null;
@@ -39591,6 +39796,12 @@ async function runWorktreeRemove(options, cwd = process.cwd()) {
   }
   let branchDeleted = false;
   if (options.deleteBranch && branch) {
+    const sha = await resolveBranchSha(repository, branch);
+    if (sha) {
+      console.log(
+        `Branch "${branch}" was at ${sha}. To recover it: git -C ${repository} branch ${branch} ${sha}`
+      );
+    }
     const del = await deleteBranch(repository, branch);
     if (!del.ok) {
       throw new Error(
@@ -39650,15 +39861,31 @@ worktreeCommand.command("list").description("List the git worktrees of a reposit
 });
 worktreeCommand.command("remove").alias("prune").description(
   "Remove an assignment's git worktree and clear its workspace.* fields. Branch deletion is opt-in."
-).option("--assignment <slug>", "Assignment slug (UUID for standalone). Defaults to .syntaur/context.json").option("--project <slug>", "Project slug. Required when --assignment is given for a project-nested assignment").option("--repository <path>", "Repository root (defaults to the recorded workspace.repository)").option("--delete-branch", "Also delete the branch after removing the worktree").option("--force", "Discard a dirty/locked worktree (passes --force to git)").action(async (options) => {
+).option("--assignment <slug>", "Assignment slug (UUID for standalone). Defaults to .syntaur/context.json").option("--project <slug>", "Project slug. Required when --assignment is given for a project-nested assignment").option("--repository <path>", "Repository root (defaults to the recorded workspace.repository)").option("--delete-branch", "Also delete the branch after removing the worktree").option("--force", "Discard a dirty/locked worktree (passes --force to git)").option("--yes", "Skip the confirmation prompt for a destructive --force removal (required for non-TTY)").action(async (options) => {
   try {
+    if (options.force && !options.yes) {
+      if (!isInteractiveTerminal()) {
+        throw new SyntaurError(
+          "--force discards uncommitted work in the worktree, but there is no TTY to confirm.",
+          { remediation: "re-run with --yes to confirm the destructive removal" }
+        );
+      }
+      const confirmed = await confirmPrompt(
+        "--force will discard any uncommitted work in the worktree. Continue?",
+        false
+      );
+      if (!confirmed) {
+        console.log("Aborted. Nothing was removed.");
+        return;
+      }
+    }
     const { worktreePath, branchDeleted, workspaceCleared } = await runWorktreeRemove(options);
     console.log(`Removed worktree at ${worktreePath}`);
     if (branchDeleted) console.log("Deleted the branch.");
     if (workspaceCleared) console.log("Cleared the assignment workspace fields.");
   } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    console.error(formatCliError(error));
+    process.exit(exitCodeFor(error));
   }
 });
 
@@ -41568,358 +41795,187 @@ var captureDashDashArgv = [];
 var program = new Command20();
 var version = await readPackageVersion(import.meta.url) ?? "0.0.0";
 program.name("syntaur").description("CLI scaffolding tool for the Syntaur protocol").version(version);
-program.command("init").description("Initialize ~/.syntaur/ directory structure and config").option("--force", "Overwrite existing config file").action(async (options) => {
-  try {
+program.command("init").description("Initialize ~/.syntaur/ directory structure and config").option("--force", "Overwrite existing config file").action(
+  runCommand(async (options) => {
     await initCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("create-project").description("Create a new project with all required files").argument("<title>", "Project title").option("--slug <slug>", "Override auto-generated slug").option("--dir <path>", "Override default project directory").option("--workspace <workspace>", "Workspace for organizational grouping").action(async (title, options) => {
-  try {
+  })
+);
+program.command("create-project").description("Create a new project with all required files").argument("<title>", "Project title").option("--slug <slug>", "Override auto-generated slug").option("--dir <path>", "Override default project directory").option("--workspace <workspace>", "Workspace for organizational grouping").action(
+  runCommand(async (title, options) => {
     await createProjectCommand(title, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("create-assignment").description("Create a new assignment within a project").argument("<title>", "Assignment title").option("--project <slug>", "Target project slug (required unless --one-off)").option("--one-off", "Create a standalone assignment at ~/.syntaur/assignments/<uuid>/").option("--slug <slug>", "Override auto-generated slug (display only for standalone; folder name for project-nested)").option(
   "--priority <level>",
   "Priority level (low|medium|high|critical)",
   "medium"
-).option("--type <type>", "Assignment type (e.g. feature, bug, refactor)").option("--depends-on <slugs>", "Comma-separated dependency slugs (not allowed with --one-off)").option("--links <slugs>", "Comma-separated linked assignment slugs (projectSlug/assignmentSlug format)").option("--dir <path>", "Override default project directory (ignored for --one-off)").option("--with-todos", "Scaffold a ## Todos section in assignment.md (omitted by default; typically populated by /plan-assignment)").option("--workspace <slug>", "Workspace group slug (only valid with --one-off; mutually exclusive with --project)").option("--ready", "Create the assignment directly as ready_for_planning (skips the draft phase)").action(async (title, options) => {
-  try {
+).option("--type <type>", "Assignment type (e.g. feature, bug, refactor)").option("--depends-on <slugs>", "Comma-separated dependency slugs (not allowed with --one-off)").option("--links <slugs>", "Comma-separated linked assignment slugs (projectSlug/assignmentSlug format)").option("--dir <path>", "Override default project directory (ignored for --one-off)").option("--with-todos", "Scaffold a ## Todos section in assignment.md (omitted by default; typically populated by /plan-assignment)").option("--workspace <slug>", "Workspace group slug (only valid with --one-off; mutually exclusive with --project)").option("--ready", "Create the assignment directly as ready_for_planning (skips the draft phase)").action(
+  runCommand(async (title, options) => {
     await createAssignmentCommand(title, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("comment").description("Add a comment to an assignment (CLI-mediated, append-only)").argument("<assignment>", "Target assignment slug (with --project) or UUID (standalone)").argument("<text>", "Comment body").option("--project <slug>", "Project slug if the target is project-nested").option("--reply-to <id>", "ID of the comment this replies to").option("--type <type>", "Comment type: question | note | feedback", "note").option("--author <name>", 'Override author (default: $USER or "unknown")').option("--dir <path>", "Override default project directory").action(async (assignment, text, options) => {
-  try {
+  })
+);
+program.command("comment").description("Add a comment to an assignment (CLI-mediated, append-only)").argument("<assignment>", "Target assignment slug (with --project) or UUID (standalone)").argument("<text>", "Comment body").option("--project <slug>", "Project slug if the target is project-nested").option("--reply-to <id>", "ID of the comment this replies to").option("--type <type>", "Comment type: question | note | feedback", "note").option("--author <name>", 'Override author (default: $USER or "unknown")').option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, text, options) => {
     await commentCommand(assignment, text, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("capture").description("Capture a typed proof artifact for an assignment").argument("[target]", "Assignment slug (with --project) or UUID; falls back to .syntaur/context.json").option("--kind <type>", "Artifact kind: screenshot | video | asciinema | http | text").option("--file <path>", "Source file to ingest (forbidden for --kind=text)").option("--criterion <index>", "Optional 0-based criterion index to tag").option("--note <text>", "Optional note (required for --kind=text)").option("--project <slug>", "Project slug if the target is project-nested").option("--dir <path>", "Override default project directory").option("--interactive", "Interactive mode: drag a region (--kind=screenshot) or record a TTY (--kind=asciinema)").option("--window", "Screenshot mode: window picker (macOS only)").option("--fullscreen", "Screenshot mode: silent full-screen capture (macOS only)").option("--start", "Start ffmpeg screen recording in the background (macOS only). Stop with --stop.").option("--stop", "Stop the running ffmpeg recording and attach the mp4.").option("--device <index>", 'AVFoundation video device index for --start (default: 1). List devices: ffmpeg -f avfoundation -list_devices true -i ""').option("--fps <n>", "Frame rate for --start (default: 30)").option("--transcribe", "Auto-transcribe captured video to a <id>.transcript.md sidecar (kind=video only; requires ELEVENLABS_API_KEY + ffmpeg)").action(async (target, options) => {
-  try {
+  })
+);
+program.command("capture").description("Capture a typed proof artifact for an assignment").argument("[target]", "Assignment slug (with --project) or UUID; falls back to .syntaur/context.json").option("--kind <type>", "Artifact kind: screenshot | video | asciinema | http | text").option("--file <path>", "Source file to ingest (forbidden for --kind=text)").option("--criterion <index>", "Optional 0-based criterion index to tag").option("--note <text>", "Optional note (required for --kind=text)").option("--project <slug>", "Project slug if the target is project-nested").option("--dir <path>", "Override default project directory").option("--interactive", "Interactive mode: drag a region (--kind=screenshot) or record a TTY (--kind=asciinema)").option("--window", "Screenshot mode: window picker (macOS only)").option("--fullscreen", "Screenshot mode: silent full-screen capture (macOS only)").option("--start", "Start ffmpeg screen recording in the background (macOS only). Stop with --stop.").option("--stop", "Stop the running ffmpeg recording and attach the mp4.").option("--device <index>", 'AVFoundation video device index for --start (default: 1). List devices: ffmpeg -f avfoundation -list_devices true -i ""').option("--fps <n>", "Frame rate for --start (default: 30)").option("--transcribe", "Auto-transcribe captured video to a <id>.transcript.md sidecar (kind=video only; requires ELEVENLABS_API_KEY + ffmpeg)").action(
+  runCommand(async (target, options) => {
     await captureCommand(target, {
       ...options,
       commandArgv: captureDashDashArgv
     });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("request").description("Append a todo to another assignment (cross-assignment work request)").argument("<target>", "Target assignment slug (with --project) or UUID (standalone)").argument("<text>", "Todo text").option("--project <slug>", "Project slug if the target is project-nested").option("--from <source>", "Source assignment (default: $SYNTAUR_ASSIGNMENT)").option("--dir <path>", "Override default project directory").action(async (target, text, options) => {
-  try {
+  })
+);
+program.command("request").description("Append a todo to another assignment (cross-assignment work request)").argument("<target>", "Target assignment slug (with --project) or UUID (standalone)").argument("<text>", "Todo text").option("--project <slug>", "Project slug if the target is project-nested").option("--from <source>", "Source assignment (default: $SYNTAUR_ASSIGNMENT)").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (target, text, options) => {
     await requestCommand(target, text, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("dashboard").description("Start the local Syntaur dashboard web UI").option("--port <number>", "Port to run the dashboard on", "4800").option("--dev", "Run the dashboard with the Vite dev server", false).option("--server-only", "Run only the API server without any UI", false).option("--api-only", "Deprecated alias for --server-only", false).option("--no-open", "Do not automatically open the browser").action(async (options) => {
-  try {
+  })
+);
+program.command("dashboard").description("Start the local Syntaur dashboard web UI").option("--port <number>", "Port to run the dashboard on", "4800").option("--dev", "Run the dashboard with the Vite dev server", false).option("--server-only", "Run only the API server without any UI", false).option("--api-only", "Deprecated alias for --server-only", false).option("--no-open", "Do not automatically open the browser").action(
+  runCommand(async (options) => {
     const autoPort = !didUserSpecifyDashboardPort();
     await dashboardCommand({
       ...options,
       autoPort
     });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("assign").description("Set the assignee on an assignment").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name to assign").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("assign").description("Set the assignee on an assignment").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name to assign").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await assignCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("unassign").description("Clear the assignee on an assignment (inverse of assign)").argument("<assignment>", "Assignment slug (UUID for standalone)").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("unassign").description("Clear the assignee on an assignment (inverse of assign)").argument("<assignment>", "Assignment slug (UUID for standalone)").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await unassignCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("start").description("Assert implementation has started (alias of implement under derived status)").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("start").description("Assert implementation has started (alias of implement under derived status)").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await startCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("archive").description("Archive an assignment or a project (hidden from normal views; restorable)").argument("<target>", "Assignment slug/UUID, or a project slug").option("--project <slug>", "Resolve <target> as an assignment within this project").option("--reason <text>", "Optional reason recorded with the archive").option("--dir <path>", "Override default project directory").action(async (target, options) => {
-  try {
+  })
+);
+program.command("archive").description("Archive an assignment or a project (hidden from normal views; restorable)").argument("<target>", "Assignment slug/UUID, or a project slug").option("--project <slug>", "Resolve <target> as an assignment within this project").option("--reason <text>", "Optional reason recorded with the archive").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (target, options) => {
     await archiveCommand(target, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("restore").description("Restore an archived assignment or project (preserves prior status)").argument("<target>", "Assignment slug/UUID, or a project slug").option("--project <slug>", "Resolve <target> as an assignment within this project").option("--dir <path>", "Override default project directory").action(async (target, options) => {
-  try {
+  })
+);
+program.command("restore").description("Restore an archived assignment or project (preserves prior status)").argument("<target>", "Assignment slug/UUID, or a project slug").option("--project <slug>", "Resolve <target> as an assignment within this project").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (target, options) => {
     await restoreCommand(target, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("shape").description("Recompute derived status; ready_for_planning follows once objective + ACs are real").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("shape").description("Recompute derived status; ready_for_planning follows once objective + ACs are real").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await shapeCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("plan-ready").description("Approve the latest plan revision (file+digest bound); ready_to_implement derives from it").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("plan-ready").description("Approve the latest plan revision (file+digest bound); ready_to_implement derives from it").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await planReadyCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("migrate-statuses").description("Suggest pending -> ready_for_planning promotions for fleshed-out assignments (use --apply to write)").option("--dir <path>", "Override default project directory").option("--apply", "Apply the migration (default: dry-run)").action(async (options) => {
-  try {
+  })
+);
+program.command("migrate-statuses").description("Suggest pending -> ready_for_planning promotions for fleshed-out assignments (use --apply to write)").option("--dir <path>", "Override default project directory").option("--apply", "Apply the migration (default: dry-run)").action(
+  runCommand(async (options) => {
     await migrateStatusesCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("migrate-status-history").description("Seed a synthetic statusHistory entry on assignments that lack one (use --apply to write)").option("--dir <path>", "Override default project directory").option("--apply", "Apply the migration (default: dry-run)").action(async (options) => {
-  try {
+  })
+);
+program.command("migrate-status-history").description("Seed a synthetic statusHistory entry on assignments that lack one (use --apply to write)").option("--dir <path>", "Override default project directory").option("--apply", "Apply the migration (default: dry-run)").action(
+  runCommand(async (options) => {
     await migrateStatusHistoryCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("migrate-derive").description("One-time migration to derived status: seed facts from current statuses, re-derive all, print a divergence report").option("--dir <path>", "Override default project directory").option("--dry-run", "Report what would change without writing").action(async (options) => {
-  try {
+  })
+);
+program.command("migrate-derive").description("One-time migration to derived status: seed facts from current statuses, re-derive all, print a divergence report").option("--dir <path>", "Override default project directory").option("--dry-run", "Report what would change without writing").action(
+  runCommand(async (options) => {
     await migrateDeriveCommand(options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("park").description("Park an assignment (intentional withhold); disposition derives to parked").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--reason <text>", "Why it is parked (recorded in history)").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("park").description("Park an assignment (intentional withhold); disposition derives to parked").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--reason <text>", "Why it is parked (recorded in history)").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await parkCommand(assignment, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("unpark").description("Unpark an assignment; status re-derives from facts").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("unpark").description("Unpark an assignment; status re-derives from facts").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await unparkCommand(assignment, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("request-review").description("Request review (sets reviewRequested); the review phase derives from it").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--clear", "Clear the review request instead").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("request-review").description("Request review (sets reviewRequested); the review phase derives from it").argument("<assignment>", "Assignment slug or standalone UUID").option("--project <slug>", "Target project slug").option("--clear", "Clear the review request instead").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await requestReviewCommand(assignment, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
+  })
+);
 var factCommand = program.command("fact").description("Manage custom asserted facts declared under statuses.facts");
-factCommand.command("set").description("Set a declared custom fact (bool/number); status re-derives from it").argument("<assignment>", "Assignment slug or standalone UUID").argument("<name>", "Declared fact name (statuses.facts)").argument("<value>", "Value (bool: true/false; number: any finite number)").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(async (assignment, name, value, options) => {
-  try {
+factCommand.command("set").description("Set a declared custom fact (bool/number); status re-derives from it").argument("<assignment>", "Assignment slug or standalone UUID").argument("<name>", "Declared fact name (statuses.facts)").argument("<value>", "Value (bool: true/false; number: any finite number)").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, name, value, options) => {
     await factSetCommand(assignment, name, value, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("attest").description("Record an attestation (agent reviewed a revision with a verdict); revision-bound").argument("<assignment>", "Assignment slug or standalone UUID").argument("<fact>", "Declared attestation fact name (statuses.facts)").option("--verdict <verdict>", "approved | changes-requested", "approved").option("--note <text>", "Optional note recorded on the attestation").option("--agent <id>", "Acting agent id (else the bound session, else human)").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, fact, options) => {
-  try {
+  })
+);
+program.command("attest").description("Record an attestation (agent reviewed a revision with a verdict); revision-bound").argument("<assignment>", "Assignment slug or standalone UUID").argument("<fact>", "Declared attestation fact name (statuses.facts)").option("--verdict <verdict>", "approved | changes-requested", "approved").option("--note <text>", "Optional note recorded on the attestation").option("--agent <id>", "Acting agent id (else the bound session, else human)").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, fact, options) => {
     await attestCommand(assignment, fact, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("recompute").description("Recompute derived status for one assignment or --all (headless reconcile)").argument("[assignment]", "Assignment slug or standalone UUID").option("--all", "Recompute every assignment (projects + standalone)").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("recompute").description("Recompute derived status for one assignment or --all (headless reconcile)").argument("[assignment]", "Assignment slug or standalone UUID").option("--all", "Recompute every assignment (projects + standalone)").option("--project <slug>", "Target project slug").option("--agent <name>", "Acting agent id").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await recomputeCommand(assignment, options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("implement").description("Assert implementation has started; status derives to in_progress when the plan is approved").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("implement").description("Assert implementation has started; status derives to in_progress when the plan is approved").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--agent <name>", "Agent name (sets assignee if not already set)").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await implementCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("complete").description("Transition an assignment to completed").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("complete").description("Transition an assignment to completed").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await completeCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("block").description("Assert a blocker (sets blockedReason); disposition derives to blocked").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--reason <text>", "Reason for blocking").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("block").description("Assert a blocker (sets blockedReason); disposition derives to blocked").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--reason <text>", "Reason for blocking").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await blockCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("unblock").description("Clear the blocker; status re-derives from facts").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("unblock").description("Clear the blocker; status re-derives from facts").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await unblockCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("review").description("Request review; the review phase derives from it (or from all ACs checked)").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("review").description("Request review; the review phase derives from it (or from all ACs checked)").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await reviewCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("fail").description("Transition an assignment to failed").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("fail").description("Transition an assignment to failed").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await failCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("reopen").description("Reopen a completed or failed assignment").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(async (assignment, options) => {
-  try {
+  })
+);
+program.command("reopen").description("Reopen a completed or failed assignment").argument("<assignment>", "Assignment slug").option("--project <slug>", "Target project slug").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (assignment, options) => {
     await reopenCommand(assignment, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("setup").description("Initialize Syntaur and optionally install plugins or launch the dashboard").option("--yes", "Skip interactive prompts and perform only the requested flags").option("--claude", "Install the Claude Code plugin").option("--codex", "Install the Codex plugin").option("--claude-dir <path>", "Install the Claude Code plugin at a specific path").option("--codex-dir <path>", "Install the Codex plugin at a specific path").option("--codex-marketplace-path <path>", "Write the Codex marketplace entry to a specific file").option("--dashboard", "Launch the dashboard after setup").option("--target <id>", "Install Syntaur into a cross-agent target. Built-in ids: pi, hermes, openclaw, cursor, opencode (plus any user descriptors in ~/.syntaur/targets/). Comma-separated for several").option("--agent <id>", "Alias for --target; cross-agent target id(s) to install into").option("--force", "Overwrite existing cross-agent protocol files / skills").option("--dry-run", "Print the cross-agent install actions without writing anything").action(async (options) => {
-  try {
+  })
+);
+program.command("setup").description("Initialize Syntaur and optionally install plugins or launch the dashboard").option("--yes", "Skip interactive prompts and perform only the requested flags").option("--claude", "Install the Claude Code plugin").option("--codex", "Install the Codex plugin").option("--claude-dir <path>", "Install the Claude Code plugin at a specific path").option("--codex-dir <path>", "Install the Codex plugin at a specific path").option("--codex-marketplace-path <path>", "Write the Codex marketplace entry to a specific file").option("--dashboard", "Launch the dashboard after setup").option("--target <id>", "Install Syntaur into a cross-agent target. Built-in ids: pi, hermes, openclaw, cursor, opencode (plus any user descriptors in ~/.syntaur/targets/). Comma-separated for several").option("--agent <id>", "Alias for --target; cross-agent target id(s) to install into").option("--force", "Overwrite existing cross-agent protocol files / skills").option("--dry-run", "Print the cross-agent install actions without writing anything").action(
+  runCommand(async (options) => {
     await setupCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("install-plugin").description("Install the Syntaur Claude Code plugin").option("--force", "Overwrite an existing Syntaur-managed install").option("--target-dir <path>", "Install the plugin at a specific directory").option("--link", "Use a symlink instead of copying files (repo-local dev only)").option("--force-skills", "Overwrite user-edited skills in ~/.claude/skills").option("--skip-skills", "Do not install protocol skills into ~/.claude/skills").option("--enable", "Enable the plugin in ~/.claude/settings.json after install").action(async (options) => {
-  try {
+  })
+);
+program.command("install-plugin").description("Install the Syntaur Claude Code plugin").option("--force", "Overwrite an existing Syntaur-managed install").option("--target-dir <path>", "Install the plugin at a specific directory").option("--link", "Use a symlink instead of copying files (repo-local dev only)").option("--force-skills", "Overwrite user-edited skills in ~/.claude/skills").option("--skip-skills", "Do not install protocol skills into ~/.claude/skills").option("--enable", "Enable the plugin in ~/.claude/settings.json after install").action(
+  runCommand(async (options) => {
     await installPluginCommand({ ...options, promptForTarget: true });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("update").alias("upgrade").description("Self-update the global syntaur package and refresh the plugin/skills").option("--version <v>", "Update to a specific version instead of latest").option("--check", "Report whether an update is available; apply nothing").option("--dry-run", "Print what would happen without changing anything").option("--skip-refresh", "Update the package only; do not refresh the plugin/skills").option("--force-skills", "Overwrite user-edited skills during the refresh").option("--enable", "Enable the plugin in settings.json during the refresh").option("--pm <name>", "Override package-manager detection (npm|pnpm|yarn|bun)").option("--yes", "Assume yes for any confirmation (non-interactive)").action(async (options) => {
-  try {
+  })
+);
+program.command("update").alias("upgrade").description("Self-update the global syntaur package and refresh the plugin/skills").option("--version <v>", "Update to a specific version instead of latest").option("--check", "Report whether an update is available; apply nothing").option("--dry-run", "Print what would happen without changing anything").option("--skip-refresh", "Update the package only; do not refresh the plugin/skills").option("--force-skills", "Overwrite user-edited skills during the refresh").option("--enable", "Enable the plugin in settings.json during the refresh").option("--pm <name>", "Override package-manager detection (npm|pnpm|yarn|bun)").option("--yes", "Assume yes for any confirmation (non-interactive)").action(
+  runCommand(async (options) => {
     await updateCommand({ ...options, scriptUrl: import.meta.url });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("install-statusline").description(
   "Install the syntaur statusLine for Claude Code. Augments ~/.claude/settings.json; wraps any existing script by default."
-).option("--mode <mode>", "replace | wrap | skip | ask (default: ask, wrap in non-TTY)", "ask").option("--link", "Symlink the installed script to the package source (dev mode)").action(async (options) => {
-  try {
+).option("--mode <mode>", "replace | wrap | skip | ask (default: ask, wrap in non-TTY)", "ask").option("--link", "Symlink the installed script to the package source (dev mode)").action(
+  runCommand(async (options) => {
     const rawMode = (options.mode ?? "ask").toLowerCase();
     const valid = ["replace", "wrap", "skip", "ask"];
     if (!valid.includes(rawMode)) {
@@ -41931,21 +41987,15 @@ program.command("install-statusline").description(
       mode: rawMode,
       link: options.link
     });
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("uninstall-statusline").description(
   "Remove the syntaur statusLine. Restores the previously configured command from backup if present."
-).option("--keep-script", "Leave ~/.syntaur/statusline.sh on disk (only edit settings.json)").action(async (options) => {
-  try {
+).option("--keep-script", "Leave ~/.syntaur/statusline.sh on disk (only edit settings.json)").action(
+  runCommand(async (options) => {
     await uninstallStatuslineCommand({ keepScript: options.keepScript });
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("configure-statusline").description(
   "Configure which segments (git, assignment, session, model, ctx, cwd, wrap) appear in the syntaur statusLine and in what order."
 ).option(
@@ -41954,55 +42004,31 @@ program.command("configure-statusline").description(
 ).option(
   "--segments <list>",
   'Comma-separated segment list, e.g. "git,assignment,session,model,ctx".'
-).option("--separator <string>", 'Segment separator (default " \xB7 ")').option("--wrap <path>", 'Path to an external statusline script to compose as a "wrap" segment').option("--preview", "Print the resolved config and a preview line without writing").action(async (options) => {
-  try {
+).option("--separator <string>", 'Segment separator (default " \xB7 ")').option("--wrap <path>", 'Path to an external statusline script to compose as a "wrap" segment').option("--preview", "Print the resolved config and a preview line without writing").action(
+  runCommand(async (options) => {
     await configureStatuslineCommand(options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("uninstall-skills").description("Remove Syntaur protocol skills from ~/.claude/skills and/or ~/.codex/skills").option("--claude", "Remove from ~/.claude/skills").option("--codex", "Remove from ~/.codex/skills").option("--all", "Remove from both").action(async (options) => {
-  try {
+  })
+);
+program.command("uninstall-skills").description("Remove Syntaur protocol skills from ~/.claude/skills and/or ~/.codex/skills").option("--claude", "Remove from ~/.claude/skills").option("--codex", "Remove from ~/.codex/skills").option("--all", "Remove from both").action(
+  runCommand(async (options) => {
     await uninstallSkillsCommand(options);
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  }
-});
-program.command("install-codex-plugin").description("Install the Syntaur Codex plugin and marketplace entry").option("--force", "Overwrite an existing Syntaur-managed install").option("--target-dir <path>", "Install the plugin at a specific directory").option("--marketplace-path <path>", "Write the marketplace entry to a specific file").option("--link", "Use a symlink instead of copying files (repo-local dev only)").option("--force-skills", "Overwrite user-edited skills in ~/.codex/skills").option("--skip-skills", "Do not install protocol skills into ~/.codex/skills").action(async (options) => {
-  try {
+  })
+);
+program.command("install-codex-plugin").description("Install the Syntaur Codex plugin and marketplace entry").option("--force", "Overwrite an existing Syntaur-managed install").option("--target-dir <path>", "Install the plugin at a specific directory").option("--marketplace-path <path>", "Write the marketplace entry to a specific file").option("--link", "Use a symlink instead of copying files (repo-local dev only)").option("--force-skills", "Overwrite user-edited skills in ~/.codex/skills").option("--skip-skills", "Do not install protocol skills into ~/.codex/skills").action(
+  runCommand(async (options) => {
     await installCodexPluginCommand({ ...options, promptForTarget: true });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("uninstall").description("Remove Syntaur integrations and optionally local data").option("--claude", "Remove only the Claude Code plugin").option("--codex", "Remove only the Codex plugin and marketplace entry").option("--data", "Remove ~/.syntaur data").option("--all", "Remove plugins and ~/.syntaur data").option("--yes", "Skip confirmation prompts").action(async (options) => {
-  try {
+  })
+);
+program.command("uninstall").description("Remove Syntaur integrations and optionally local data").option("--claude", "Remove only the Claude Code plugin").option("--codex", "Remove only the Codex plugin and marketplace entry").option("--data", "Remove ~/.syntaur data").option("--all", "Remove plugins and ~/.syntaur data").option("--yes", "Skip confirmation prompts").action(
+  runCommand(async (options) => {
     await uninstallCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("setup-adapter").description("Generate adapter instruction files for a framework in the current directory").argument("<framework>", "Target framework: built-in ids cursor, codex, opencode, pi, openclaw, hermes (plus any user descriptor with an instructions adapter in ~/.syntaur/targets/)").option("--project <slug>", "Target project slug (required)").option("--assignment <slug>", "Target assignment slug (required)").option("--force", "Overwrite existing adapter files").option("--dir <path>", "Override default project directory").action(async (framework, options) => {
-  try {
+  })
+);
+program.command("setup-adapter").description("Generate adapter instruction files for a framework in the current directory").argument("<framework>", "Target framework: built-in ids cursor, codex, opencode, pi, openclaw, hermes (plus any user descriptor with an instructions adapter in ~/.syntaur/targets/)").option("--project <slug>", "Target project slug (required)").option("--assignment <slug>", "Target assignment slug (required)").option("--force", "Overwrite existing adapter files").option("--dir <path>", "Override default project directory").action(
+  runCommand(async (framework, options) => {
     await setupAdapterCommand(framework, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("track-session").description("Register an agent session (optionally linked to a project/assignment)").option("--project <slug>", "Target project slug").option("--assignment <slug>", "Assignment slug").option("--agent <name>", "Agent name, e.g. claude, codex, cursor (required)").option(
   "--session-id <id>",
   "Session id from the agent runtime (real, not generated). Defaults to self-resolution via env / process-tree markers / transcript scan \u2014 pass explicitly only when registering a session other than the calling one."
@@ -42019,17 +42045,11 @@ program.command("track-session").description("Register an agent session (optiona
     }
     return n;
   }
-).action(async (options) => {
-  try {
+).action(
+  runCommand(async (options) => {
     await trackSessionCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
+  })
+);
 program.command("url <url>").description(
   "Open an assignment or session in the configured terminal + agent (handles syntaur:// deep links)"
 ).option(
@@ -42053,83 +42073,41 @@ program.command("install-url-handler").description(
     process.exit(1);
   }
 });
-program.command("browse").description("Interactive TUI browser for projects and assignments").option("--agent <id>", "Bypass the agent picker and launch the given configured agent id").option("--no-worktree-prompt", "Skip the prompt to create a worktree when one is missing").action(async (options) => {
-  try {
+program.command("browse").description("Interactive TUI browser for projects and assignments").option("--agent <id>", "Bypass the agent picker and launch the given configured agent id").option("--no-worktree-prompt", "Skip the prompt to create a worktree when one is missing").action(
+  runCommand(async (options) => {
     await browseCommand(options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("create-playbook").description("Create a new playbook").argument("<name>", "Playbook name").option("--slug <slug>", "Override auto-generated slug").option("--description <desc>", "Playbook description").action(async (name, options) => {
-  try {
+  })
+);
+program.command("create-playbook").description("Create a new playbook").argument("<name>", "Playbook name").option("--slug <slug>", "Override auto-generated slug").option("--description <desc>", "Playbook description").action(
+  runCommand(async (name, options) => {
     await createPlaybookCommand(name, options);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("list-playbooks").description("List playbooks (disabled playbooks are excluded unless --all is passed)").option("--all", "Include disabled playbooks").action(async (options) => {
-  try {
+  })
+);
+program.command("list-playbooks").description("List playbooks (disabled playbooks are excluded unless --all is passed)").option("--all", "Include disabled playbooks").action(
+  runCommand(async (options) => {
     await listPlaybooksCommand({ all: Boolean(options?.all) });
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("enable-playbook").description("Enable a previously-disabled playbook").argument("<slug>", "Playbook slug").action(async (slug) => {
-  try {
+  })
+);
+program.command("enable-playbook").description("Enable a previously-disabled playbook").argument("<slug>", "Playbook slug").action(
+  runCommand(async (slug) => {
     await enablePlaybookCommand(slug);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("disable-playbook").description("Disable a playbook so agents no longer load it").argument("<slug>", "Playbook slug").action(async (slug) => {
-  try {
+  })
+);
+program.command("disable-playbook").description("Disable a playbook so agents no longer load it").argument("<slug>", "Playbook slug").action(
+  runCommand(async (slug) => {
     await disablePlaybookCommand(slug);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("delete-playbook").description("Delete a playbook from disk and regenerate the manifest").argument("<slug>", "Playbook slug").action(async (slug) => {
-  try {
+  })
+);
+program.command("delete-playbook").description("Delete a playbook from disk and regenerate the manifest").argument("<slug>", "Playbook slug").action(
+  runCommand(async (slug) => {
     await deletePlaybookCommand(slug);
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
-program.command("regen-playbook-manifest").description("Rebuild ~/.syntaur/playbooks/manifest.md from current playbook files").action(async () => {
-  try {
+  })
+);
+program.command("regen-playbook-manifest").description("Rebuild ~/.syntaur/playbooks/manifest.md from current playbook files").action(
+  runCommand(async () => {
     await regenPlaybookManifestCommand();
-  } catch (error) {
-    console.error(
-      "Error:",
-      error instanceof Error ? error.message : String(error)
-    );
-    process.exit(1);
-  }
-});
+  })
+);
 program.addCommand(todoCommand);
 program.addCommand(backupCommand);
 program.addCommand(doctorCommand);
@@ -42148,6 +42126,21 @@ program.addCommand(progressCommand);
 program.addCommand(leaseCommand);
 program.addCommand(scheduleCommand);
 program.addCommand(usageCommand);
+program.addHelpText(
+  "after",
+  `
+Common workflow:
+  $ syntaur setup                                  Initialize Syntaur (plugins, dashboard)
+  $ syntaur create-project "My App"                Start a new project
+  $ syntaur create-assignment --project my-app "Add login"   Add a task to a project
+  $ syntaur browse                                 Interactive TUI: pick & launch work
+  $ syntaur dashboard                              Open the local web dashboard
+  $ syntaur doctor                                 Diagnose Syntaur state & suggested fixes
+
+Run 'syntaur <command> --help' for command-specific options.
+Migration/internal commands (migrate-*, regen-playbook-manifest) are advanced; most
+workflows never need them.`
+);
 if (process.argv.length <= 2) {
   process.argv.push(await getDefaultCommandName());
 }