@mu-crew/mu 2.0.0 → 3.1.0

package/dist/index.js

@@ -1762,6 +1762,7 @@ var CAPTURED_COLUMNS = {
     "local_id",
     "title",
     "status",
+    "substate",
     "impact",
     "effort_days",
     "owner_id",
@@ -1872,6 +1873,48 @@ function installCapture(db) {
   db.exec(CAPTURE_TRIGGER_DDL);
 }
 
+// src/tasks/status.ts
+var TASK_STATUSES = ["OPEN", "IN_PROGRESS", "CLOSED"];
+function isTaskStatus(s) {
+  return TASK_STATUSES.includes(s);
+}
+var TASK_STATUS_LIST = TASK_STATUSES.join(" | ");
+var TASK_SUBSTATES = {
+  OPEN: ["todo", "parked"],
+  IN_PROGRESS: ["active"],
+  CLOSED: ["done", "rejected", "wontfix", "duplicate", "superseded"]
+};
+var DEFAULT_SUBSTATE = { OPEN: "todo", IN_PROGRESS: "active", CLOSED: "done" };
+var TASK_SUBSTATE_ROWS = TASK_STATUSES.flatMap(
+  (status) => TASK_SUBSTATES[status].map(
+    (substate) => [status, substate, substate === DEFAULT_SUBSTATE[status] ? 1 : 0]
+  )
+);
+function isValidPair(status, substate) {
+  if (!isTaskStatus(status)) return false;
+  return TASK_SUBSTATES[status].includes(substate);
+}
+var LEGACY_STATUS_PAIRS = {
+  REJECTED: { status: "CLOSED", substate: "rejected" },
+  DEFERRED: { status: "OPEN", substate: "parked" }
+};
+function mapLegacyStatus(value) {
+  const pair = LEGACY_STATUS_PAIRS[value];
+  return pair ? { ...pair } : null;
+}
+function resolvePair(status, substate) {
+  const legacy = mapLegacyStatus(status);
+  if (legacy) return legacy;
+  if (!isTaskStatus(status)) return null;
+  if (typeof substate === "string" && isValidPair(status, substate)) {
+    return { status, substate };
+  }
+  return { status, substate: DEFAULT_SUBSTATE[status] };
+}
+function formatPair(pair) {
+  return pair.substate === DEFAULT_SUBSTATE[pair.status] ? pair.status : `${pair.status}/${pair.substate}`;
+}
+
 // src/db.ts
 function defaultStateDir() {
   if (process.env.MU_STATE_DIR) return process.env.MU_STATE_DIR;
@@ -1892,6 +1935,13 @@ function openDb(options = {}) {
     db.pragma("foreign_keys = ON");
     db.pragma("busy_timeout = 5000");
     const detectedVersion = detectExistingSchemaVersion(db);
+    if (detectedVersion !== null && detectedVersion > CURRENT_SCHEMA_VERSION) {
+      try {
+        db.close();
+      } catch {
+      }
+      throw new SchemaTooNewError(detectedVersion, CURRENT_SCHEMA_VERSION);
+    }
     if (detectedVersion !== null && detectedVersion < MIN_ACCEPTED_SCHEMA_VERSION) {
       try {
         db.close();
@@ -1967,7 +2017,7 @@ var SchemaTooOldError = class extends Error {
         command: `mv "\${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}" "\${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}.old"`
       },
       {
-        intent: `Migrate the preserved DB into a fresh v${this.requiredVersion} file`,
+        intent: `Migrate the old DB into a fresh v${this.requiredVersion} DB`,
         command: `npx tsx scripts/migrate.ts "\${MU_DB_PATH:-$HOME/.local/state/mu/mu.db}.old" --out /tmp/mu-v${this.requiredVersion}.db`
       },
       {
@@ -1977,6 +2027,19 @@ var SchemaTooOldError = class extends Error {
     ];
   }
 };
+var SchemaTooNewError = class extends Error {
+  constructor(detectedVersion, supportedVersion) {
+    super(`DB is v${detectedVersion}; this mu understands up to v${supportedVersion}. Upgrade mu.`);
+    this.detectedVersion = detectedVersion;
+    this.supportedVersion = supportedVersion;
+  }
+  detectedVersion;
+  supportedVersion;
+  name = "SchemaTooNewError";
+  errorNextSteps() {
+    return [{ intent: "Check which mu is on PATH", command: "which mu && mu --version" }];
+  }
+};
 function detectExistingSchemaVersion(db) {
   const hasVersionTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'").get();
   if (hasVersionTable) {
@@ -1999,6 +2062,12 @@ function applySchema(db) {
   db.exec("BEGIN IMMEDIATE");
   try {
     db.exec(CURRENT_SCHEMA);
+    const seed = db.prepare(
+      "INSERT OR IGNORE INTO task_substates (status, substate, is_default) VALUES (?, ?, ?)"
+    );
+    for (const [status, substate, isDefault] of TASK_SUBSTATE_ROWS) {
+      seed.run(status, substate, isDefault);
+    }
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -2009,8 +2078,8 @@ function applySchema(db) {
     CURRENT_SCHEMA_VERSION
   );
 }
-var CURRENT_SCHEMA_VERSION = 10;
-var MIN_ACCEPTED_SCHEMA_VERSION = 10;
+var CURRENT_SCHEMA_VERSION = 11;
+var MIN_ACCEPTED_SCHEMA_VERSION = 11;
 var EXPECTED_TABLES = [
   "agents",
   "machine_identity",
@@ -2019,6 +2088,7 @@ var EXPECTED_TABLES = [
   "sync_peers",
   "task_edges",
   "task_notes",
+  "task_substates",
   "tasks",
   "vcs_workspaces",
   "workstreams"
@@ -2032,6 +2102,7 @@ var MACHINE_LOCAL_TABLES = [
   "ops",
   "schema_version",
   "sync_peers",
+  "task_substates",
   "vcs_workspaces"
 ];
 var READY_VIEW_SQL = `
@@ -2040,6 +2111,7 @@ CREATE VIEW ready AS
   SELECT t.*
     FROM tasks t
    WHERE t.status = 'OPEN'
+     AND t.substate <> 'parked'
      AND NOT EXISTS (
        SELECT 1
          FROM task_edges e
@@ -2135,6 +2207,19 @@ CREATE TABLE IF NOT EXISTS agents (
 CREATE INDEX IF NOT EXISTS idx_agents_workstream ON agents (workstream_id);
 CREATE INDEX IF NOT EXISTS idx_agents_status ON agents (status);
 
+-- task_substates: the legal (status, substate) pairs. Seeded from
+-- TASK_SUBSTATE_ROWS (src/tasks/status.ts) by applySchema; exactly one
+-- default per status.
+CREATE TABLE IF NOT EXISTS task_substates (
+  status     TEXT NOT NULL,
+  substate   TEXT NOT NULL,
+  is_default INTEGER NOT NULL DEFAULT 0 CHECK (is_default IN (0, 1)),
+  PRIMARY KEY (status, substate)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_task_substates_one_default
+  ON task_substates (status) WHERE is_default = 1;
+
 -- tasks: per-workstream unique on local_id (TRULY local now \u2014
 -- different workstreams may reuse the same local_id).
 CREATE TABLE IF NOT EXISTS tasks (
@@ -2144,6 +2229,9 @@ CREATE TABLE IF NOT EXISTS tasks (
   title         TEXT NOT NULL,
   status        TEXT NOT NULL DEFAULT 'OPEN',
   -- OPEN | IN_PROGRESS | CLOSED \u2014 see VOCABULARY.md.
+  substate      TEXT NOT NULL,
+  -- Qualifies status. No DEFAULT on purpose: a writer that forgets it
+  -- must fail loudly rather than silently pick one.
   impact        INTEGER NOT NULL,
   effort_days   REAL NOT NULL,
   owner_id      INTEGER REFERENCES agents (id) ON DELETE SET NULL,
@@ -2152,7 +2240,8 @@ CREATE TABLE IF NOT EXISTS tasks (
   UNIQUE (workstream_id, local_id),
   CHECK (impact BETWEEN 1 AND 100),
   CHECK (effort_days > 0),
-  CHECK (status IN ('OPEN', 'IN_PROGRESS', 'CLOSED'))
+  FOREIGN KEY (status, substate) REFERENCES task_substates (status, substate)
+    DEFERRABLE INITIALLY DEFERRED
 );
 
 CREATE INDEX IF NOT EXISTS idx_tasks_workstream ON tasks (workstream_id);
@@ -2300,6 +2389,9 @@ var GLYPH = {
   /** Task is blocked by an incoming edge. */
   blocked: "\uF0C1",
   // nf-fa-link (chain)
+  /** Task is parked (OPEN/parked): open, but set aside on purpose. */
+  parked: "\uF04C",
+  // nf-fa-pause
   /** Track whose roots merged (diamond dependency). */
   merge: "\uF074",
   // nf-fa-random
@@ -4733,6 +4825,7 @@ var SELECT_TASK_COLS = `
   ws.name AS workstream,
   t.title AS title,
   t.status AS status,
+  t.substate AS substate,
   t.impact AS impact,
   t.effort_days AS effort_days,
   ag.name AS owner,
@@ -4755,6 +4848,7 @@ function rowFromDb3(row) {
     workstreamName: row.workstream,
     title: row.title,
     status: row.status,
+    substate: row.substate,
     impact: row.impact,
     effortDays: row.effort_days,
     ownerName: row.owner,
@@ -4797,6 +4891,10 @@ function getTask(db, localId, workstream) {
   ).get(wsId, localId);
   return row ? rowFromDb3(row) : void 0;
 }
+function asList(v) {
+  if (v === void 0) return void 0;
+  return typeof v === "string" ? [v] : v;
+}
 function listTasks(db, workstream, opts = {}) {
   const statuses = opts.status === void 0 ? void 0 : Array.isArray(opts.status) ? opts.status : [opts.status];
   const where = [];
@@ -4811,6 +4909,11 @@ function listTasks(db, workstream, opts = {}) {
     where.push(`t.status IN (${statuses.map(() => "?").join(", ")})`);
     params.push(...statuses);
   }
+  const substates = asList(opts.substate);
+  if (substates !== void 0 && substates.length > 0) {
+    where.push(`t.substate IN (${substates.map(() => "?").join(", ")})`);
+    params.push(...substates);
+  }
   const sql = where.length === 0 ? `SELECT ${SELECT_TASK_COLS} ${TASK_FROM_JOIN} ORDER BY t.local_id` : `SELECT ${SELECT_TASK_COLS} ${TASK_FROM_JOIN} WHERE ${where.join(" AND ")} ORDER BY t.local_id`;
   const rows = db.prepare(sql).all(...params);
   return rows.map(rowFromDb3);
@@ -4826,6 +4929,7 @@ var SELECT_VIEW_COLS = `
   ws.name AS workstream,
   v.title AS title,
   v.status AS status,
+  v.substate AS substate,
   v.impact AS impact,
   v.effort_days AS effort_days,
   ag.name AS owner,
@@ -4842,6 +4946,11 @@ function listReady(db, workstream, opts = {}) {
     where.push(`v.status IN (${statuses.map(() => "?").join(", ")})`);
     params.push(...statuses);
   }
+  const substates = asList(opts.substate);
+  if (substates !== void 0 && substates.length > 0) {
+    where.push(`v.substate IN (${substates.map(() => "?").join(", ")})`);
+    params.push(...substates);
+  }
   const rows = db.prepare(
     `SELECT ${SELECT_VIEW_COLS} ${VIEW_FROM_JOIN("ready")} WHERE ${where.join(" AND ")} ORDER BY v.local_id`
   ).all(...params);
@@ -5202,6 +5311,84 @@ var CrossWorkstreamEdgeError = class extends Error {
     ];
   }
 };
+var SubstateReasonRequiredError = class extends Error {
+  constructor(verb, substate, taskId) {
+    super(
+      verb === "close" ? `closing ${taskId} as ${substate} needs a reason (--why "...")` : `parking ${taskId} needs a reason (--why "...")`
+    );
+    this.verb = verb;
+    this.substate = substate;
+    this.taskId = taskId;
+  }
+  verb;
+  substate;
+  taskId;
+  name = "SubstateReasonRequiredError";
+  errorNextSteps() {
+    const cmd = this.verb === "close" ? `mu task close ${this.taskId} --as ${this.substate} --why "<reason>"` : `mu task park ${this.taskId} --why "<reason>"`;
+    return [{ intent: "Retry with a reason", command: cmd }];
+  }
+};
+var TaskParkStateError = class extends Error {
+  constructor(taskId, status, workstream) {
+    super(
+      status === "IN_PROGRESS" ? `cannot park ${taskId}: it is IN_PROGRESS (release it first)` : `cannot park ${taskId}: it is CLOSED (open it first)`
+    );
+    this.taskId = taskId;
+    this.status = status;
+    this.workstream = workstream;
+  }
+  taskId;
+  status;
+  workstream;
+  name = "TaskParkStateError";
+  errorNextSteps() {
+    const ws = this.workstream;
+    const first = this.status === "IN_PROGRESS" ? { intent: "Release the claim first", command: `mu task release ${this.taskId} -w ${ws}` } : { intent: "Reopen the task first", command: `mu task open ${this.taskId} -w ${ws}` };
+    return [
+      first,
+      {
+        intent: "Then park it",
+        command: `mu task park ${this.taskId} --why "<reason>" -w ${ws}`
+      }
+    ];
+  }
+};
+var TaskParkedError = class extends Error {
+  constructor(taskId, workstream) {
+    super(`task ${taskId} is parked (OPEN/parked); unpark it or claim with --force`);
+    this.taskId = taskId;
+    this.workstream = workstream;
+  }
+  taskId;
+  workstream;
+  name = "TaskParkedError";
+  errorNextSteps() {
+    const ws = this.workstream;
+    return [
+      { intent: "Unpark it, then claim", command: `mu task unpark ${this.taskId} -w ${ws}` },
+      { intent: "Claim it anyway", command: `mu task claim ${this.taskId} --force -w ${ws}` }
+    ];
+  }
+};
+var InvalidSubstateError = class extends Error {
+  constructor(status, substate) {
+    super(
+      `invalid substate for ${status}: ${JSON.stringify(substate)} (expected one of: ${TASK_SUBSTATES[status].join(", ")})`
+    );
+    this.status = status;
+    this.substate = substate;
+  }
+  status;
+  substate;
+  name = "InvalidSubstateError";
+  errorNextSteps() {
+    return TASK_SUBSTATES[this.status].map((s) => ({
+      intent: `Use ${this.status}/${s}`,
+      command: this.status === "CLOSED" ? `mu task close <id> --as ${s}` : `mu task list --substate ${s}`
+    }));
+  }
+};
 
 // src/tasks/edges.ts
 function dedupeBlockersById(blockers) {
@@ -5239,12 +5426,12 @@ function getTaskEdgesWithStatus(db, taskLocalId, workstream) {
   const taskId = taskIdFor(db, taskLocalId, workstream);
   if (taskId === null) return { blockers: [], dependents: [] };
   const blockers = db.prepare(
-    `SELECT t.local_id AS name, t.status AS status FROM task_edges e
+    `SELECT t.local_id AS name, t.status AS status, t.substate AS substate FROM task_edges e
          JOIN tasks t ON t.id = e.from_task_id
         WHERE e.to_task_id = ? ORDER BY t.local_id`
   ).all(taskId);
   const dependents = db.prepare(
-    `SELECT t.local_id AS name, t.status AS status FROM task_edges e
+    `SELECT t.local_id AS name, t.status AS status, t.substate AS substate FROM task_edges e
          JOIN tasks t ON t.id = e.to_task_id
         WHERE e.from_task_id = ? ORDER BY t.local_id`
   ).all(taskId);
@@ -5617,8 +5804,8 @@ function addTaskImpl(db, opts) {
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const insertResult = db.prepare(
-      `INSERT INTO tasks (workstream_id, local_id, title, status, impact, effort_days, created_at, updated_at)
-         VALUES (?, ?, ?, 'OPEN', ?, ?, ?, ?)`
+      `INSERT INTO tasks (workstream_id, local_id, title, status, substate, impact, effort_days, created_at, updated_at)
+         VALUES (?, ?, ?, 'OPEN', 'todo', ?, ?, ?, ?)`
     ).run(wsId, opts.localId, opts.title, opts.impact, opts.effortDays, now, now);
     const newTaskId = Number(insertResult.lastInsertRowid);
     if (opts.blockedBy && opts.blockedBy.length > 0) {
@@ -5667,10 +5854,10 @@ function addNote(db, taskLocalId, content, opts) {
   return withOpContext(
     db,
     { intent: "task.note", actor: opts.author, group: "new" },
-    () => addNoteImpl(db, taskLocalId, content, opts)
+    () => insertNote(db, taskLocalId, content, opts)
   );
 }
-function addNoteImpl(db, taskLocalId, content, opts) {
+function insertNote(db, taskLocalId, content, opts) {
   const task = getTask(db, taskLocalId, opts.workstream);
   if (!task) {
     throw new TaskNotFoundError(taskLocalId);
@@ -5782,19 +5969,32 @@ function setTaskStatus(db, localId, status, opts) {
   );
 }
 function setTaskStatusImpl(db, localId, status, opts) {
+  const substate = opts.substate ?? DEFAULT_SUBSTATE[status];
+  if (!isValidPair(status, substate)) throw new InvalidSubstateError(status, substate);
   const before = getTask(db, localId, opts.workstream);
   if (!before) throw new TaskNotFoundError(localId);
-  if (before.status === status) {
-    return { previousStatus: before.status, status, changed: false };
+  const base = {
+    previousStatus: before.status,
+    status,
+    previousSubstate: before.substate,
+    substate
+  };
+  if (before.status === status && before.substate === substate) {
+    return { ...base, changed: false };
   }
   db.prepare(
-    `UPDATE tasks SET status = ?, updated_at = ?
+    `UPDATE tasks SET status = ?, substate = ?, updated_at = ?
       WHERE local_id = ?
         AND workstream_id = (SELECT id FROM workstreams WHERE name = ?)`
-  ).run(status, (/* @__PURE__ */ new Date()).toISOString(), localId, before.workstreamName);
-  return { previousStatus: before.status, status, changed: true };
+  ).run(status, substate, (/* @__PURE__ */ new Date()).toISOString(), localId, before.workstreamName);
+  return { ...base, changed: true };
 }
 function closeTask(db, localId, opts) {
+  const as = opts.as ?? "done";
+  if (!isValidPair("CLOSED", as)) throw new InvalidSubstateError("CLOSED", as);
+  if (as !== "done" && (opts.why === void 0 || opts.why.trim() === "")) {
+    throw new SubstateReasonRequiredError("close", as, localId);
+  }
   return withOpContext(
     db,
     { intent: "task.close", actor: opts.author, group: "new" },
@@ -5802,6 +6002,7 @@ function closeTask(db, localId, opts) {
   );
 }
 function closeTaskImpl(db, localId, opts) {
+  const as = opts.as ?? "done";
   const before = getTask(db, localId, opts.workstream);
   if (opts.ifReady && before) {
     const edges = getTaskEdgesWithStatus(db, localId, before.workstreamName);
@@ -5811,14 +6012,43 @@ function closeTaskImpl(db, localId, opts) {
         skipped: "not_ready",
         previousStatus: before.status,
         status: before.status,
+        previousSubstate: before.substate,
+        substate: before.substate,
         changed: false,
         blockingIds: blocking
       };
     }
   }
-  const r = setTaskStatus(db, localId, "CLOSED", opts);
-  if (r.changed && before) recordEvidenceNote(db, localId, before.workstreamName, "CLOSE", opts);
-  return r;
+  return db.transaction(() => {
+    const track = as !== "done" && before !== void 0;
+    const readyBefore = track ? readyDependents(db, localId, before.workstreamName) : [];
+    const r = setTaskStatus(db, localId, "CLOSED", {
+      workstream: opts.workstream,
+      substate: as,
+      ...opts.evidence !== void 0 ? { evidence: opts.evidence } : {}
+    });
+    if (!r.changed || !before) return { ...r, unblocked: [] };
+    recordReasonNote(db, localId, before.workstreamName, as, opts.why, opts.author);
+    recordEvidenceNote(db, localId, before.workstreamName, "CLOSE", opts);
+    const unblocked = track ? readyDependents(db, localId, before.workstreamName).filter((n) => !readyBefore.includes(n)) : [];
+    return { ...r, unblocked };
+  })();
+}
+function readyDependents(db, localId, workstream) {
+  const id = taskIdFor(db, localId, workstream);
+  if (id === null) return [];
+  const rows = db.prepare(
+    `SELECT r.local_id AS name FROM task_edges e
+         JOIN ready r ON r.id = e.to_task_id
+        WHERE e.from_task_id = ? ORDER BY r.local_id`
+  ).all(id);
+  return rows.map((r) => r.name);
+}
+function recordReasonNote(db, localId, workstream, substate, why, author) {
+  if (why === void 0 || why.trim() === "") return;
+  const noteOpts = { workstream };
+  if (author !== void 0 && author !== "") noteOpts.author = author;
+  insertNote(db, localId, `${substate.toUpperCase()}: ${why}`, noteOpts);
 }
 function openTask(db, localId, opts) {
   return withOpContext(db, { intent: "task.open", group: "new" }, () => {
@@ -5828,6 +6058,51 @@ function openTask(db, localId, opts) {
     return r;
   });
 }
+function parkTask(db, localId, opts) {
+  if (opts.why.trim() === "") throw new SubstateReasonRequiredError("park", "parked", localId);
+  return withOpContext(
+    db,
+    { intent: "task.park", actor: opts.author, group: "new" },
+    () => db.transaction(() => {
+      const before = getTask(db, localId, opts.workstream);
+      if (!before) throw new TaskNotFoundError(localId);
+      if (before.status !== "OPEN") {
+        throw new TaskParkStateError(localId, before.status, before.workstreamName);
+      }
+      const r = setTaskStatus(db, localId, "OPEN", {
+        workstream: opts.workstream,
+        substate: "parked"
+      });
+      if (r.changed) {
+        recordReasonNote(db, localId, before.workstreamName, "parked", opts.why, opts.author);
+        recordEvidenceNote(db, localId, before.workstreamName, "PARK", opts);
+      }
+      return r;
+    })()
+  );
+}
+function unparkTask(db, localId, opts) {
+  return withOpContext(
+    db,
+    { intent: "task.unpark", group: "new" },
+    () => db.transaction(() => {
+      const before = getTask(db, localId, opts.workstream);
+      if (!before) throw new TaskNotFoundError(localId);
+      if (before.status !== "OPEN" || before.substate !== "parked") {
+        return {
+          previousStatus: before.status,
+          status: before.status,
+          previousSubstate: before.substate,
+          substate: before.substate,
+          changed: false
+        };
+      }
+      const r = setTaskStatus(db, localId, "OPEN", { workstream: opts.workstream });
+      recordEvidenceNote(db, localId, before.workstreamName, "UNPARK", opts);
+      return r;
+    })()
+  );
+}
 
 // src/tasks/claim.ts
 function releaseTask(db, localId, opts) {
@@ -5852,10 +6127,16 @@ function releaseTaskImpl(db, localId, opts) {
     };
   }
   db.prepare(
-    `UPDATE tasks SET owner_id = NULL, status = ?, updated_at = ?
+    `UPDATE tasks SET owner_id = NULL, status = ?, substate = ?, updated_at = ?
       WHERE local_id = ?
         AND workstream_id = (SELECT id FROM workstreams WHERE name = ?)`
-  ).run(newStatus, (/* @__PURE__ */ new Date()).toISOString(), localId, before.workstreamName);
+  ).run(
+    newStatus,
+    statusChanges ? DEFAULT_SUBSTATE[newStatus] : before.substate,
+    (/* @__PURE__ */ new Date()).toISOString(),
+    localId,
+    before.workstreamName
+  );
   recordEvidenceNote(db, localId, before.workstreamName, "RELEASE", opts);
   return {
     previousOwnerName: before.ownerName,
@@ -5896,11 +6177,15 @@ async function claimTaskImpl(db, localId, opts) {
     () => db.transaction(() => {
       const before = getTask(db, localId, opts.workstream);
       if (!before) throw new TaskNotFoundError(localId);
+      assertNotParked(before, opts);
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const result = db.prepare(
         `UPDATE tasks
             SET owner_id = ?,
                 status = CASE WHEN status = 'OPEN' THEN 'IN_PROGRESS' ELSE status END,
+                -- SQLite evaluates every SET expression against the OLD
+                -- row, so this CASE still sees the pre-claim status.
+                substate = CASE WHEN status = 'OPEN' THEN 'active' ELSE substate END,
                 updated_at = ?
           WHERE local_id = ?
             AND workstream_id = (SELECT id FROM workstreams WHERE name = ?)
@@ -5922,6 +6207,11 @@ async function claimTaskImpl(db, localId, opts) {
     })()
   );
 }
+function assertNotParked(task, opts) {
+  if (task.status === "OPEN" && task.substate === "parked" && opts.force !== true) {
+    throw new TaskParkedError(task.name, task.workstreamName);
+  }
+}
 async function resolveActorIdentity() {
   const worker = await resolveWorkerIdentity();
   if (worker !== void 0) return worker;
@@ -5947,10 +6237,12 @@ async function claimSelf(db, localId, opts) {
     () => db.transaction(() => {
       const before = getTask(db, localId, opts.workstream);
       if (!before) throw new TaskNotFoundError(localId);
+      assertNotParked(before, opts);
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const result = db.prepare(
         `UPDATE tasks
             SET status = CASE WHEN status = 'OPEN' THEN 'IN_PROGRESS' ELSE status END,
+                substate = CASE WHEN status = 'OPEN' THEN 'active' ELSE substate END,
                 updated_at = ?
           WHERE local_id = ?
             AND workstream_id = (SELECT id FROM workstreams WHERE name = ?)
@@ -5973,17 +6265,6 @@ async function claimSelf(db, localId, opts) {
   );
 }
 
-// src/tasks/status.ts
-var TASK_STATUSES = ["OPEN", "IN_PROGRESS", "CLOSED"];
-function isTaskStatus(s) {
-  return TASK_STATUSES.includes(s);
-}
-var RETIRED_STATUSES = /* @__PURE__ */ new Set(["REJECTED", "DEFERRED"]);
-function normalizeTaskStatus(value) {
-  return RETIRED_STATUSES.has(value) ? "OPEN" : value;
-}
-var TASK_STATUS_LIST = TASK_STATUSES.join(" | ");
-
 // src/tasks/wait.ts
 var currentWaitSleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
 var pollCount = 0;
@@ -6054,6 +6335,7 @@ async function waitForTasks(db, input, opts) {
     for (const ref of refs) {
       const row = getTask(db, ref.name, ref.workstreamName);
       const status = row?.status ?? "OPEN";
+      const substate = row?.substate ?? DEFAULT_SUBSTATE[status];
       const owner = row?.ownerName ?? null;
       const ageMs = await stuckAgeMs(status, owner, ref.workstreamName);
       const stuck = ageMs !== null;
@@ -6082,6 +6364,7 @@ async function waitForTasks(db, input, opts) {
         workstreamName: ref.workstreamName,
         name: ref.name,
         status,
+        substate,
         owner,
         reachedTarget: status === target,
         stuck
@@ -6470,10 +6753,9 @@ function deleteAgent(db, name, workstream) {
       const result = db.prepare("DELETE FROM agents WHERE id = ?").run(agentId);
       if (result.changes === 0) return false;
       for (const t of stuck) {
-        db.prepare("UPDATE tasks SET status = 'OPEN', updated_at = ? WHERE id = ?").run(
-          (/* @__PURE__ */ new Date()).toISOString(),
-          t.taskId
-        );
+        db.prepare(
+          "UPDATE tasks SET status = 'OPEN', substate = 'todo', updated_at = ? WHERE id = ?"
+        ).run((/* @__PURE__ */ new Date()).toISOString(), t.taskId);
         addNote(
           db,
           t.localId,
@@ -6704,7 +6986,7 @@ function applyFieldLww(db, op, table, rowId, entries) {
   return applied;
 }
 var APPLIABLE_COLUMNS = {
-  tasks: ["title", "status", "impact", "effort_days", "created_at", "updated_at"],
+  tasks: ["title", "status", "substate", "impact", "effort_days", "created_at", "updated_at"],
   workstreams: ["created_at"]
 };
 function filterAppliable(table, entries) {
@@ -6713,9 +6995,20 @@ function filterAppliable(table, entries) {
 }
 function applyTaskPut(db, op) {
   const { workstream, localId } = parseTaskKey(op.key);
-  const entries = filterAppliable("tasks", decodePayload(op.payload)).map(
-    ([field, value]) => field === "status" && typeof value === "string" ? [field, normalizeTaskStatus(value)] : [field, value]
-  );
+  const entries = [];
+  for (const entry of filterAppliable("tasks", decodePayload(op.payload))) {
+    const [field, value] = entry;
+    if (field === "substate") continue;
+    if (field === "status") {
+      if (typeof value !== "string") continue;
+      const legacy = mapLegacyStatus(value);
+      if (legacy) entries.push(["status", legacy.status]);
+      else if (isTaskStatus(value)) entries.push(entry);
+      continue;
+    }
+    entries.push(entry);
+  }
+  const pending = { hlc: op.hlc, substate: carriedSubstate(JSON.parse(op.payload)) };
   const existing = taskRowId(db, op.key);
   if (existing === null) {
     const tomb = tombstoneHlc(db, op);
@@ -6725,18 +7018,60 @@ function applyTaskPut(db, op) {
     const wsId = ensureWorkstreamRow(db, workstream);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     db.prepare(
-      `INSERT INTO tasks (workstream_id, local_id, title, status, impact, effort_days,
+      `INSERT INTO tasks (workstream_id, local_id, title, status, substate, impact, effort_days,
                           owner_id, created_at, updated_at)
-       VALUES (?, ?, ?, 'OPEN', 50, 1, NULL, ?, ?)`
+       VALUES (?, ?, ?, 'OPEN', 'todo', 50, 1, NULL, ?, ?)`
     ).run(wsId, localId, localId, now, now);
     const rowId = taskRowId(db, op.key);
     if (rowId === null) throw new Error(`failed to create task row for ${op.key}`);
     const applied2 = applyFieldLww(db, op, "tasks", rowId, entries);
+    if (repairTaskPair(db, rowId, pending)) applied2.push("substate");
     return { changed: true, appliedFields: applied2 };
   }
   const applied = applyFieldLww(db, op, "tasks", existing, entries);
+  if (repairTaskPair(db, existing, pending)) applied.push("substate");
   return applied.length > 0 ? { changed: true, appliedFields: applied } : { changed: false, appliedFields: [], skipped: "older-than-current" };
 }
+function carriedSubstate(payload) {
+  if (payload === null || typeof payload !== "object") return null;
+  const { status, substate } = payload;
+  if (typeof status === "string") {
+    const legacy = mapLegacyStatus(status);
+    if (legacy) return legacy.substate;
+    if (typeof substate !== "string" && isTaskStatus(status)) return DEFAULT_SUBSTATE[status];
+  }
+  return typeof substate === "string" ? substate : null;
+}
+function repairTaskPair(db, rowId, pending) {
+  const row = db.prepare(
+    `SELECT t.status, t.substate, w.name || '/' || t.local_id AS key
+         FROM tasks t JOIN workstreams w ON w.id = t.workstream_id
+        WHERE t.id = ?`
+  ).get(rowId);
+  if (!row) return false;
+  let winner = null;
+  const writers = db.prepare(
+    `SELECT hlc, payload FROM ops
+        WHERE entity = 'task' AND key = ? AND op = 'put' AND hlc <> ?
+          AND ${LEGACY_LOG_ONLY_SQL_EXCLUSION}
+          AND (json_type(payload, '$.substate') IS NOT NULL
+               OR json_type(payload, '$.status') IS NOT NULL)
+        ORDER BY hlc DESC`
+  ).iterate(row.key, pending?.hlc ?? "");
+  for (const w of writers) {
+    const substate = carriedSubstate(JSON.parse(w.payload));
+    if (substate === null) continue;
+    winner = { hlc: w.hlc, substate };
+    break;
+  }
+  if (pending && pending.substate !== null && wins(pending.hlc, winner?.hlc ?? null)) {
+    winner = { hlc: pending.hlc, substate: pending.substate };
+  }
+  const target = resolvePair(row.status, winner?.substate ?? row.substate);
+  if (target === null || target.substate === row.substate) return false;
+  db.prepare("UPDATE tasks SET substate = ? WHERE id = ?").run(target.substate, rowId);
+  return true;
+}
 function applyWorkstreamPut(db, op) {
   const name = op.key;
   if (name.length === 0) throw new OpKeyMalformedError("workstream", name);
@@ -6878,7 +7213,7 @@ function applyOp(db, op) {
       case "workstream":
         return applyWorkstreamPut(db, op);
       case "task":
-        return applyTaskPut(db, op);
+        return db.transaction(() => applyTaskPut(db, op))();
       case "note":
         return applyNotePut(db, op);
       case "edge":
@@ -6992,7 +7327,7 @@ import pc2 from "picocolors";
 var RECURRENCE_MARKER = `  ${pc2.dim("(\u21BB)")}`;
 function loadFullDag(db, workstream, opts = {}) {
   const tasks = listTasks(db, workstream).filter(
-    (t) => opts.statuses === void 0 || opts.statuses.has(t.status)
+    (t) => (opts.statuses === void 0 || opts.statuses.has(t.status)) && (opts.include === void 0 || opts.include(t))
   );
   const byName = new Map(tasks.map((t) => [t.name, t]));
   const incoming = /* @__PURE__ */ new Set();
@@ -7327,7 +7662,7 @@ function checkCheapDriftInvariant(db) {
 }
 var COMPARED = {
   workstreams: ["created_at"],
-  tasks: ["title", "status", "impact", "effort_days", "created_at", "updated_at"],
+  tasks: ["title", "status", "substate", "impact", "effort_days", "created_at", "updated_at"],
   task_notes: ["author", "content", "created_at"],
   task_edges: ["created_at"]
 };
@@ -7335,7 +7670,7 @@ var SNAPSHOT_SQL = {
   workstreams: `SELECT w.name AS key, w.created_at
                   FROM workstreams w`,
   tasks: `SELECT w.name || '/' || t.local_id AS key,
-                 t.title, t.status, t.impact, t.effort_days, t.created_at, t.updated_at
+                 t.title, t.status, t.substate, t.impact, t.effort_days, t.created_at, t.updated_at
             FROM tasks t JOIN workstreams w ON w.id = t.workstream_id`,
   // Notes are a GROW-ONLY SET whose local surrogate id is not portable,
   // so identity for diffing is (task, author, content) — exactly the
@@ -8055,6 +8390,8 @@ var VERBS = {
   "task.delete": "task delete",
   "task.close": "task close",
   "task.open": "task open",
+  "task.park": "task park",
+  "task.unpark": "task unpark",
   "task.reject": "task reject",
   "task.defer": "task defer",
   "task.claim": "task claim",
@@ -8141,7 +8478,16 @@ function renderKnown(row, intent) {
     case "task.reject":
     case "task.defer": {
       const status = str(bag, "status");
-      return { verb: VERBS[intent], subject, detail: status === void 0 ? "" : `\u2192 ${status}` };
+      return {
+        verb: VERBS[intent],
+        subject,
+        detail: status === void 0 ? "" : `\u2192 ${pairText(bag, status)}`
+      };
+    }
+    case "task.park":
+    case "task.unpark": {
+      const detail = str(bag, "substate") === void 0 ? "" : `\u2192 ${pairText(bag, "OPEN")}`;
+      return { verb: VERBS[intent], subject, detail };
     }
     case "task.claim": {
       const by = row.source === "" ? "" : `by ${row.source}`;
@@ -8200,6 +8546,10 @@ function renderKnown(row, intent) {
     }
   }
 }
+function pairText(bag, status) {
+  const pair = resolvePair(status, str(bag, "substate"));
+  return pair === null ? status : formatPair(pair);
+}
 function oneLine(text, max = 60) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length <= max ? flat : `${flat.slice(0, max - 1)}\u2026`;
@@ -8746,7 +9096,8 @@ function getParallelTracks(db, workstream) {
              FROM reach r
              JOIN task_edges e ON e.to_task_id = r.node_id
          )
-       SELECT goal.local_id AS goal_id, node.local_id AS task_id
+       SELECT goal.local_id AS goal_id, node.local_id AS task_id,
+              node.status AS status, node.substate AS substate
          FROM reach r
          JOIN tasks goal ON goal.id = r.goal_id
          JOIN tasks node ON node.id = r.node_id`
@@ -8754,7 +9105,9 @@ function getParallelTracks(db, workstream) {
   const subgraphs = new Map(goals.map((goal) => [goal.name, /* @__PURE__ */ new Set()]));
   const uf = new UnionFind(goals.map((goal) => goal.name));
   const firstGoalByTask = /* @__PURE__ */ new Map();
+  const openSubstate = /* @__PURE__ */ new Map();
   for (const row of reach) {
+    if (row.status !== "CLOSED") openSubstate.set(row.task_id, row.substate);
     subgraphs.get(row.goal_id)?.add(row.task_id);
     const firstGoal = firstGoalByTask.get(row.task_id);
     if (firstGoal === void 0) firstGoalByTask.set(row.task_id, row.goal_id);
@@ -8781,8 +9134,17 @@ function getParallelTracks(db, workstream) {
   for (const [root, taskIds] of componentTaskIds) {
     const trackRoots = componentRoots.get(root) ?? [];
     let readyCount = 0;
-    for (const id of taskIds) if (readyIds.has(id)) readyCount++;
-    tracks.push({ roots: trackRoots, taskIds, readyCount });
+    let openCount = 0;
+    let parkedCount = 0;
+    for (const id of taskIds) {
+      if (readyIds.has(id)) readyCount++;
+      const sub = openSubstate.get(id);
+      if (sub === void 0) continue;
+      openCount++;
+      if (sub === "parked") parkedCount++;
+    }
+    const parked = openCount > 0 && parkedCount === openCount;
+    tracks.push({ roots: trackRoots, taskIds, readyCount, parked });
   }
   tracks.sort((a, b) => {
     const an = a.roots[0]?.name ?? "";
@@ -8844,6 +9206,7 @@ async function loadWorkstreamSnapshotFast(db, workstream, opts = {}) {
     inProgress: listInProgress(db, workstream),
     blocked: listBlocked(db, workstream),
     recentClosed: listRecentClosed(db, workstream),
+    parkedCount: listTasks(db, workstream, { status: "OPEN", substate: "parked" }).length,
     allTasks: opts.withAllTasks === true ? listTasks(db, workstream) : [],
     workspaces: listWorkspaces2(db, workstream),
     workspaceOrphans: listWorkspaceOrphans(db, workstream),
@@ -8916,6 +9279,7 @@ function minimalSnapshot(workstream) {
     inProgress: [],
     blocked: [],
     recentClosed: [],
+    parkedCount: 0,
     allTasks: [],
     workspaces: [],
     workspaceOrphans: [],
@@ -9374,13 +9738,13 @@ function planUndo(db, groupId) {
       if (Object.keys(fields3).length === 0) fields3 = payloadFields(row.payload);
       if (Object.keys(fields3).length === 0 && row.entity === "note") {
         const recovered = recoverLegacyNoteContents(db, row.key, row.hlc, seenLegacyNoteTasks);
-        for (const legacy of recovered) {
+        for (const legacy2 of recovered) {
           inverses.push({
             entity: "note",
-            key: legacy.key,
+            key: legacy2.key,
             op: "put",
-            fields: legacy.fields,
-            summary: `note ${legacy.key} (recovered from legacy history)`,
+            fields: legacy2.fields,
+            summary: `note ${legacy2.key} (recovered from legacy history)`,
             supersededBy: []
           });
         }
@@ -9388,7 +9752,11 @@ function planUndo(db, groupId) {
         continue;
       }
       const status = fields3.status;
-      if (typeof status === "string") fields3.status = normalizeTaskStatus(status);
+      const legacy = typeof status === "string" ? mapLegacyStatus(status) : null;
+      if (legacy) {
+        fields3.status = legacy.status;
+        fields3.substate = legacy.substate;
+      }
       const conflicts = laterRowWriters(db, row.entity, row.key, row.hlc, groupId).map((w) => ({
         field: "<row>",
         groupId: w.groupId,
@@ -9608,15 +9976,23 @@ function restoreRow(db, inverse, table) {
       if (id === null) {
         const wsId = ensureWorkstream2(db, parsed.workstream);
         const now = (/* @__PURE__ */ new Date()).toISOString();
+        const pair = resolvePair(
+          String(inverse.fields.status ?? "OPEN"),
+          inverse.fields.substate
+        ) ?? {
+          status: "OPEN",
+          substate: "todo"
+        };
         db.prepare(
-          `INSERT INTO tasks (workstream_id, local_id, title, status, impact, effort_days,
-                              owner_id, created_at, updated_at)
-           VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?)`
+          `INSERT INTO tasks (workstream_id, local_id, title, status, substate, impact,
+                              effort_days, owner_id, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`
         ).run(
           wsId,
           parsed.localId,
           String(inverse.fields.title ?? parsed.localId),
-          String(inverse.fields.status ?? "OPEN"),
+          pair.status,
+          pair.substate,
           Number(inverse.fields.impact ?? 50),
           Number(inverse.fields.effort_days ?? 1),
           String(inverse.fields.created_at ?? now),
@@ -9624,7 +10000,8 @@ function restoreRow(db, inverse, table) {
         );
         return true;
       }
-      return updateFields(db, "tasks", "id", id, inverse.fields);
+      const updated = updateFields(db, "tasks", "id", id, inverse.fields);
+      return repairTaskPair(db, id) || updated;
     }
     case "note": {
       const parsed = parseNoteKey2(inverse.key);
@@ -9726,6 +10103,7 @@ export {
   ClaimerNotRegisteredError,
   CrossWorkstreamEdgeError,
   CycleError,
+  DEFAULT_SUBSTATE,
   DRIFT_REPORT_CAP,
   DriftDetectedError,
   EXPECTED_TABLES,
@@ -9733,6 +10111,7 @@ export {
   HlcOverflowError,
   HlcParseError,
   HomeDirAsProjectRootError,
+  InvalidSubstateError,
   KNOWN_INTENTS,
   KNOWN_VERBS,
   MACHINE_LOCAL_ENTITIES,
@@ -9755,15 +10134,20 @@ export {
   SEGMENT_FORMAT_VERSION,
   SYNCED_ENTITIES,
   SchemaTooOldError,
+  SubstateReasonRequiredError,
   SyncPeerNotFoundError,
   SyncPeerRefAmbiguousError,
   SyncSourceNotFoundError,
   TASK_STATUSES,
   TASK_STATUS_LIST,
+  TASK_SUBSTATES,
+  TASK_SUBSTATE_ROWS,
   TaskAlreadyOwnedError,
   TaskExistsError,
   TaskNotFoundError,
   TaskNotInWorkstreamError,
+  TaskParkStateError,
+  TaskParkedError,
   TmuxError,
   UNKNOWN_REASON,
   UndoGroupNotFoundError,
@@ -9833,6 +10217,7 @@ export {
   foregroundPgid,
   formatDriftRecord,
   formatHlc,
+  formatPair,
   freeWorkspace,
   getAgent,
   getAgentByPane,
@@ -9857,6 +10242,7 @@ export {
   isPathInside,
   isTaskStatus,
   isValidAgentName,
+  isValidPair,
   isValidPaneId,
   isValidTaskId,
   isValidWorkstreamName,
@@ -9894,6 +10280,7 @@ export {
   loadWorkstreamSnapshotSlow,
   localMachineId,
   locksDir,
+  mapLegacyStatus,
   mergeSnapshotFastSlow,
   mostRecentGroup,
   murmurAvailable,
@@ -9909,6 +10296,7 @@ export {
   openTask,
   paneExists,
   paneTTY,
+  parkTask,
   parseAgentNameFromTitle,
   parseHlc,
   parseOpKey,
@@ -9945,6 +10333,7 @@ export {
   resolveCliCommand,
   resolveCliCommandWithSource,
   resolveGroupId,
+  resolvePair,
   resolvePeerRef,
   roiBucket,
   segmentLineCount,
@@ -9979,6 +10368,7 @@ export {
   tmuxBackend,
   transportNextSteps,
   undoGroup,
+  unparkTask,
   updateTask,
   verifyAgainstManifest,
   waitForTasks,