@basou/cli 0.3.1

package/dist/index.js

@@ -0,0 +1,3594 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+import { Command } from "commander";
+
+// src/commands/approval.ts
+import { unlink } from "fs/promises";
+import { join } from "path";
+import {
+  ApprovalSchema,
+  ApprovalStatusSchema,
+  appendEvent,
+  assertBasouRootSafe,
+  basouPaths,
+  enumerateApprovals,
+  findErrorCode,
+  isLazyExpired,
+  linkYamlFile,
+  loadApproval,
+  prefixedUlid,
+  readYamlFile,
+  replayEvents,
+  resolveRepositoryRoot
+} from "@basou/core";
+
+// src/lib/error-render.ts
+import {
+  FailedToFinalizeError
+} from "@basou/core";
+var SES_PREFIX = "ses_";
+var TASK_PREFIX = "task_";
+var SHORT_ID_LEN = 6;
+function shortSessionId(id) {
+  if (id.startsWith(SES_PREFIX))
+    return id.slice(SES_PREFIX.length, SES_PREFIX.length + SHORT_ID_LEN);
+  return id.slice(0, SHORT_ID_LEN);
+}
+function shortTaskId(id) {
+  if (id.startsWith(TASK_PREFIX))
+    return id.slice(TASK_PREFIX.length, TASK_PREFIX.length + SHORT_ID_LEN);
+  return id.slice(0, SHORT_ID_LEN);
+}
+function isVerbose(options) {
+  return options?.verbose === true || process.env.BASOU_DEBUG === "1";
+}
+var CAUSE_CHAIN_MAX_DEPTH = 4;
+function extractCauseLabel(error) {
+  let current = error.cause;
+  let constructorName;
+  for (let depth = 0; depth < CAUSE_CHAIN_MAX_DEPTH; depth += 1) {
+    if (!(current instanceof Error)) break;
+    const code = current.code;
+    if (typeof code === "string" && code.length > 0) return code;
+    constructorName = current.constructor.name;
+    current = current.cause;
+  }
+  return constructorName;
+}
+var failedToFinalizeClassifier = {
+  match: (error) => error instanceof FailedToFinalizeError,
+  additionalLines: (error) => {
+    const e = error;
+    const sid = shortSessionId(e.sessionId);
+    const anchor = e.targetEventIds[0];
+    return [
+      `Recorded ${anchor} in session ${sid}; do not rerun`,
+      "Warning: session.yaml status update failed; events.jsonl is consistent"
+    ];
+  }
+};
+function renderCliError(error, options) {
+  if (!(error instanceof Error)) {
+    console.error(String(error));
+    return;
+  }
+  console.error(error.message);
+  for (const classifier of options.classifiers ?? []) {
+    if (classifier.match(error)) {
+      for (const line of classifier.additionalLines(error)) console.error(line);
+    }
+  }
+  if (options.verbose) {
+    const label = extractCauseLabel(error);
+    if (label !== void 0) console.error(`Caused by: ${label}`);
+  }
+}
+function printReplayWarning(warning, sessionId) {
+  const short = shortSessionId(sessionId);
+  switch (warning.kind) {
+    case "partial_trailing_line":
+      console.error(`Warning: ignored partial trailing line in ${short}/events.jsonl`);
+      break;
+    case "malformed_json":
+      console.error(
+        `Warning: skipped malformed JSON at line ${warning.line} in ${short}/events.jsonl`
+      );
+      break;
+    case "schema_violation":
+      console.error(
+        `Warning: skipped invalid event at line ${warning.line} in ${short}/events.jsonl`
+      );
+      break;
+  }
+}
+function printSessionSkip(sid, reason) {
+  const short = shortSessionId(sid);
+  if (reason === "events_jsonl_unreadable") {
+    console.error(`Warning: skipped suspect check for ${short}: events.jsonl unreadable`);
+  } else {
+    console.error(`Skipped ${short}: ${reason}`);
+  }
+}
+function printSessionListSkip(sid, reason) {
+  const short = shortSessionId(sid);
+  switch (reason) {
+    case "session_yaml_missing":
+      console.error(`Skipped ${short}: session.yaml not found`);
+      break;
+    case "session_yaml_invalid":
+      console.error(`Skipped ${short}: invalid session schema`);
+      break;
+    case "events_jsonl_unreadable":
+      console.error(`Warning: skipped suspect check for ${short}: events.jsonl unreadable`);
+      break;
+  }
+}
+function printTaskSkip(taskId, reason) {
+  console.error(`Skipped ${shortTaskId(taskId)}: ${reason}`);
+}
+
+// src/commands/approval.ts
+var APPR_PREFIX = "appr_";
+var SHORT_ID_BASE_LEN = 6;
+var SHORT_ID_MAX_LEN = 26;
+var ACTION_KEY_DETAIL_MAX_LEN = 60;
+var REASON_TEXT_MAX_LEN = 80;
+var STATUS_VALUES = ApprovalStatusSchema.options;
+function registerApprovalCommand(program2) {
+  const approval = program2.command("approval").description("Manage Basou approval requests under .basou/approvals/");
+  approval.command("list").description("List approvals across pending and resolved (newest first)").option("--json", "Output the list as a JSON array").option(
+    "--status <state>",
+    `Filter by approval status (one of: ${STATUS_VALUES.join(", ")})`,
+    parseApprovalStatus
+  ).option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runApprovalList(options);
+  });
+  approval.command("show <id>").description("Show an approval's metadata and related events").option("--json", "Output the approval and events as JSON").option("-v, --verbose", "Show error causes").action(async (id, options) => {
+    await runApprovalShow(id, options);
+  });
+  approval.command("approve <id>").description("Approve a pending approval").option("--note <text>", "Optional note to attach to the approval_approved event").option("-v, --verbose", "Show error causes").action(async (id, options) => {
+    await runApprovalApprove(id, options);
+  });
+  approval.command("reject <id>").description("Reject a pending approval").requiredOption("--reason <text>", "Reason for rejection (required)").option("-v, --verbose", "Show error causes").action(async (id, options) => {
+    await runApprovalReject(id, options);
+  });
+}
+async function runApprovalList(options, ctx = {}) {
+  try {
+    await doRunApprovalList(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunApprovalList(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForApproval(cwd, "list");
+  const paths = basouPaths(repositoryRoot);
+  await assertWorkspaceInitialized(paths.root);
+  const ids = await enumerateApprovals(paths);
+  const now = /* @__PURE__ */ new Date();
+  const records = [];
+  const resolvedSet = new Set(ids.resolved);
+  for (const id of ids.pending) {
+    if (resolvedSet.has(id)) {
+      console.error(`Warning: stale pending entry for ${shortId(id)}; resolved version preferred`);
+      continue;
+    }
+    const rec = await readApprovalListRecord(paths, id, "pending", now);
+    if (rec !== null) records.push(rec);
+  }
+  for (const id of ids.resolved) {
+    const rec = await readApprovalListRecord(paths, id, "resolved", now);
+    if (rec !== null) records.push(rec);
+  }
+  records.sort((a, b) => Date.parse(b.approval.created_at) - Date.parse(a.approval.created_at));
+  const filtered = options.status !== void 0 ? records.filter((r) => r.approval.status === options.status) : records;
+  if (filtered.length === 0) {
+    printNoApprovals(options);
+    return;
+  }
+  if (options.json === true) {
+    console.log(
+      JSON.stringify(
+        filtered.map((r) => ({ ...r.approval, lazy_expired: r.lazyExpired })),
+        null,
+        2
+      )
+    );
+  } else {
+    printApprovalListText(filtered);
+  }
+}
+async function readApprovalListRecord(paths, id, location, now) {
+  const filePath = join(paths.approvals[location], `${id}.yaml`);
+  let raw;
+  try {
+    raw = await readYamlFile(filePath);
+  } catch (error) {
+    console.error(`Skipped ${shortId(id)}: ${describeReadError(error)}`);
+    return null;
+  }
+  const parse = ApprovalSchema.safeParse(raw);
+  if (!parse.success) {
+    console.error(`Skipped ${shortId(id)}: invalid approval schema`);
+    return null;
+  }
+  if (parse.data.id !== id) {
+    console.error(`Skipped ${shortId(id)}: filename and YAML body id disagree`);
+    return null;
+  }
+  const approval = parse.data;
+  return { approval, location, lazyExpired: isLazyExpired(approval, now) };
+}
+async function runApprovalShow(idInput, options, ctx = {}) {
+  try {
+    await doRunApprovalShow(idInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunApprovalShow(idInput, options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForApproval(cwd, "show");
+  const paths = basouPaths(repositoryRoot);
+  await assertWorkspaceInitialized(paths.root);
+  const { id } = await resolveApprovalId(paths, idInput);
+  const loaded = await loadApproval(paths, id);
+  if (loaded === null) {
+    throw new Error(`Approval not found: ${idInput}`);
+  }
+  const sessionDir = join(paths.sessions, loaded.approval.session_id);
+  const relatedEvents = [];
+  for await (const ev of replayEvents(sessionDir, {
+    onWarning: (w) => printReplayWarning(w, loaded.approval.session_id)
+  })) {
+    if (isApprovalEvent(ev) && ev.approval_id === id) {
+      relatedEvents.push(ev);
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  const lazyExpired = isLazyExpired(loaded.approval, now);
+  if (options.json === true) {
+    console.log(
+      JSON.stringify(
+        {
+          approval: { ...loaded.approval, lazy_expired: lazyExpired },
+          events: relatedEvents
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  printApprovalShowText(loaded.approval, loaded.location, relatedEvents, lazyExpired);
+}
+async function runApprovalApprove(idInput, options, ctx = {}) {
+  try {
+    await doRunApprovalResolve(idInput, options, ctx, "approve");
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function runApprovalReject(idInput, options, ctx = {}) {
+  try {
+    await doRunApprovalResolve(idInput, options, ctx, "reject");
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunApprovalResolve(idInput, options, ctx, decision) {
+  if (decision === "reject") {
+    const reason = options.reason;
+    if (reason.length === 0) {
+      throw new Error("--reason must not be empty");
+    }
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForApproval(cwd, decision);
+  const paths = basouPaths(repositoryRoot);
+  await assertWorkspaceInitialized(paths.root);
+  const { id, location } = await resolveApprovalId(paths, idInput);
+  if (location === "resolved") {
+    throw new Error(`Approval already resolved: ${idInput}`);
+  }
+  const pendingPath = join(paths.approvals.pending, `${id}.yaml`);
+  let pendingRaw;
+  try {
+    pendingRaw = await readYamlFile(pendingPath);
+  } catch (error) {
+    if (error instanceof Error && error.message === "YAML file not found") {
+      throw new Error(`Approval not found: ${idInput}`);
+    }
+    throw new Error("Failed to read approval", { cause: error });
+  }
+  const approvalParse = ApprovalSchema.safeParse(pendingRaw);
+  if (!approvalParse.success) {
+    throw new Error("Failed to read approval", { cause: approvalParse.error });
+  }
+  const approval = approvalParse.data;
+  if (approval.id !== id) {
+    throw new Error("Failed to read approval", {
+      cause: new Error(`Approval id mismatch: filename id ${id} vs YAML body id ${approval.id}`)
+    });
+  }
+  if (approval.status !== "pending") {
+    throw new Error(`Approval status mismatch: pending YAML has status=${approval.status}`);
+  }
+  const sessionDir = join(paths.sessions, approval.session_id);
+  for await (const ev of replayEvents(sessionDir, {
+    onWarning: (w) => printReplayWarning(w, approval.session_id)
+  })) {
+    if (isApprovalEvent(ev) && ev.approval_id === approval.id && (ev.type === "approval_approved" || ev.type === "approval_rejected" || ev.type === "approval_expired")) {
+      throw new Error(`Approval already resolved (per events.jsonl): ${idInput}`);
+    }
+  }
+  const now = /* @__PURE__ */ new Date();
+  if (isLazyExpired(approval, now)) {
+    throw new Error(`Approval already expired: ${idInput}`);
+  }
+  const occurredAt = now.toISOString();
+  const eventId = prefixedUlid("evt");
+  if (decision === "approve") {
+    const note = options.note ?? null;
+    await appendEvent(sessionDir, {
+      schema_version: "0.1.0",
+      id: eventId,
+      session_id: approval.session_id,
+      occurred_at: occurredAt,
+      source: "local-cli",
+      type: "approval_approved",
+      approval_id: approval.id,
+      resolver: "local-cli",
+      note
+    });
+  } else {
+    const reason = options.reason;
+    await appendEvent(sessionDir, {
+      schema_version: "0.1.0",
+      id: eventId,
+      session_id: approval.session_id,
+      occurred_at: occurredAt,
+      source: "local-cli",
+      type: "approval_rejected",
+      approval_id: approval.id,
+      resolver: "local-cli",
+      reason
+    });
+  }
+  const resolvedApproval = decision === "approve" ? {
+    ...approval,
+    status: "approved",
+    resolver: "local-cli",
+    resolved_at: occurredAt,
+    note: options.note ?? null
+  } : {
+    ...approval,
+    status: "rejected",
+    resolver: "local-cli",
+    resolved_at: occurredAt,
+    rejection_reason: options.reason
+  };
+  const resolvedPath = join(paths.approvals.resolved, `${id}.yaml`);
+  try {
+    await linkYamlFile(resolvedPath, resolvedApproval);
+  } catch (error) {
+    const cause = error instanceof Error ? error.cause : void 0;
+    if (cause instanceof Error && cause.code === "EEXIST") {
+      throw new Error("Approval already resolved at the same time", { cause });
+    }
+    throw error;
+  }
+  try {
+    await unlink(pendingPath);
+  } catch {
+    console.error(
+      `Warning: failed to unlink pending entry for ${shortId(id)}; events.jsonl is consistent`
+    );
+  }
+  const verb = decision === "approve" ? "Approved" : "Rejected";
+  console.log(`${verb} approval ${shortId(id)}`);
+}
+async function resolveApprovalId(paths, input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Approval id is empty");
+  }
+  const normalized = trimmed.startsWith(APPR_PREFIX) ? trimmed : `${APPR_PREFIX}${trimmed}`;
+  if (normalized.length <= APPR_PREFIX.length) {
+    throw new Error(`Approval not found: ${input}`);
+  }
+  const enumeration = await enumerateApprovals(paths);
+  const byId = /* @__PURE__ */ new Map();
+  for (const id2 of enumeration.pending) {
+    if (id2.startsWith(normalized)) byId.set(id2, "pending");
+  }
+  for (const id2 of enumeration.resolved) {
+    if (!id2.startsWith(normalized)) continue;
+    if (byId.get(id2) === "pending") {
+      console.error(`Warning: stale pending entry for ${shortId(id2)}; resolved version preferred`);
+    }
+    byId.set(id2, "resolved");
+  }
+  if (byId.size === 0) {
+    throw new Error(`Approval not found: ${input}`);
+  }
+  if (byId.size > 1) {
+    throw new Error(
+      `Ambiguous approval id '${input}': matched ${byId.size} approvals. Disambiguate with a longer prefix.`
+    );
+  }
+  const first = byId.entries().next().value;
+  if (first === void 0) {
+    throw new Error(`Approval not found: ${input}`);
+  }
+  const [id, location] = first;
+  return { id, location };
+}
+function isApprovalEvent(ev) {
+  return ev.type === "approval_requested" || ev.type === "approval_approved" || ev.type === "approval_rejected" || ev.type === "approval_expired";
+}
+function printApprovalListText(records) {
+  const allIds = records.map((r) => r.approval.id);
+  const shortLen = computeUniquePrefixLen(allIds);
+  const rows = records.map((r) => {
+    const sid = sliceShort(r.approval.id, shortLen);
+    const status = r.lazyExpired ? `${r.approval.status} (expired)` : r.approval.status;
+    const risk = r.approval.risk_level;
+    const action = r.approval.action.kind;
+    const createdAt = r.approval.created_at;
+    const reason = truncate(r.approval.reason, REASON_TEXT_MAX_LEN);
+    return { sid, status, risk, action, createdAt, reason };
+  });
+  const widths = {
+    sid: maxLen(
+      rows.map((r) => r.sid),
+      "SHORT_ID".length
+    ),
+    status: maxLen(
+      rows.map((r) => r.status),
+      "STATUS".length
+    ),
+    risk: maxLen(
+      rows.map((r) => r.risk),
+      "RISK".length
+    ),
+    action: maxLen(
+      rows.map((r) => r.action),
+      "ACTION".length
+    ),
+    createdAt: maxLen(
+      rows.map((r) => r.createdAt),
+      "CREATED_AT".length
+    )
+  };
+  console.log(
+    `${pad("SHORT_ID", widths.sid)}  ${pad("STATUS", widths.status)}  ${pad("RISK", widths.risk)}  ${pad("ACTION", widths.action)}  ${pad("CREATED_AT", widths.createdAt)}  REASON`
+  );
+  for (const row of rows) {
+    console.log(
+      `${pad(row.sid, widths.sid)}  ${pad(row.status, widths.status)}  ${pad(row.risk, widths.risk)}  ${pad(row.action, widths.action)}  ${pad(row.createdAt, widths.createdAt)}  ${row.reason}`
+    );
+  }
+}
+function printApprovalShowText(approval, _location, events, lazyExpired) {
+  console.log(`Approval: ${approval.id}  (status: ${approval.status})`);
+  console.log(`Session:        ${approval.session_id}`);
+  console.log(`Created at:     ${approval.created_at}`);
+  console.log(`Risk level:     ${approval.risk_level}`);
+  console.log(`Action:         ${formatActionLine(approval.action)}`);
+  console.log(`Reason:         ${approval.reason}`);
+  const expiresLabel = formatExpiresLabel(approval.expires_at, lazyExpired);
+  console.log(`Expires at:     ${expiresLabel}`);
+  console.log(`Resolver:       ${approval.resolver ?? "(none)"}`);
+  console.log(`Resolved at:    ${approval.resolved_at ?? "(none)"}`);
+  console.log(`Note:           ${approval.note ?? "(none)"}`);
+  console.log(`Rejection reason: ${approval.rejection_reason ?? "(none)"}`);
+  console.log("");
+  console.log(`Related events: ${events.length} total`);
+  for (const ev of events) {
+    console.log(`  ${formatApprovalEventLine(ev)}`);
+  }
+}
+function formatActionLine(action) {
+  const extras = [];
+  for (const [key, value] of Object.entries(action)) {
+    if (key === "kind") continue;
+    if (typeof value !== "string") continue;
+    extras.push(`${key}="${truncate(value, ACTION_KEY_DETAIL_MAX_LEN)}"`);
+    if (extras.length >= 2) break;
+  }
+  return extras.length === 0 ? action.kind : `${action.kind} (${extras.join(", ")})`;
+}
+function formatExpiresLabel(expiresAt, lazyExpired) {
+  if (expiresAt === null) return "(none)";
+  return lazyExpired ? `${expiresAt} (expired)` : expiresAt;
+}
+function formatApprovalEventLine(ev) {
+  const summary = approvalEventSummary(ev);
+  return `${ev.occurred_at} [${ev.source}]  ${ev.type}  ${summary}`;
+}
+function approvalEventSummary(ev) {
+  switch (ev.type) {
+    case "approval_requested":
+      return `${ev.action.kind} risk=${ev.risk_level}`;
+    case "approval_approved":
+      return ev.resolver !== void 0 ? `by ${ev.resolver}` : "(approved)";
+    case "approval_rejected":
+      return ev.resolver !== void 0 ? `by ${ev.resolver}: ${ev.reason}` : ev.reason;
+    case "approval_expired":
+      return `approval=${ev.approval_id}`;
+    default:
+      return "";
+  }
+}
+function shortId(id) {
+  return sliceShort(id, SHORT_ID_BASE_LEN);
+}
+var KNOWN_ID_PREFIXES = ["appr_", "ses_", "evt_", "ws_", "task_", "decision_"];
+function sliceShort(id, len) {
+  for (const prefix of KNOWN_ID_PREFIXES) {
+    if (id.startsWith(prefix)) {
+      return id.slice(prefix.length, prefix.length + len);
+    }
+  }
+  return id.slice(0, len);
+}
+function computeUniquePrefixLen(ids) {
+  if (ids.length <= 1) return SHORT_ID_BASE_LEN;
+  for (let len = SHORT_ID_BASE_LEN; len <= SHORT_ID_MAX_LEN; len += 2) {
+    const seen = /* @__PURE__ */ new Set();
+    let collided = false;
+    for (const id of ids) {
+      const key = sliceShort(id, len);
+      if (seen.has(key)) {
+        collided = true;
+        break;
+      }
+      seen.add(key);
+    }
+    if (!collided) return len;
+  }
+  return SHORT_ID_MAX_LEN;
+}
+function pad(value, width) {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+function maxLen(values, floor) {
+  let max = floor;
+  for (const v of values) if (v.length > max) max = v.length;
+  return max;
+}
+function truncate(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength - 3)}...`;
+}
+async function resolveRepositoryRootForApproval(cwd, subcmd) {
+  try {
+    return await resolveRepositoryRoot(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        `Not a git repository. Run 'git init' first, then re-run 'basou approval ${subcmd}'.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized(basouRoot) {
+  try {
+    await assertBasouRootSafe(basouRoot);
+  } catch (error) {
+    if (findErrorCode(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+function describeReadError(error) {
+  if (error instanceof Error) {
+    if (error.message === "YAML file not found") return "approval YAML not found";
+    if (error.message === "Failed to parse YAML content") return "invalid YAML";
+    return error.message;
+  }
+  return String(error);
+}
+function parseApprovalStatus(raw) {
+  const result = ApprovalStatusSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(`Invalid approval status: ${raw}. Valid values: ${STATUS_VALUES.join(", ")}`);
+  }
+  return result.data;
+}
+function printNoApprovals(options) {
+  if (options.json === true) {
+    console.log("[]");
+  } else {
+    console.log("No approvals found.");
+  }
+}
+
+// src/commands/decision.ts
+import {
+  acquireLock,
+  appendEventToExistingSession,
+  assertBasouRootSafe as assertBasouRootSafe2,
+  basouPaths as basouPaths2,
+  createAdHocSessionWithEvent,
+  findErrorCode as findErrorCode2,
+  prefixedUlid as prefixedUlid2,
+  readManifest,
+  resolveRepositoryRoot as resolveRepositoryRoot2,
+  resolveSessionId
+} from "@basou/core";
+import { InvalidArgumentError } from "commander";
+var LABEL_TITLE_MAX = 80;
+var LABEL_TRUNCATE_HEAD = LABEL_TITLE_MAX - 3;
+function registerDecisionCommand(program2) {
+  const decision = program2.command("decision").description("Record human-authored decisions as events");
+  decision.command("record").description("Record a decision_recorded event").requiredOption("--title <text>", "Decision title", parseTitle).option("--rationale <text>", "Rationale for the decision", parseRationale).option(
+    "--rejected-reason <text>",
+    "Reason rejected alternatives were not chosen",
+    parseRejectedReason
+  ).option(
+    "--alternative <text>",
+    "Alternative considered (repeatable: --alternative yup --alternative joi)",
+    collectAlternative,
+    []
+  ).option(
+    "--linked-event <event_id>",
+    "Related event id (repeatable). Schema only checks the prefix; existence is verified at render time.",
+    collectLinkedEvent,
+    []
+  ).option(
+    "--linked-file <path>",
+    "Related file path (repeatable). Path is opaque; existence is verified at render time.",
+    collectLinkedFile,
+    []
+  ).option(
+    "--session <session_id>",
+    "Attach to an existing session; otherwise an ad-hoc session is created"
+  ).option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runDecisionRecord(options);
+  });
+}
+async function runDecisionRecord(options, ctx = {}) {
+  try {
+    await doRunDecisionRecord(options, ctx);
+  } catch (error) {
+    renderCliError(error, {
+      verbose: isVerbose(options),
+      classifiers: [failedToFinalizeClassifier]
+    });
+    process.exitCode = 1;
+  }
+}
+async function doRunDecisionRecord(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForDecision(cwd);
+  const paths = basouPaths2(repositoryRoot);
+  await assertWorkspaceInitialized2(paths.root);
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const decisionId = prefixedUlid2("decision");
+  const rich = pickRichFields(options);
+  if (options.session !== void 0) {
+    const sessionId = await resolveSessionId(paths, options.session);
+    const sesId = sessionId;
+    const sessionLock = await acquireLock(paths, "session", sesId);
+    let result;
+    try {
+      result = await appendEventToExistingSession({
+        paths,
+        sessionId: sesId,
+        eventBuilder: (eventId) => buildDecisionEvent({
+          eventId,
+          sessionId: sesId,
+          decisionId,
+          title: options.title,
+          occurredAt,
+          rich
+        })
+      });
+    } finally {
+      await sessionLock.release();
+    }
+    printDecisionResult(options, {
+      mode: "attached",
+      sessionId,
+      decisionId,
+      eventId: result.eventId,
+      sessionStatus: result.sessionStatus,
+      title: options.title,
+      rich
+    });
+    return;
+  }
+  const manifest = await readManifest(paths);
+  const adHoc = await createAdHocSessionWithEvent({
+    paths,
+    manifest,
+    label: buildAdHocLabel(options.title),
+    occurredAt,
+    sessionSource: "human",
+    workingDirectory: repositoryRoot,
+    invocation: {
+      command: "basou decision record",
+      args: ["--title", options.title]
+    },
+    targetEventBuilders: [
+      (sessionId, eventId) => buildDecisionEvent({
+        eventId,
+        sessionId,
+        decisionId,
+        title: options.title,
+        occurredAt,
+        rich
+      })
+    ]
+  });
+  printDecisionResult(options, {
+    mode: "ad-hoc",
+    sessionId: adHoc.sessionId,
+    decisionId,
+    eventId: adHoc.targetEventIds[0],
+    sessionStatus: "completed",
+    title: options.title,
+    rich
+  });
+}
+function pickRichFields(options) {
+  const out = {};
+  if (options.rationale !== void 0) out.rationale = options.rationale;
+  if (options.rejectedReason !== void 0) out.rejected_reason = options.rejectedReason;
+  if (options.alternative !== void 0 && options.alternative.length > 0) {
+    out.alternatives = [...options.alternative];
+  }
+  if (options.linkedEvent !== void 0 && options.linkedEvent.length > 0) {
+    out.linked_events = [...options.linkedEvent];
+  }
+  if (options.linkedFile !== void 0 && options.linkedFile.length > 0) {
+    out.linked_files = [...options.linkedFile];
+  }
+  return out;
+}
+function buildDecisionEvent(input) {
+  return {
+    schema_version: "0.1.0",
+    id: input.eventId,
+    session_id: input.sessionId,
+    occurred_at: input.occurredAt,
+    source: "local-cli",
+    type: "decision_recorded",
+    decision_id: input.decisionId,
+    title: input.title,
+    ...input.rich.rationale !== void 0 ? { rationale: input.rich.rationale } : {},
+    ...input.rich.alternatives !== void 0 ? { alternatives: input.rich.alternatives } : {},
+    ...input.rich.rejected_reason !== void 0 ? { rejected_reason: input.rich.rejected_reason } : {},
+    ...input.rich.linked_events !== void 0 ? { linked_events: input.rich.linked_events } : {},
+    ...input.rich.linked_files !== void 0 ? { linked_files: input.rich.linked_files } : {}
+  };
+}
+function buildAdHocLabel(title) {
+  const truncated = title.length > LABEL_TITLE_MAX ? `${title.slice(0, LABEL_TRUNCATE_HEAD)}...` : title;
+  return `Ad-hoc decision: ${truncated}`;
+}
+function parseTitle(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError("Title must not be empty");
+  }
+  return raw;
+}
+function parseRationale(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError("Rationale must not be empty");
+  }
+  return raw;
+}
+function parseRejectedReason(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError("Rejected reason must not be empty");
+  }
+  return raw;
+}
+function collectAlternative(value, prev) {
+  if (value.length === 0) {
+    throw new InvalidArgumentError("Alternative must not be empty");
+  }
+  return prev.concat(value);
+}
+var EVENT_ID_RE = /^evt_[A-Z0-9]+$/;
+function collectLinkedEvent(value, prev) {
+  if (!EVENT_ID_RE.test(value)) {
+    throw new InvalidArgumentError(`Linked event id must match evt_<ULID>, got '${value}'`);
+  }
+  return prev.concat(value);
+}
+function collectLinkedFile(value, prev) {
+  if (value.length === 0) {
+    throw new InvalidArgumentError("Linked file path must not be empty");
+  }
+  if (value.length > 4096) {
+    throw new InvalidArgumentError("Linked file path exceeds 4096 chars");
+  }
+  return prev.concat(value);
+}
+function printDecisionResult(options, result) {
+  const sid = shortSessionId(result.sessionId);
+  if (options.json === true) {
+    const payload = {
+      decision_id: result.decisionId,
+      event_id: result.eventId,
+      session_id: result.sessionId,
+      session_status: result.sessionStatus,
+      mode: result.mode,
+      title: result.title
+    };
+    if (result.rich.rationale !== void 0) payload.rationale = result.rich.rationale;
+    if (result.rich.alternatives !== void 0) payload.alternatives = result.rich.alternatives;
+    if (result.rich.rejected_reason !== void 0) {
+      payload.rejected_reason = result.rich.rejected_reason;
+    }
+    if (result.rich.linked_events !== void 0) payload.linked_events = result.rich.linked_events;
+    if (result.rich.linked_files !== void 0) payload.linked_files = result.rich.linked_files;
+    console.log(JSON.stringify(payload));
+    return;
+  }
+  const rationaleSuffix = result.rich.rationale !== void 0 ? ` (rationale: ${result.rich.rationale})` : "";
+  if (result.mode === "ad-hoc") {
+    console.log(`Recorded ${result.decisionId} in ad-hoc session ${sid}${rationaleSuffix}`);
+  } else {
+    console.log(
+      `Recorded ${result.decisionId} in session ${sid} (${result.sessionStatus})${rationaleSuffix}`
+    );
+  }
+}
+async function resolveRepositoryRootForDecision(cwd) {
+  try {
+    return await resolveRepositoryRoot2(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        "Not a git repository. Run 'git init' first, then re-run 'basou decision record'.",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized2(basouRoot) {
+  try {
+    await assertBasouRootSafe2(basouRoot);
+  } catch (error) {
+    if (findErrorCode2(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+
+// src/commands/decisions.ts
+import {
+  assertBasouRootSafe as assertBasouRootSafe3,
+  basouPaths as basouPaths3,
+  findErrorCode as findErrorCode3,
+  readMarkdownFile,
+  renderDecisions,
+  renderWithMarkers,
+  resolveRepositoryRoot as resolveRepositoryRoot3,
+  writeMarkdownFile
+} from "@basou/core";
+function registerDecisionsCommand(program2) {
+  const decisions = program2.command("decisions").description("Generate or inspect .basou/decisions.md");
+  decisions.command("generate").description("Regenerate .basou/decisions.md from recorded decision events").option("-v, --verbose", "Show error causes").action(async (opts) => {
+    await runDecisionsGenerate(opts);
+  });
+}
+async function runDecisionsGenerate(options, ctx = {}) {
+  try {
+    await doRunDecisionsGenerate(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunDecisionsGenerate(options, ctx) {
+  void options;
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForDecisions(cwd);
+  const paths = basouPaths3(repositoryRoot);
+  await assertWorkspaceInitialized3(paths.root);
+  const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
+  const result = await renderDecisions({
+    paths,
+    nowIso,
+    onWarning: (w, sid) => printReplayWarning(w, sid),
+    onSessionSkip: (sid, reason) => printSessionSkip(sid, reason)
+  });
+  const existing = await readMarkdownFile(paths.files.decisions);
+  const finalBody = renderWithMarkers(existing, result.body, "decisions.md");
+  await writeMarkdownFile(paths.files.decisions, finalBody);
+  console.log(`Generated .basou/decisions.md (decisions: ${result.decisionCount})`);
+}
+async function resolveRepositoryRootForDecisions(cwd) {
+  try {
+    return await resolveRepositoryRoot3(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        "Not a git repository. Run 'git init' first, then re-run 'basou decisions generate'.",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized3(basouRoot) {
+  try {
+    await assertBasouRootSafe3(basouRoot);
+  } catch (error) {
+    if (findErrorCode3(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+
+// src/commands/exec.ts
+import { mkdir } from "fs/promises";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import {
+  ChildProcessRunner,
+  SessionSchema,
+  assertBasouRootSafe as assertBasouRootSafe4,
+  basouPaths as basouPaths4,
+  appendEvent as coreAppendEvent,
+  getSnapshot,
+  overwriteYamlFile,
+  parseDuration,
+  prefixedUlid as prefixedUlid3,
+  readManifest as readManifest2,
+  readYamlFile as readYamlFile2,
+  resolveRepositoryRoot as resolveRepositoryRoot4,
+  sanitizeWorkingDirectory,
+  writeYamlFile
+} from "@basou/core";
+function registerExecCommand(program2) {
+  program2.command("exec <command> [args...]").description("Execute a command and record it as a Basou session").passThroughOptions().option("--timeout <duration>", "Kill the child after this duration (e.g. 30s, 5m, 1h)").option("--no-snapshot", "Skip git_snapshot before/after the command").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes").action(async (command, args, options) => {
+    try {
+      const exitCode = await runExec(command, args, options);
+      process.exit(exitCode);
+    } catch (error) {
+      renderCliError(error, { verbose: isVerbose(options) });
+      process.exit(1);
+    }
+  });
+}
+async function runExec(command, args, options, ctx = {}) {
+  const runner = ctx.runner ?? new ChildProcessRunner();
+  const now = ctx.now ?? (() => /* @__PURE__ */ new Date());
+  const appendEvent2 = ctx.appendEvent ?? coreAppendEvent;
+  const cwd = options.cwd ?? process.cwd();
+  const timeout_ms = options.timeout !== void 0 ? parseDuration(options.timeout) : void 0;
+  const repoRoot = await resolveRepositoryRootForExec(cwd);
+  const paths = basouPaths4(repoRoot);
+  await assertBasouRootSafe4(paths.root);
+  const manifest = await readManifest2(paths);
+  const sessionId = prefixedUlid3("ses");
+  const sessionDir = join2(paths.sessions, sessionId);
+  await mkdir(sessionDir, { recursive: true });
+  const startedAt = now().toISOString();
+  const sessionYamlPath = join2(sessionDir, "session.yaml");
+  const session = buildInitialSession({
+    id: sessionId,
+    command,
+    args,
+    cwd,
+    workspaceId: manifest.workspace.id,
+    startedAt
+  });
+  await writeYamlFile(sessionYamlPath, session);
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_started",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: startedAt,
+    source: "terminal-recording"
+  });
+  if (options.snapshot !== false) {
+    await tryAppendGitSnapshot(sessionDir, sessionId, repoRoot, now, appendEvent2);
+  }
+  const runningAt = now().toISOString();
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: runningAt,
+    source: "terminal-recording",
+    from: "initialized",
+    to: "running"
+  });
+  await mutateSessionYaml(sessionYamlPath, (s) => {
+    s.session.status = "running";
+  });
+  const controller = new AbortController();
+  let signalReceived = null;
+  let activeChild = null;
+  const signalHandler = (sig) => {
+    if (signalReceived !== null) return;
+    signalReceived = sig;
+    controller.abort();
+  };
+  const exitHandler = () => {
+    if (activeChild !== null) {
+      try {
+        activeChild.kill("SIGKILL");
+      } catch {
+      }
+    }
+  };
+  const onSigInt = () => signalHandler("SIGINT");
+  const onSigTerm = () => signalHandler("SIGTERM");
+  process.on("SIGINT", onSigInt);
+  process.on("SIGTERM", onSigTerm);
+  process.on("exit", exitHandler);
+  ctx.onExitHookInstalled?.(exitHandler);
+  let result;
+  try {
+    try {
+      result = await runner.run(command, args, {
+        cwd,
+        capture: "none",
+        ...timeout_ms !== void 0 ? { timeout_ms } : {},
+        signal: controller.signal,
+        onSpawn: (child) => {
+          activeChild = child;
+        }
+      });
+    } catch (spawnError) {
+      await finalizeSessionAsFailed(sessionDir, sessionYamlPath, sessionId, appendEvent2, {
+        command,
+        args,
+        cwd,
+        occurredAt: now().toISOString(),
+        signalReceived
+      });
+      throw spawnError;
+    }
+  } finally {
+    process.off("SIGINT", onSigInt);
+    process.off("SIGTERM", onSigTerm);
+    process.off("exit", exitHandler);
+    activeChild = null;
+  }
+  const endedAt = now().toISOString();
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "command_executed",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: "terminal-recording",
+    command,
+    args,
+    cwd,
+    exit_code: result.exit_code,
+    ...result.signal !== null ? { signal: result.signal } : {},
+    ...signalReceived !== null ? { received_signal: signalReceived } : {},
+    duration_ms: result.duration_ms
+  });
+  if (options.snapshot !== false) {
+    await tryAppendGitSnapshot(sessionDir, sessionId, repoRoot, now, appendEvent2);
+  }
+  const finalStatus = decideFinalStatus(result, signalReceived);
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: "terminal-recording",
+    from: "running",
+    to: finalStatus
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_ended",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: "terminal-recording",
+    ...result.exit_code !== null ? { exit_code: result.exit_code } : {}
+  });
+  await mutateSessionYaml(sessionYamlPath, (s) => {
+    s.session.status = finalStatus;
+    s.session.ended_at = endedAt;
+    s.session.invocation.exit_code = result.exit_code;
+  });
+  if (result.exit_code !== null) {
+    return result.exit_code;
+  }
+  return signalToExitCode(signalReceived ?? result.signal);
+}
+function decideFinalStatus(result, signalReceived) {
+  if (signalReceived === "SIGINT" || signalReceived === "SIGTERM") return "interrupted";
+  if (result.signal === "SIGINT" || result.signal === "SIGTERM" || result.signal === "SIGKILL") {
+    return "interrupted";
+  }
+  if (result.exit_code === 0) return "completed";
+  return "failed";
+}
+var SIGNUM_MAP = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGKILL: 9,
+  SIGTERM: 15
+};
+function signalToExitCode(sig) {
+  if (sig === null) return 1;
+  const num = SIGNUM_MAP[sig] ?? 1;
+  return 128 + num;
+}
+async function tryAppendGitSnapshot(sessionDir, sessionId, repoRoot, now, appendEvent2) {
+  let snapshot;
+  try {
+    snapshot = await getSnapshot(repoRoot);
+  } catch (error) {
+    console.warn(normalizeGitSnapshotSkipMessage(error));
+    return;
+  }
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "git_snapshot",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: now().toISOString(),
+    source: "git-capability",
+    ...snapshot
+  });
+}
+function normalizeGitSnapshotSkipMessage(error) {
+  if (!(error instanceof Error)) {
+    return `git_snapshot skipped: ${String(error)}`;
+  }
+  const msg = error.message;
+  if (msg === "Not a git repository") {
+    return "git_snapshot skipped: not in a git repository";
+  }
+  if (msg === "Git executable not found in PATH. Install git first.") {
+    return "git_snapshot skipped: git executable not found";
+  }
+  if (msg === "No commits in repository") {
+    return "git_snapshot skipped: no commits in repository";
+  }
+  return `git_snapshot skipped: ${msg}`;
+}
+function buildInitialSession(input) {
+  const cmdline = [input.command, ...input.args].join(" ");
+  return {
+    schema_version: "0.1.0",
+    session: {
+      id: input.id,
+      label: `basou exec ${cmdline} (${input.startedAt})`,
+      task_id: null,
+      workspace_id: input.workspaceId,
+      source: { kind: "terminal", version: "0.1.0" },
+      started_at: input.startedAt,
+      status: "initialized",
+      working_directory: sanitizeWorkingDirectory(input.cwd, { homedir: homedir() }),
+      invocation: {
+        command: input.command,
+        args: [...input.args],
+        exit_code: null
+      },
+      related_files: [],
+      events_log: "events.jsonl"
+    }
+  };
+}
+async function mutateSessionYaml(filePath, mutator) {
+  const raw = await readYamlFile2(filePath);
+  const parsed = SessionSchema.parse(raw);
+  mutator(parsed);
+  const validated = SessionSchema.parse(parsed);
+  await overwriteYamlFile(filePath, validated);
+}
+async function finalizeSessionAsFailed(sessionDir, sessionYamlPath, sessionId, appendEvent2, ctx) {
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "command_executed",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: "terminal-recording",
+    command: ctx.command,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    exit_code: null,
+    signal: null,
+    ...ctx.signalReceived !== null ? { received_signal: ctx.signalReceived } : {},
+    duration_ms: 0
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: "terminal-recording",
+    from: "running",
+    to: "failed"
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_ended",
+    id: prefixedUlid3("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: "terminal-recording"
+  });
+  await mutateSessionYaml(sessionYamlPath, (s) => {
+    s.session.status = "failed";
+    s.session.ended_at = ctx.occurredAt;
+    s.session.invocation.exit_code = null;
+  });
+}
+async function resolveRepositoryRootForExec(cwd) {
+  try {
+    return await resolveRepositoryRoot4(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou exec'.", {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+
+// src/commands/handoff.ts
+import {
+  assertBasouRootSafe as assertBasouRootSafe5,
+  basouPaths as basouPaths5,
+  findErrorCode as findErrorCode4,
+  readMarkdownFile as readMarkdownFile2,
+  renderHandoff,
+  renderWithMarkers as renderWithMarkers2,
+  resolveRepositoryRoot as resolveRepositoryRoot5,
+  writeMarkdownFile as writeMarkdownFile2
+} from "@basou/core";
+function registerHandoffCommand(program2) {
+  const handoff = program2.command("handoff").description("Generate or inspect .basou/handoff.md");
+  handoff.command("generate").description("Regenerate .basou/handoff.md from current session state").option("-v, --verbose", "Show error causes").action(async (opts) => {
+    await runHandoffGenerate(opts);
+  });
+}
+async function runHandoffGenerate(options, ctx = {}) {
+  try {
+    await doRunHandoffGenerate(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunHandoffGenerate(options, ctx) {
+  void options;
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForHandoff(cwd);
+  const paths = basouPaths5(repositoryRoot);
+  await assertWorkspaceInitialized4(paths.root);
+  const nowIso = (ctx.nowProvider?.() ?? /* @__PURE__ */ new Date()).toISOString();
+  const result = await renderHandoff({
+    paths,
+    nowIso,
+    onWarning: (w, sid) => printReplayWarning(w, sid),
+    onSessionSkip: (sid, reason) => printSessionSkip(sid, reason),
+    onTaskSkip: (taskId, reason) => printTaskSkip(taskId, reason)
+  });
+  const existing = await readMarkdownFile2(paths.files.handoff);
+  const finalBody = renderWithMarkers2(existing, result.body, "handoff.md");
+  await writeMarkdownFile2(paths.files.handoff, finalBody);
+  console.log(
+    `Generated .basou/handoff.md (sessions: ${result.sessionCount}, tasks: ${result.taskCount}, decisions: ${result.decisionCount}, pending approvals: ${result.pendingApprovalsCount})`
+  );
+}
+async function resolveRepositoryRootForHandoff(cwd) {
+  try {
+    return await resolveRepositoryRoot5(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        "Not a git repository. Run 'git init' first, then re-run 'basou handoff generate'.",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized4(basouRoot) {
+  try {
+    await assertBasouRootSafe5(basouRoot);
+  } catch (error) {
+    if (findErrorCode4(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+
+// src/commands/init.ts
+import { basename } from "path";
+import {
+  appendBasouGitignore,
+  createManifest,
+  ensureBasouDirectory,
+  resolveRepositoryRoot as resolveRepositoryRoot6,
+  tryRemoteUrl,
+  writeManifest
+} from "@basou/core";
+function registerInitCommand(program2) {
+  program2.command("init").description("Initialize a Basou workspace at the current Git repository root").option("--name <name>", "Workspace name (defaults to the repository directory name)").option("--project-name <name>", "Project display name").option("--project-description <description>", "Project description").option(
+    "--repo-url <url>",
+    "Repository URL (defaults to git remote.origin.url; pass empty string for null)"
+  ).option("-f, --force", "Overwrite an existing manifest").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runInit(options);
+  });
+}
+async function runInit(options, ctx = {}) {
+  try {
+    await doRunInit(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunInit(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForInit(cwd);
+  const workspaceName = options.name ?? basename(repositoryRoot);
+  let repositoryUrl;
+  if (options.repoUrl !== void 0) {
+    repositoryUrl = options.repoUrl === "" ? null : options.repoUrl;
+  } else {
+    repositoryUrl = await tryRemoteUrl(repositoryRoot);
+  }
+  const paths = await ensureBasouDirectory(repositoryRoot);
+  const manifest = createManifest({
+    workspaceName,
+    ...options.projectName !== void 0 ? { projectName: options.projectName } : {},
+    ...options.projectDescription !== void 0 ? { projectDescription: options.projectDescription } : {},
+    ...repositoryUrl !== void 0 ? { repositoryUrl } : {}
+  });
+  await writeManifest(paths, manifest, { force: options.force === true });
+  try {
+    await appendBasouGitignore(repositoryRoot);
+  } catch (error) {
+    renderGitignoreWarning(error, isVerbose(options));
+  }
+  console.log(`Initialized Basou workspace: ${manifest.workspace.id}`);
+}
+function renderGitignoreWarning(error, verbose) {
+  const baseMessage = error instanceof Error ? error.message : String(error);
+  console.error(
+    `Warning: Could not update .gitignore (${baseMessage}). Add Basou's default .gitignore block manually.`
+  );
+  if (verbose && error instanceof Error) {
+    const label = extractCauseLabel(error);
+    if (label !== void 0) console.error(`Caused by: ${label}`);
+  }
+}
+async function resolveRepositoryRootForInit(cwd) {
+  try {
+    return await resolveRepositoryRoot6(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou init'.", {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+
+// src/commands/run.ts
+import { mkdir as mkdir2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+import {
+  ChildProcessRunner as ChildProcessRunner2,
+  SessionSchema as SessionSchema2,
+  assertBasouRootSafe as assertBasouRootSafe6,
+  basouPaths as basouPaths6,
+  claudeCodeAdapterMetadata,
+  appendEvent as coreAppendEvent2,
+  getDiff,
+  getSnapshot as getSnapshot2,
+  overwriteYamlFile as overwriteYamlFile2,
+  prefixedUlid as prefixedUlid4,
+  readManifest as readManifest3,
+  readYamlFile as readYamlFile3,
+  resolveClaudeCodeCommand,
+  resolveRepositoryRoot as resolveRepositoryRoot7,
+  sanitizeRelatedFiles,
+  sanitizeWorkingDirectory as sanitizeWorkingDirectory2,
+  writeYamlFile as writeYamlFile2
+} from "@basou/core";
+function registerRunCommand(program2, ctx = {}) {
+  const runCommand = program2.command("run").description("Run an AI coding tool through Basou as a tracked session").enablePositionalOptions().option("--no-snapshot", "Skip git_snapshot before/after the session").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes");
+  runCommand.command("claude-code [args...]").description("Run Claude Code CLI as a Basou-tracked session").option("--no-snapshot", "Skip git_snapshot before/after the session").option("--cwd <path>", "Run from a Basou root other than process.cwd()").option("-v, --verbose", "Show error causes").passThroughOptions().action(async (args, options, command) => {
+    const parentOptions = command.parent?.opts() ?? {};
+    const snapshotOn = parentOptions.snapshot !== false && options.snapshot !== false;
+    const merged = {
+      ...parentOptions,
+      ...options,
+      snapshot: snapshotOn
+    };
+    try {
+      const exitCode = await runClaudeCode(args, merged, ctx);
+      process.exit(exitCode);
+    } catch (error) {
+      renderCliError(error, { verbose: isVerbose(merged) });
+      process.exit(1);
+    }
+  });
+}
+async function runClaudeCode(args, options, ctx = {}) {
+  const runner = ctx.runner ?? new ChildProcessRunner2();
+  const now = ctx.now ?? (() => /* @__PURE__ */ new Date());
+  const appendEvent2 = ctx.appendEvent ?? coreAppendEvent2;
+  const resolveCommand = ctx.resolveCommand ?? resolveClaudeCodeCommand;
+  const getDiffFn = ctx.getDiff ?? getDiff;
+  const { command } = await resolveCommand();
+  const cwd = options.cwd ?? process.cwd();
+  const repoRoot = await resolveRepositoryRootForRun(cwd);
+  const paths = basouPaths6(repoRoot);
+  await assertBasouRootSafe6(paths.root);
+  const manifest = await readManifest3(paths);
+  const sessionId = prefixedUlid4("ses");
+  const sessionDir = join3(paths.sessions, sessionId);
+  await mkdir2(sessionDir, { recursive: true });
+  const startedAt = now().toISOString();
+  const sessionYamlPath = join3(sessionDir, "session.yaml");
+  const session = buildInitialSession2({
+    id: sessionId,
+    command,
+    args,
+    cwd: repoRoot,
+    workspaceId: manifest.workspace.id,
+    startedAt
+  });
+  await writeYamlFile2(sessionYamlPath, session);
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_started",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: startedAt,
+    source: claudeCodeAdapterMetadata.kind
+  });
+  let preSnapshot = null;
+  if (options.snapshot !== false) {
+    preSnapshot = await tryAppendGitSnapshot2(sessionDir, sessionId, repoRoot, now, appendEvent2);
+  }
+  const runningAt = now().toISOString();
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: runningAt,
+    source: claudeCodeAdapterMetadata.kind,
+    from: "initialized",
+    to: "running"
+  });
+  await mutateSessionYaml2(sessionYamlPath, (s) => {
+    s.session.status = "running";
+  });
+  const controller = new AbortController();
+  let signalReceived = null;
+  let activeChild = null;
+  const signalHandler = (sig) => {
+    if (signalReceived !== null) return;
+    signalReceived = sig;
+    controller.abort();
+  };
+  const exitHandler = () => {
+    if (activeChild !== null) {
+      try {
+        activeChild.kill("SIGKILL");
+      } catch {
+      }
+    }
+  };
+  const onSigInt = () => signalHandler("SIGINT");
+  const onSigTerm = () => signalHandler("SIGTERM");
+  process.on("SIGINT", onSigInt);
+  process.on("SIGTERM", onSigTerm);
+  process.on("exit", exitHandler);
+  ctx.onExitHookInstalled?.(exitHandler);
+  let result;
+  try {
+    try {
+      result = await runner.run(command, args, {
+        cwd: repoRoot,
+        capture: "none",
+        signal: controller.signal,
+        onSpawn: (child) => {
+          activeChild = child;
+        }
+      });
+    } catch (spawnError) {
+      await finalizeSessionAsFailed2(sessionDir, sessionYamlPath, sessionId, appendEvent2, {
+        command,
+        args,
+        cwd: repoRoot,
+        occurredAt: now().toISOString(),
+        signalReceived
+      });
+      throw spawnError;
+    }
+  } finally {
+    process.off("SIGINT", onSigInt);
+    process.off("SIGTERM", onSigTerm);
+    process.off("exit", exitHandler);
+    activeChild = null;
+  }
+  const endedAt = now().toISOString();
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "command_executed",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: "terminal-recording",
+    command,
+    args,
+    cwd: repoRoot,
+    exit_code: result.exit_code,
+    ...result.signal !== null ? { signal: result.signal } : {},
+    ...signalReceived !== null ? { received_signal: signalReceived } : {},
+    duration_ms: result.duration_ms
+  });
+  let postSnapshot = null;
+  if (options.snapshot !== false) {
+    postSnapshot = await tryAppendGitSnapshot2(sessionDir, sessionId, repoRoot, now, appendEvent2);
+  }
+  let diff = null;
+  if (preSnapshot !== null && postSnapshot !== null) {
+    diff = await tryAppendFileChangedEvents(
+      sessionDir,
+      sessionId,
+      repoRoot,
+      preSnapshot.head,
+      postSnapshot.head,
+      now().toISOString(),
+      appendEvent2,
+      getDiffFn
+    );
+  }
+  const rawRelated = computeRelatedFiles(preSnapshot, postSnapshot, diff);
+  const relatedFiles = sanitizeRelatedFiles(rawRelated, {
+    workingDirectory: repoRoot,
+    homedir: homedir2()
+  }).sanitized;
+  const finalStatus = decideFinalStatus2(result, signalReceived);
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: claudeCodeAdapterMetadata.kind,
+    from: "running",
+    to: finalStatus
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_ended",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: endedAt,
+    source: claudeCodeAdapterMetadata.kind,
+    ...result.exit_code !== null ? { exit_code: result.exit_code } : {}
+  });
+  await mutateSessionYaml2(sessionYamlPath, (s) => {
+    s.session.status = finalStatus;
+    s.session.ended_at = endedAt;
+    s.session.invocation.exit_code = result.exit_code;
+    s.session.related_files = relatedFiles;
+  });
+  if (result.exit_code !== null) return result.exit_code;
+  return signalToExitCode2(signalReceived ?? result.signal);
+}
+function decideFinalStatus2(result, signalReceived) {
+  if (signalReceived === "SIGINT" || signalReceived === "SIGTERM") return "interrupted";
+  if (result.signal === "SIGINT" || result.signal === "SIGTERM" || result.signal === "SIGKILL") {
+    return "interrupted";
+  }
+  if (result.exit_code === 0) return "completed";
+  return "failed";
+}
+var SIGNUM_MAP2 = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGKILL: 9,
+  SIGTERM: 15
+};
+function signalToExitCode2(sig) {
+  if (sig === null) return 1;
+  const num = SIGNUM_MAP2[sig] ?? 1;
+  return 128 + num;
+}
+async function tryAppendGitSnapshot2(sessionDir, sessionId, repoRoot, now, appendEvent2) {
+  let snapshot;
+  try {
+    snapshot = await getSnapshot2(repoRoot);
+  } catch (error) {
+    console.warn(normalizeGitSnapshotSkipMessage2(error));
+    return null;
+  }
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "git_snapshot",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: now().toISOString(),
+    source: "git-capability",
+    ...snapshot
+  });
+  return snapshot;
+}
+async function tryAppendFileChangedEvents(sessionDir, sessionId, repoRoot, baseRef, headRef, occurredAt, appendEvent2, getDiffFn) {
+  let diff;
+  try {
+    diff = await getDiffFn(repoRoot, baseRef, headRef);
+  } catch (error) {
+    console.warn(normalizeFileChangedSkipMessage(error));
+    return null;
+  }
+  for (const change of diff.changed_files) {
+    await appendEvent2(sessionDir, {
+      schema_version: "0.1.0",
+      type: "file_changed",
+      id: prefixedUlid4("evt"),
+      session_id: sessionId,
+      occurred_at: occurredAt,
+      source: "git-capability",
+      path: change.path,
+      change_type: change.status,
+      ...change.old_path !== void 0 ? { old_path: change.old_path } : {}
+    });
+  }
+  return diff;
+}
+function computeRelatedFiles(preSnapshot, postSnapshot, diff) {
+  const set = /* @__PURE__ */ new Set();
+  for (const snap of [preSnapshot, postSnapshot]) {
+    if (snap === null) continue;
+    for (const p of snap.staged) set.add(p);
+    for (const p of snap.unstaged) set.add(p);
+    for (const p of snap.untracked) set.add(p);
+  }
+  if (diff !== null) {
+    for (const change of diff.changed_files) set.add(change.path);
+  }
+  return [...set].sort();
+}
+function normalizeGitSnapshotSkipMessage2(error) {
+  if (!(error instanceof Error)) {
+    return `git_snapshot skipped: ${String(error)}`;
+  }
+  const msg = error.message;
+  if (msg === "Not a git repository") return "git_snapshot skipped: not in a git repository";
+  if (msg === "Git executable not found in PATH. Install git first.") {
+    return "git_snapshot skipped: git executable not found";
+  }
+  if (msg === "No commits in repository") return "git_snapshot skipped: no commits in repository";
+  return `git_snapshot skipped: ${msg}`;
+}
+function normalizeFileChangedSkipMessage(error) {
+  if (!(error instanceof Error)) {
+    return `file_changed skipped: ${String(error)}`;
+  }
+  const msg = error.message;
+  if (msg === "Not a git repository") return "file_changed skipped: not in a git repository";
+  if (msg === "Git executable not found in PATH. Install git first.") {
+    return "file_changed skipped: git executable not found";
+  }
+  if (msg === "Invalid ref") return "file_changed skipped: invalid git ref";
+  if (msg === "Failed to compute git diff")
+    return "file_changed skipped: failed to compute git diff";
+  return `file_changed skipped: ${msg}`;
+}
+function buildInitialSession2(input) {
+  const cmdline = [input.command, ...input.args].join(" ");
+  return {
+    schema_version: "0.1.0",
+    session: {
+      id: input.id,
+      label: `basou run ${cmdline} (${input.startedAt})`,
+      task_id: null,
+      workspace_id: input.workspaceId,
+      source: { ...claudeCodeAdapterMetadata },
+      started_at: input.startedAt,
+      status: "initialized",
+      working_directory: sanitizeWorkingDirectory2(input.cwd, { homedir: homedir2() }),
+      invocation: {
+        command: input.command,
+        args: [...input.args],
+        exit_code: null
+      },
+      related_files: [],
+      events_log: "events.jsonl"
+    }
+  };
+}
+async function mutateSessionYaml2(filePath, mutator) {
+  const raw = await readYamlFile3(filePath);
+  const parsed = SessionSchema2.parse(raw);
+  mutator(parsed);
+  const validated = SessionSchema2.parse(parsed);
+  await overwriteYamlFile2(filePath, validated);
+}
+async function finalizeSessionAsFailed2(sessionDir, sessionYamlPath, sessionId, appendEvent2, ctx) {
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "command_executed",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: "terminal-recording",
+    command: ctx.command,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    exit_code: null,
+    signal: null,
+    ...ctx.signalReceived !== null ? { received_signal: ctx.signalReceived } : {},
+    duration_ms: 0
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_status_changed",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: claudeCodeAdapterMetadata.kind,
+    from: "running",
+    to: "failed"
+  });
+  await appendEvent2(sessionDir, {
+    schema_version: "0.1.0",
+    type: "session_ended",
+    id: prefixedUlid4("evt"),
+    session_id: sessionId,
+    occurred_at: ctx.occurredAt,
+    source: claudeCodeAdapterMetadata.kind
+  });
+  await mutateSessionYaml2(sessionYamlPath, (s) => {
+    s.session.status = "failed";
+    s.session.ended_at = ctx.occurredAt;
+    s.session.invocation.exit_code = null;
+  });
+}
+async function resolveRepositoryRootForRun(cwd) {
+  try {
+    return await resolveRepositoryRoot7(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou run'.", {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+
+// src/commands/session.ts
+import { readFile } from "fs/promises";
+import { basename as basename2, isAbsolute, join as join4, relative } from "path";
+import {
+  SessionImportPayloadSchema,
+  SessionSchema as SessionSchema3,
+  SessionStatusSchema,
+  acquireLock as acquireLock2,
+  appendEventToExistingSession as appendEventToExistingSession2,
+  assertBasouRootSafe as assertBasouRootSafe7,
+  basouPaths as basouPaths7,
+  findErrorCode as findErrorCode5,
+  importSessionFromJson,
+  loadSessionEntries,
+  readAllEvents,
+  readManifest as readManifest4,
+  readYamlFile as readYamlFile4,
+  resolveRepositoryRoot as resolveRepositoryRoot8,
+  resolveSessionId as resolveSessionId2,
+  resolveTaskId
+} from "@basou/core";
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+var SES_PREFIX2 = "ses_";
+var TASK_PREFIX2 = "task_";
+var SHORT_ID_BASE_LEN2 = 6;
+var SHORT_ID_MAX_LEN2 = 26;
+var STATUS_VALUES2 = SessionStatusSchema.options;
+function registerSessionCommand(program2) {
+  const session = program2.command("session").description("Inspect Basou sessions stored under .basou/sessions/");
+  session.command("list").description("List sessions in the current workspace (newest first)").option("--json", "Output the list as a JSON array").option(
+    "--status <state>",
+    `Filter by session status (one of: ${STATUS_VALUES2.join(", ")})`,
+    parseSessionStatus
+  ).option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runSessionList(options);
+  });
+  session.command("show <id>").description("Show a session's metadata and recent events").option("--json", "Output the session and events as JSON").option("--events", "List all events instead of just the trailing few").option("--last <n>", "Number of trailing events to display (default: 5)", parsePositiveInt).option(
+    "--full-path",
+    "Show working_directory as an absolute path instead of repository-relative"
+  ).option("-v, --verbose", "Show error causes").action(async (id, options) => {
+    await runSessionShow(id, options);
+  });
+  session.command("import").description("Import a session from a JSON file").requiredOption("--format <format>", "Input format (currently only 'json')", parseImportFormat).requiredOption("--from <path>", "Path to the input JSON file").option("--label <text>", "Override the session label", parseLabelOverride).option("--task <task_id>", "Override the session task_id", parseTaskIdOverride).option("--dry-run", "Validate input only; do not write to disk").option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runSessionImport(options);
+  });
+  session.command("note <session_id>").description("Append a note_added event to an existing session").option("--body <text>", "Note body (inline)", parseNoteBodyOption).option("--from-file <path>", "Read note body from a file").option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (sessionIdInput, options) => {
+    await runSessionNote(sessionIdInput, options);
+  });
+}
+async function runSessionList(options, ctx = {}) {
+  try {
+    await doRunSessionList(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunSessionList(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForSession(cwd, "list");
+  const paths = basouPaths7(repositoryRoot);
+  await assertWorkspaceInitialized5(paths.root);
+  const now = /* @__PURE__ */ new Date();
+  const records = (await loadSessionEntries(paths, {
+    now,
+    onWarning: (w, sid) => printReplayWarning(w, sid),
+    onSkip: (sid, reason) => printSessionListSkip(sid, reason)
+  })).map((entry) => ({
+    sessionId: entry.sessionId,
+    session: entry.session,
+    suspect: entry.suspect,
+    suspectReason: entry.suspectReason
+  }));
+  if (records.length === 0) {
+    printNoSessions(options);
+    return;
+  }
+  records.sort(
+    (a, b) => Date.parse(b.session.session.started_at) - Date.parse(a.session.session.started_at)
+  );
+  const filtered = options.status !== void 0 ? records.filter((r) => r.session.session.status === options.status) : records;
+  if (filtered.length === 0) {
+    printNoSessions(options);
+    return;
+  }
+  if (options.json === true) {
+    console.log(
+      JSON.stringify(
+        filtered.map((r) => ({
+          ...r.session.session,
+          suspect: r.suspect,
+          suspect_reason: r.suspectReason
+        })),
+        null,
+        2
+      )
+    );
+  } else {
+    printSessionListText(filtered);
+  }
+}
+async function runSessionShow(idInput, options, ctx = {}) {
+  try {
+    await doRunSessionShow(idInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunSessionShow(idInput, options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForSession(cwd, "show");
+  const paths = basouPaths7(repositoryRoot);
+  await assertWorkspaceInitialized5(paths.root);
+  const sessionId = await resolveSessionId2(paths, idInput);
+  const sessionDir = join4(paths.sessions, sessionId);
+  const sessionYamlPath = join4(sessionDir, "session.yaml");
+  let session;
+  try {
+    const raw = await readYamlFile4(sessionYamlPath);
+    session = SessionSchema3.parse(raw);
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error(`Session not found: ${idInput}`);
+    }
+    throw new Error("Failed to read session", { cause: error });
+  }
+  const events = await readAllEvents(sessionDir, {
+    onWarning: (w) => printReplayWarning(w, sessionId)
+  });
+  if (options.json === true) {
+    console.log(JSON.stringify({ session: session.session, events }, null, 2));
+    return;
+  }
+  printSessionShowText(session, events, options, repositoryRoot);
+}
+function suspectLabel(reason) {
+  if (reason === "events_say_ended_but_yaml_running") return " \u26A0 ended (yaml stale)";
+  if (reason === "running_no_end_event") return " \u26A0 no end event";
+  return "";
+}
+function printSessionListText(records) {
+  const shortLen = computeUniquePrefixLen2(records.map((r) => r.sessionId));
+  const rows = records.map((r) => {
+    const sid = sliceShort2(r.sessionId, shortLen);
+    const status = `${r.session.session.status}${suspectLabel(r.suspectReason)}`;
+    const source = r.session.session.source.kind;
+    const startedAt = r.session.session.started_at;
+    const fileCount = r.session.session.related_files.length;
+    const filesSuffix = fileCount > 0 ? ` (${fileCount} files)` : "";
+    const label = (r.session.session.label ?? "") + filesSuffix;
+    return { sid, status, source, startedAt, label };
+  });
+  const widths = {
+    sid: maxLen2(
+      rows.map((r) => r.sid),
+      "SHORT_ID".length
+    ),
+    status: maxLen2(
+      rows.map((r) => r.status),
+      "STATUS".length
+    ),
+    source: maxLen2(
+      rows.map((r) => r.source),
+      "SOURCE".length
+    ),
+    startedAt: maxLen2(
+      rows.map((r) => r.startedAt),
+      "STARTED_AT".length
+    )
+  };
+  console.log(
+    `${pad2("SHORT_ID", widths.sid)}  ${pad2("STATUS", widths.status)}  ${pad2("SOURCE", widths.source)}  ${pad2("STARTED_AT", widths.startedAt)}  LABEL`
+  );
+  for (const row of rows) {
+    console.log(
+      `${pad2(row.sid, widths.sid)}  ${pad2(row.status, widths.status)}  ${pad2(row.source, widths.source)}  ${pad2(row.startedAt, widths.startedAt)}  ${row.label}`
+    );
+  }
+}
+function printSessionShowText(session, events, options, repositoryRoot) {
+  const s = session.session;
+  console.log(`Session: ${s.id}  (status: ${s.status})`);
+  console.log(`Source:        ${s.source.kind} (v${s.source.version})`);
+  console.log(`Workspace:     ${s.workspace_id}`);
+  console.log(`Started at:    ${s.started_at}`);
+  if (s.ended_at !== void 0) {
+    console.log(`Ended at:      ${s.ended_at}`);
+  }
+  console.log(`Working dir:   ${formatWorkingDir(s.working_directory, repositoryRoot, options)}`);
+  const invocationArgs = s.invocation.args.length > 0 ? ` ${s.invocation.args.join(" ")}` : "";
+  console.log(`Invocation:    ${s.invocation.command}${invocationArgs}`);
+  if (s.invocation.exit_code !== null) {
+    console.log(`Exit code:     ${s.invocation.exit_code}`);
+  }
+  if (s.label !== void 0) {
+    console.log(`Label:         ${s.label}`);
+  }
+  console.log(`Related files: ${formatRelatedFiles(s.related_files)}`);
+  console.log("");
+  console.log(`Events: ${events.length} total`);
+  const counts = countByType(events);
+  for (const [type, n] of counts) {
+    console.log(`  ${pad2(`${type}:`, 24)} ${n}`);
+  }
+  if (events.length === 0) return;
+  const last = options.last ?? 5;
+  const showAll = options.events === true && options.last === void 0;
+  const slice = showAll ? events : events.slice(-last);
+  const heading = showAll ? "All events:" : `Last ${slice.length} events:`;
+  console.log("");
+  console.log(heading);
+  for (const ev of slice) {
+    console.log(`  ${formatEventLine(ev)}`);
+  }
+}
+function formatWorkingDir(workingDir, repositoryRoot, options) {
+  if (options.fullPath === true) return workingDir;
+  if (!isAbsolute(workingDir)) {
+    if (workingDir === ".") return "<repository_root>";
+    return workingDir;
+  }
+  if (workingDir === repositoryRoot) return "<repository_root>";
+  const rel = relative(repositoryRoot, workingDir);
+  if (rel.length === 0 || rel === ".") return "<repository_root>";
+  if (rel.startsWith("..")) return rel;
+  return `./${rel}`;
+}
+function formatRelatedFiles(files) {
+  if (files.length === 0) return "0 paths";
+  const head = files.slice(0, 3).join(", ");
+  const remaining = files.length - 3;
+  if (remaining <= 0) return `${files.length} paths (${head})`;
+  return `${files.length} paths (${head}, ... +${remaining} more)`;
+}
+function countByType(events) {
+  const map = /* @__PURE__ */ new Map();
+  for (const ev of events) {
+    map.set(ev.type, (map.get(ev.type) ?? 0) + 1);
+  }
+  return [...map.entries()];
+}
+function formatEventLine(ev) {
+  return `${ev.occurred_at} [${ev.source}]  ${ev.type}  ${eventVariantSummary(ev)}`;
+}
+function eventVariantSummary(ev) {
+  switch (ev.type) {
+    case "command_executed": {
+      const argsPart = ev.args.length > 0 ? ` ${ev.args.join(" ")}` : "";
+      const exitPart = ev.exit_code === null ? "exit=signal" : `exit=${ev.exit_code}`;
+      return `${ev.command}${argsPart} (${exitPart}, ${ev.duration_ms}ms)`;
+    }
+    case "git_snapshot":
+      return `branch=${ev.branch} dirty=${ev.dirty}`;
+    case "file_changed":
+      return `${ev.change_type} ${ev.path}`;
+    case "session_status_changed":
+      return `${ev.from} -> ${ev.to}`;
+    case "session_started":
+      return "(start)";
+    case "session_ended":
+      return ev.exit_code !== void 0 ? `exit_code=${ev.exit_code}` : "(end)";
+    case "approval_requested":
+      return `${ev.action.kind} risk=${ev.risk_level}`;
+    case "approval_approved":
+      return ev.resolver !== void 0 ? `by ${ev.resolver}` : "(approved)";
+    case "approval_rejected":
+      return ev.resolver !== void 0 ? `by ${ev.resolver}: ${ev.reason}` : ev.reason;
+    case "approval_expired":
+      return `approval=${ev.approval_id}`;
+    case "decision_recorded":
+      return ev.title;
+    case "task_created":
+      return ev.title;
+    case "task_status_changed":
+      return `${ev.from} -> ${ev.to}`;
+    case "task_reconciled": {
+      const createdPart = ev.removed_created_in_session !== null ? "1 created_in_session" : "0 created_in_session";
+      return `task ${shortTaskId2(ev.task_id)}: cleared ${ev.removed_linked_sessions.length} linked + ${createdPart}`;
+    }
+    case "task_linkage_refreshed": {
+      const added = ev.added_linked_sessions.length;
+      const removed = ev.removed_linked_sessions.length;
+      const final = ev.final_count !== void 0 ? ` final=${ev.final_count}` : "";
+      return `task ${shortTaskId2(ev.task_id)}: +${added} / -${removed} linked${final}`;
+    }
+    case "task_deleted":
+      return `task ${shortTaskId2(ev.task_id)}: ${ev.title} (deleted)`;
+    case "task_archived":
+      return `task ${shortTaskId2(ev.task_id)}: ${ev.title} (archived)`;
+    case "note_added":
+      return ev.body.length > 80 ? `${ev.body.slice(0, 77)}...` : ev.body;
+    case "adapter_output":
+      return `${ev.stream} "${ev.summary}" raw_ref=${ev.raw_ref}`;
+  }
+}
+function shortId2(id) {
+  return sliceShort2(id, SHORT_ID_BASE_LEN2);
+}
+function shortTaskId2(id) {
+  if (id.startsWith(TASK_PREFIX2)) {
+    return id.slice(TASK_PREFIX2.length, TASK_PREFIX2.length + SHORT_ID_BASE_LEN2);
+  }
+  return id.slice(0, SHORT_ID_BASE_LEN2);
+}
+function sliceShort2(id, len) {
+  if (id.startsWith(SES_PREFIX2)) {
+    return id.slice(SES_PREFIX2.length, SES_PREFIX2.length + len);
+  }
+  return id.slice(0, len);
+}
+function computeUniquePrefixLen2(sessionIds) {
+  if (sessionIds.length <= 1) return SHORT_ID_BASE_LEN2;
+  for (let len = SHORT_ID_BASE_LEN2; len <= SHORT_ID_MAX_LEN2; len += 2) {
+    const seen = /* @__PURE__ */ new Set();
+    let collided = false;
+    for (const sid of sessionIds) {
+      const key = sliceShort2(sid, len);
+      if (seen.has(key)) {
+        collided = true;
+        break;
+      }
+      seen.add(key);
+    }
+    if (!collided) return len;
+  }
+  return SHORT_ID_MAX_LEN2;
+}
+function pad2(value, width) {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+function maxLen2(values, floor) {
+  let max = floor;
+  for (const v of values) if (v.length > max) max = v.length;
+  return max;
+}
+async function resolveRepositoryRootForSession(cwd, subcmd) {
+  try {
+    return await resolveRepositoryRoot8(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        `Not a git repository. Run 'git init' first, then re-run 'basou session ${subcmd}'.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized5(basouRoot) {
+  try {
+    await assertBasouRootSafe7(basouRoot);
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+function parsePositiveInt(raw) {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n < 1 || raw.trim() !== String(n)) {
+    throw new Error(`Invalid number: ${raw}`);
+  }
+  return n;
+}
+function parseSessionStatus(raw) {
+  const result = SessionStatusSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(`Invalid session status: ${raw}. Valid values: ${STATUS_VALUES2.join(", ")}`);
+  }
+  return result.data;
+}
+function printNoSessions(options) {
+  if (options.json === true) {
+    console.log("[]");
+  } else {
+    console.log("No sessions found.");
+  }
+}
+async function runSessionImport(options, ctx = {}) {
+  try {
+    await doRunSessionImport(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunSessionImport(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForSession(cwd, "import");
+  const paths = basouPaths7(repositoryRoot);
+  await assertWorkspaceInitialized5(paths.root);
+  const manifest = await readManifest4(paths);
+  const rawBody = await readInputFile(options.from);
+  const json = parseJsonStrict(rawBody);
+  const parsed = SessionImportPayloadSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new Error("Invalid import payload", { cause: parsed.error });
+  }
+  if (parsed.data.schema_version !== "0.1.0") {
+    throw new Error(`Unsupported import schema_version: ${parsed.data.schema_version}`);
+  }
+  const importOptions = { dryRun: options.dryRun === true };
+  if (options.label !== void 0) importOptions.labelOverride = options.label;
+  if (options.task !== void 0) {
+    importOptions.taskIdOverride = await resolveTaskId(paths, options.task);
+  }
+  const result = await importSessionFromJson(paths, manifest, parsed.data, importOptions);
+  const sanitizeReport = result.pathSanitizeReport;
+  if (sanitizeReport.relatedFiles > 0 || sanitizeReport.workingDirectoryRewritten) {
+    const wdCount = sanitizeReport.workingDirectoryRewritten ? 1 : 0;
+    console.error(
+      `Imported session: ${sanitizeReport.relatedFiles + wdCount} path(s) sanitized (related_files: ${sanitizeReport.relatedFiles}, working_directory: ${wdCount})`
+    );
+  }
+  printSessionImportResult(options, result);
+}
+async function readInputFile(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error("Import source not found", { cause: error });
+    }
+    if (findErrorCode5(error, "EISDIR")) {
+      throw new Error("Import source is not a file", { cause: error });
+    }
+    throw new Error("Failed to read import source", { cause: error });
+  }
+}
+function parseJsonStrict(body) {
+  try {
+    return JSON.parse(body);
+  } catch (error) {
+    throw new Error("Failed to parse import JSON", { cause: error });
+  }
+}
+function parseImportFormat(raw) {
+  if (raw !== "json") {
+    throw new InvalidArgumentError2(`Unsupported format: ${raw}. Valid values: json`);
+  }
+  return "json";
+}
+function parseLabelOverride(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError2("Label must not be empty");
+  }
+  return raw;
+}
+function parseTaskIdOverride(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError2("Task id is empty");
+  }
+  return raw;
+}
+function printSessionImportResult(options, result) {
+  const isDry = options.dryRun === true;
+  const sid = shortId2(result.sessionId);
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        session_id: result.sessionId,
+        event_count: result.eventCount,
+        dry_run: isDry,
+        source: { kind: result.finalSourceKind, version: "0.1.0" },
+        status: result.finalStatus
+      })
+    );
+    return;
+  }
+  if (isDry) {
+    console.log(
+      `Dry run: would import ${result.eventCount} events into ${sid} (illustrative ID; not reserved, no files written)`
+    );
+    return;
+  }
+  console.log(
+    `Imported session ${sid} (${result.eventCount} events) from ${basename2(options.from)}`
+  );
+}
+var NOTE_BODY_PREVIEW_LIMIT = 80;
+var NOTE_BODY_PREVIEW_HEAD = 77;
+async function runSessionNote(sessionIdInput, options, ctx = {}) {
+  try {
+    await doRunSessionNote(sessionIdInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunSessionNote(sessionIdInput, options, ctx) {
+  const hasBody = options.body !== void 0;
+  const hasFromFile = options.fromFile !== void 0;
+  if (!hasBody && !hasFromFile) {
+    throw new Error("Provide --body or --from-file");
+  }
+  if (hasBody && hasFromFile) {
+    throw new Error("--body and --from-file are mutually exclusive");
+  }
+  if (hasFromFile && options.fromFile === "-") {
+    throw new Error("--from-file - (stdin) is not supported in v0.1");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForSession(cwd, "note");
+  const paths = basouPaths7(repositoryRoot);
+  await assertWorkspaceInitialized5(paths.root);
+  const sessionId = await resolveSessionId2(paths, sessionIdInput);
+  const body = hasBody ? options.body : await readNoteFile(options.fromFile);
+  if (body.length === 0) {
+    throw new Error("Note body is empty");
+  }
+  const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+  const sesId = sessionId;
+  const sessionLock = await acquireLock2(paths, "session", sesId);
+  let result;
+  try {
+    result = await appendEventToExistingSession2({
+      paths,
+      sessionId: sesId,
+      eventBuilder: (eventId) => ({
+        schema_version: "0.1.0",
+        id: eventId,
+        session_id: sesId,
+        occurred_at: occurredAt,
+        source: "local-cli",
+        type: "note_added",
+        body
+      })
+    });
+  } finally {
+    await sessionLock.release();
+  }
+  printSessionNoteResult(options, sessionId, result.eventId, result.sessionStatus, body);
+}
+async function readNoteFile(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (findErrorCode5(error, "ENOENT")) {
+      throw new Error("Note source not found", { cause: error });
+    }
+    if (findErrorCode5(error, "EISDIR")) {
+      throw new Error("Note source is not a file", { cause: error });
+    }
+    throw new Error("Failed to read note source", { cause: error });
+  }
+}
+function parseNoteBodyOption(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError2("--body must not be empty");
+  }
+  return raw;
+}
+function printSessionNoteResult(options, sessionId, eventId, sessionStatus, body) {
+  const sid = shortId2(sessionId);
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        event_id: eventId,
+        session_id: sessionId,
+        session_status: sessionStatus,
+        body_length: body.length
+      })
+    );
+    return;
+  }
+  const preview = body.length > NOTE_BODY_PREVIEW_LIMIT ? `${body.slice(0, NOTE_BODY_PREVIEW_HEAD)}...` : body;
+  console.log(`Added note to session ${sid} (${sessionStatus}): ${preview}`);
+}
+
+// src/commands/status.ts
+import {
+  assertBasouRootSafe as assertBasouRootSafe8,
+  basouPaths as basouPaths8,
+  buildStatusSnapshot,
+  findErrorCode as findErrorCode6,
+  readManifest as readManifest5,
+  resolveRepositoryRoot as resolveRepositoryRoot9,
+  writeStatus
+} from "@basou/core";
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show the current Basou workspace status").option("--json", "Output the snapshot as JSON to stdout").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runStatus(options);
+  });
+}
+async function runStatus(options, ctx = {}) {
+  try {
+    await doRunStatus(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options) });
+    process.exitCode = 1;
+  }
+}
+async function doRunStatus(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForStatus(cwd);
+  const paths = basouPaths8(repositoryRoot);
+  try {
+    await assertBasouRootSafe8(paths.root);
+  } catch (error) {
+    if (findErrorCode6(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+  let manifest;
+  try {
+    manifest = await readManifest5(paths);
+  } catch (error) {
+    if (findErrorCode6(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw new Error("Failed to read workspace manifest", { cause: error });
+  }
+  const snapshot = await buildStatusSnapshot({ manifest, paths });
+  await writeStatus(paths, snapshot);
+  if (options.json === true) {
+    console.log(JSON.stringify(snapshot, null, 2));
+  } else {
+    renderTextStatus(snapshot);
+  }
+}
+function renderTextStatus(s) {
+  console.log(`Workspace: ${s.workspace.name} (${s.workspace.id})`);
+  console.log(`Spec version:  ${s.workspace.basou_version}`);
+  console.log(`Generated at:  ${s.generated_at}`);
+  const dp = s.directories_present;
+  const total = Object.keys(dp).length;
+  const present = Object.values(dp).filter((v) => v === true).length;
+  console.log(`Subdirectories present: ${present}/${total}`);
+}
+async function resolveRepositoryRootForStatus(cwd) {
+  try {
+    return await resolveRepositoryRoot9(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou status'.", {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+
+// src/commands/task.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join as join5 } from "path";
+import {
+  TaskStatusSchema,
+  TaskWriteAfterEventError,
+  archiveTask,
+  assertBasouRootSafe as assertBasouRootSafe9,
+  basouPaths as basouPaths9,
+  createTaskWithEvent,
+  deleteTask,
+  editTask,
+  enumerateArchivedTaskIds,
+  findErrorCode as findErrorCode7,
+  loadSessionEntries as loadSessionEntries2,
+  loadTaskEntries,
+  prefixedUlid as prefixedUlid5,
+  readManifest as readManifest6,
+  readTaskFile,
+  readTaskFileWithArchiveFallback,
+  reconcileAllTasks,
+  reconcileTask,
+  refreshTaskLinkedSessions,
+  replayEvents as replayEvents2,
+  resolveRepositoryRoot as resolveRepositoryRoot10,
+  resolveSessionId as resolveSessionId3,
+  resolveTaskId as resolveTaskId2,
+  updateTaskStatusWithEvent
+} from "@basou/core";
+import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
+var STATUS_VALUES3 = TaskStatusSchema.options;
+function registerTaskCommand(program2) {
+  const task = program2.command("task").description("Manage Basou tasks (purpose units that span sessions)");
+  task.command("new").description("Create a new task and fire a task_created event").requiredOption("--title <text>", "Task title", parseTitle2).option("--label <text>", "Optional label for the task", parseLabel).option(
+    "--status <status>",
+    `Initial status (one of: ${STATUS_VALUES3.join(", ")}; default planned). For done/cancelled the orchestrator also emits a task_status_changed event so the audit trail records the implicit transition.`,
+    parseInitialTaskStatus
+  ).option(
+    "--completed-at <iso>",
+    "ISO-8601 timestamp to record as the task's updated_at when --status is done or cancelled (rejected otherwise)",
+    parseIsoTimestampOption
+  ).option("--session <session_id>", "Attach to existing session; otherwise ad-hoc").option("--description <text>", "Task description body (inline)", parseDescriptionOption).option("--from-file <path>", "Read description body from a file").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runTaskNew(options);
+  });
+  task.command("list").description("List tasks in the current workspace (newest first)").option(
+    "--status <status>",
+    `Filter by task status (one of: ${STATUS_VALUES3.join(", ")})`,
+    parseTaskStatusFilter
+  ).option("--include-archived", "Also list tasks under .basou/tasks/archive/ (hidden by default)").option("--json", "Output the list as a JSON array").option("-v, --verbose", "Show error causes").action(async (options) => {
+    await runTaskList(options);
+  });
+  task.command("show <task_id>").description("Show a task with its metadata, linked sessions, and events").option("--json", "Output as JSON").option("--events", "Show all related events instead of trailing few").option("--last <n>", "Number of trailing events to display (default: 5)", parsePositiveInt2).option("-v, --verbose", "Show error causes").action(async (id, options) => {
+    await runTaskShow(id, options);
+  });
+  task.command("status <task_id> <new_status>").description("Change task status and fire a task_status_changed event").option("--session <session_id>", "Attach to existing session; otherwise ad-hoc").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (taskIdInput, newStatusInput, options) => {
+    await runTaskStatus(taskIdInput, newStatusInput, options);
+  });
+  task.command("reconcile").description(
+    "Dry-run audit of task session references; use --write to repair broken refs. Forward sync (events -> task.md linked_sessions) is out of scope."
+  ).option("--task <task_id>", "Limit to a single task (otherwise scan all)").option("--write", "Apply repairs (default: dry-run)").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes and broken session_id values").action(async (options) => {
+    await runTaskReconcile(options);
+  });
+  task.command("refresh-linkage <task_id>").description(
+    "Re-derive task.md linked_sessions[] from session.yaml.task_id matches across the workspace (forward sync events -> task.md). Dry-run default; use --write to apply."
+  ).option("--write", "Apply the refresh (default: dry-run)").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (taskIdInput, options) => {
+    await runTaskRefreshLinkage(taskIdInput, options);
+  });
+  task.command("edit <task_id>").description(
+    "Update --title and/or --status on an existing task. Status changes fire a task_status_changed event; title changes update task.md only (no event)."
+  ).option("--title <text>", "New title (must be non-empty)", parseTitle2).option(
+    "--status <status>",
+    `New status (one of: ${STATUS_VALUES3.join(", ")}); routed through STATUS_TRANSITIONS so only valid edges are accepted`,
+    parseInitialTaskStatus
+  ).option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (taskIdInput, options) => {
+    await runTaskEdit(taskIdInput, options);
+  });
+  task.command("delete <task_id>").description(
+    "Hard-delete a task.md file and fire a task_deleted event. Requires confirmation by default; use --yes to skip the prompt."
+  ).option("--yes", "Skip the confirmation prompt (required when stdin is not a TTY)").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (taskIdInput, options) => {
+    await runTaskDelete(taskIdInput, options);
+  });
+  task.command("archive <task_id>").description(
+    "Move task.md into .basou/tasks/archive/ and fire a task_archived event. Requires confirmation by default; use --yes to skip the prompt."
+  ).option("--yes", "Skip the confirmation prompt (required when stdin is not a TTY)").option("--json", "Output as JSON").option("-v, --verbose", "Show error causes").action(async (taskIdInput, options) => {
+    await runTaskArchive(taskIdInput, options);
+  });
+}
+async function runTaskNew(options, ctx = {}) {
+  try {
+    await doRunTaskNew(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskNew(options, ctx) {
+  if (options.description !== void 0 && options.fromFile !== void 0) {
+    throw new Error("--description and --from-file are mutually exclusive");
+  }
+  if (options.fromFile === "-") {
+    throw new Error("--from-file - (stdin) is not supported in v0.1");
+  }
+  const initialStatus = options.status ?? "planned";
+  if (options.completedAt !== void 0 && !isTerminalStatusForCli(initialStatus)) {
+    throw new Error("--completed-at requires --status done or cancelled");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "new");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const description = options.description !== void 0 ? options.description : options.fromFile !== void 0 ? await readDescriptionFile(options.fromFile) : "";
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const taskId = prefixedUlid5("task");
+  if (options.session !== void 0) {
+    const sessionId = await resolveSessionId3(paths, options.session);
+    const result2 = await createTaskWithEvent({
+      mode: "attach",
+      paths,
+      occurredAt,
+      sessionId,
+      taskId,
+      title: options.title,
+      ...options.label !== void 0 ? { label: options.label } : {},
+      initialStatus,
+      description,
+      ...options.completedAt !== void 0 ? { completedAt: options.completedAt } : {}
+    });
+    printTaskNewResult(options, {
+      mode: "attached",
+      taskId: result2.taskId,
+      eventId: result2.eventId,
+      sessionId: result2.sessionId,
+      sessionStatus: result2.sessionStatus,
+      title: options.title,
+      ...options.label !== void 0 ? { label: options.label } : {},
+      status: initialStatus,
+      occurredAt,
+      ...options.completedAt !== void 0 ? { completedAt: options.completedAt } : {},
+      descriptionLength: description.length
+    });
+    return;
+  }
+  const manifest = await readManifest6(paths);
+  const result = await createTaskWithEvent({
+    mode: "ad-hoc",
+    paths,
+    manifest,
+    occurredAt,
+    taskId,
+    title: options.title,
+    ...options.label !== void 0 ? { label: options.label } : {},
+    initialStatus,
+    description,
+    workingDirectory: repositoryRoot,
+    ...options.completedAt !== void 0 ? { completedAt: options.completedAt } : {}
+  });
+  printTaskNewResult(options, {
+    mode: "ad-hoc",
+    taskId: result.taskId,
+    eventId: result.eventId,
+    sessionId: result.sessionId,
+    sessionStatus: result.sessionStatus,
+    title: options.title,
+    ...options.label !== void 0 ? { label: options.label } : {},
+    status: initialStatus,
+    occurredAt,
+    ...options.completedAt !== void 0 ? { completedAt: options.completedAt } : {},
+    descriptionLength: description.length
+  });
+}
+function isTerminalStatusForCli(status) {
+  return status === "done" || status === "cancelled";
+}
+function printTaskNewResult(options, result) {
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        task_id: result.taskId,
+        event_id: result.eventId,
+        session_id: result.sessionId,
+        session_status: result.sessionStatus,
+        mode: result.mode,
+        title: result.title,
+        label: result.label ?? null,
+        status: result.status,
+        recorded_at: result.occurredAt,
+        completed_at: result.completedAt ?? null,
+        description_length: result.descriptionLength
+      })
+    );
+    return;
+  }
+  const shortSes = shortSessionId(result.sessionId);
+  const created = result.mode === "ad-hoc" ? `Created ${result.taskId} in ad-hoc session ${shortSes}` : `Created ${result.taskId} in session ${shortSes} (${result.sessionStatus})`;
+  console.log(created);
+  console.log(`  Title:  ${result.title}`);
+  if (result.completedAt !== void 0) {
+    console.log(
+      `  Status: ${result.status} (recorded at ${result.occurredAt}, completed at ${result.completedAt})`
+    );
+  } else {
+    console.log(`  Status: ${result.status}`);
+  }
+  console.log(`  Label:  ${result.label ?? "(none)"}`);
+}
+async function runTaskList(options, ctx = {}) {
+  try {
+    await doRunTaskList(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskList(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "list");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const entries = await loadTaskEntries(paths, {
+    onSkip: (id, reason) => printTaskSkip(id, reason)
+  });
+  const archivedEntries = [];
+  if (options.includeArchived === true) {
+    const archivedIds = await enumerateArchivedTaskIds(paths);
+    for (const id of archivedIds) {
+      try {
+        const { doc } = await readTaskFileWithArchiveFallback(paths, id);
+        archivedEntries.push({ doc, archived: true });
+      } catch {
+      }
+    }
+  }
+  const combined = [...entries, ...archivedEntries.map((a) => a.doc)];
+  const archivedIdSet = new Set(archivedEntries.map((a) => a.doc.task.task.id));
+  const ordered = [...combined].sort(
+    (a, b) => Date.parse(b.task.task.created_at) - Date.parse(a.task.task.created_at)
+  );
+  const filtered = options.status !== void 0 ? ordered.filter((t) => t.task.task.status === options.status) : ordered;
+  if (filtered.length === 0) {
+    if (options.json === true) {
+      console.log("[]");
+    } else {
+      console.log("No tasks found.");
+    }
+    return;
+  }
+  if (options.json === true) {
+    console.log(
+      JSON.stringify(
+        filtered.map((t) => ({
+          task_id: t.task.task.id,
+          title: t.task.task.title,
+          label: t.task.task.label ?? null,
+          status: t.task.task.status,
+          created_at: t.task.task.created_at,
+          updated_at: t.task.task.updated_at,
+          linked_session_count: t.task.task.linked_sessions.length,
+          archived: archivedIdSet.has(t.task.task.id)
+        })),
+        null,
+        2
+      )
+    );
+    return;
+  }
+  printTaskListText(filtered, archivedIdSet);
+}
+function printTaskListText(entries, archivedIds) {
+  const rows = entries.map((t) => ({
+    sid: shortTaskId(t.task.task.id),
+    status: t.task.task.status,
+    createdAt: t.task.task.created_at,
+    label: t.task.task.label ?? "(none)",
+    // Mark archived entries with a leading [archived] tag so the operator
+    // can distinguish them from live tasks when --include-archived is on.
+    title: archivedIds.has(t.task.task.id) ? `[archived] ${t.task.task.title}` : t.task.task.title,
+    linkedCount: String(t.task.task.linked_sessions.length)
+  }));
+  const widths = {
+    sid: maxLen3(
+      rows.map((r) => r.sid),
+      "SHORT_ID".length
+    ),
+    status: maxLen3(
+      rows.map((r) => r.status),
+      "STATUS".length
+    ),
+    createdAt: maxLen3(
+      rows.map((r) => r.createdAt),
+      "CREATED_AT".length
+    ),
+    linkedCount: maxLen3(
+      rows.map((r) => r.linkedCount),
+      "LINKS".length
+    ),
+    label: maxLen3(
+      rows.map((r) => r.label),
+      "LABEL".length
+    )
+  };
+  console.log(
+    `${pad3("SHORT_ID", widths.sid)}  ${pad3("STATUS", widths.status)}  ${pad3("CREATED_AT", widths.createdAt)}  ${pad3("LINKS", widths.linkedCount)}  ${pad3("LABEL", widths.label)}  TITLE`
+  );
+  for (const r of rows) {
+    console.log(
+      `${pad3(r.sid, widths.sid)}  ${pad3(r.status, widths.status)}  ${pad3(r.createdAt, widths.createdAt)}  ${pad3(r.linkedCount, widths.linkedCount)}  ${pad3(r.label, widths.label)}  ${r.title}`
+    );
+  }
+}
+async function runTaskShow(idInput, options, ctx = {}) {
+  try {
+    await doRunTaskShow(idInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskShow(idInput, options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "show");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const taskId = await resolveTaskId2(paths, idInput, { includeArchived: true });
+  const { doc, archived } = await readTaskFileWithArchiveFallback(paths, taskId);
+  const sessions = await loadSessionEntries2(paths, { now: /* @__PURE__ */ new Date() });
+  const events = [];
+  const linkedSessionIds = new Set(doc.task.task.linked_sessions);
+  for (const s of sessions) {
+    const sessionDir = join5(paths.sessions, s.sessionId);
+    try {
+      for await (const ev of replayEvents2(sessionDir, {
+        onWarning: (w) => printReplayWarning(w, s.sessionId)
+      })) {
+        if ((ev.type === "task_created" || ev.type === "task_status_changed" || ev.type === "task_reconciled" || ev.type === "task_linkage_refreshed" || ev.type === "task_deleted" || ev.type === "task_archived") && ev.task_id === taskId) {
+          events.push(ev);
+          linkedSessionIds.add(s.sessionId);
+        }
+      }
+    } catch (error) {
+      const short = shortSessionId(s.sessionId);
+      const suffix = error instanceof Error ? `: ${error.message}` : "";
+      console.error(`Warning: events unavailable for session ${short}${suffix}`);
+    }
+  }
+  events.sort((a, b) => Date.parse(a.occurred_at) - Date.parse(b.occurred_at));
+  if (options.json === true) {
+    console.log(
+      JSON.stringify(
+        {
+          task: doc.task.task,
+          body: doc.body,
+          linked_sessions: [...linkedSessionIds],
+          archived,
+          events
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  printTaskShowText(doc, [...linkedSessionIds], events, sessions, options, archived);
+}
+function printTaskShowText(doc, linkedSessions, events, sessionEntries, options, archived) {
+  const t = doc.task.task;
+  const archivedTag = archived ? " [archived]" : "";
+  console.log(`Task: ${t.id}${archivedTag}`);
+  console.log(`  Title:       ${t.title}`);
+  console.log(`  Status:      ${t.status}`);
+  console.log(`  Label:       ${t.label ?? "(none)"}`);
+  console.log(`  Created at:  ${t.created_at}`);
+  console.log(`  Updated at:  ${t.updated_at}`);
+  console.log(`  Workspace:   ${t.workspace_id}`);
+  console.log("");
+  console.log(`Linked sessions (${linkedSessions.length}):`);
+  const sessionStatusMap = new Map(
+    sessionEntries.map((s) => [s.sessionId, s.session.session.status])
+  );
+  for (const sid of linkedSessions) {
+    const status = sessionStatusMap.get(sid) ?? "unknown";
+    console.log(`  ${sid}  (${status})`);
+  }
+  console.log("");
+  console.log("Description:");
+  if (doc.body.length === 0) {
+    console.log("(no description)");
+  } else {
+    console.log(doc.body);
+  }
+  console.log("");
+  console.log(`Events: ${events.length} total`);
+  if (events.length === 0) return;
+  const showAll = options.events === true && options.last === void 0;
+  const last = options.last ?? 5;
+  const slice = showAll ? events : events.slice(-last);
+  const heading = showAll ? "All events:" : `Last ${slice.length} events:`;
+  console.log("");
+  console.log(heading);
+  const verbose = isVerbose(options);
+  for (const ev of slice) {
+    console.log(`  ${formatTaskEvent(ev)}`);
+    if (verbose && ev.type === "task_reconciled") {
+      for (const line of formatTaskReconciledDetails(ev)) {
+        console.log(line);
+      }
+    }
+  }
+}
+function formatTaskEvent(ev) {
+  if (ev.type === "task_created") {
+    return `${ev.occurred_at} [${ev.source}]  task_created             ${ev.title}`;
+  }
+  if (ev.type === "task_status_changed") {
+    return `${ev.occurred_at} [${ev.source}]  task_status_changed      ${ev.from} -> ${ev.to}`;
+  }
+  if (ev.type === "task_reconciled") {
+    const removedCount = (ev.removed_created_in_session !== null ? 1 : 0) + ev.removed_linked_sessions.length;
+    return `${ev.occurred_at} [${ev.source}]  task_reconciled          ${removedCount} broken ref${removedCount === 1 ? "" : "s"} (use -v for details)`;
+  }
+  if (ev.type === "task_linkage_refreshed") {
+    const added = ev.added_linked_sessions.length;
+    const removed = ev.removed_linked_sessions.length;
+    const finalPart = ev.final_count !== void 0 ? `, final=${ev.final_count}` : "";
+    return `${ev.occurred_at} [${ev.source}]  task_linkage_refreshed   +${added} / -${removed}${finalPart}`;
+  }
+  if (ev.type === "task_deleted") {
+    return `${ev.occurred_at} [${ev.source}]  task_deleted             ${ev.title}`;
+  }
+  if (ev.type === "task_archived") {
+    return `${ev.occurred_at} [${ev.source}]  task_archived            ${ev.title}`;
+  }
+  return `${ev.occurred_at} [${ev.source}]  ${ev.type}`;
+}
+function formatTaskReconciledDetails(ev) {
+  const lines = [];
+  if (ev.removed_created_in_session !== null) {
+    lines.push(`      removed_created_in_session:    ${ev.removed_created_in_session}`);
+  }
+  if (ev.created_in_session_replacement !== null) {
+    lines.push(`      created_in_session_replacement: ${ev.created_in_session_replacement}`);
+  }
+  if (ev.removed_linked_sessions.length > 0) {
+    lines.push("      removed_linked_sessions:");
+    for (const sid of ev.removed_linked_sessions) {
+      lines.push(`        - ${sid}`);
+    }
+  }
+  return lines;
+}
+async function runTaskStatus(taskIdInput, newStatusInput, options, ctx = {}) {
+  try {
+    await doRunTaskStatus(taskIdInput, newStatusInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskStatus(taskIdInput, newStatusInput, options, ctx) {
+  if (taskIdInput.trim().length === 0) {
+    throw new Error("Task id is empty");
+  }
+  const newStatus = parseTaskStatusPositional(newStatusInput);
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "status");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const taskId = await resolveTaskId2(paths, taskIdInput);
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  if (options.session !== void 0) {
+    const sessionId = await resolveSessionId3(paths, options.session);
+    const result2 = await updateTaskStatusWithEvent({
+      mode: "attach",
+      paths,
+      occurredAt,
+      sessionId,
+      taskId,
+      newStatus
+    });
+    printTaskStatusResult(options, {
+      mode: "attached",
+      taskId: result2.taskId,
+      eventId: result2.eventId,
+      sessionId: result2.sessionId,
+      sessionStatus: result2.sessionStatus,
+      previousStatus: result2.previousStatus,
+      newStatus: result2.newStatus
+    });
+    return;
+  }
+  const manifest = await readManifest6(paths);
+  const result = await updateTaskStatusWithEvent({
+    mode: "ad-hoc",
+    paths,
+    manifest,
+    occurredAt,
+    taskId,
+    newStatus,
+    workingDirectory: repositoryRoot
+  });
+  printTaskStatusResult(options, {
+    mode: "ad-hoc",
+    taskId: result.taskId,
+    eventId: result.eventId,
+    sessionId: result.sessionId,
+    sessionStatus: result.sessionStatus,
+    previousStatus: result.previousStatus,
+    newStatus: result.newStatus
+  });
+}
+function printTaskStatusResult(options, result) {
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        task_id: result.taskId,
+        event_id: result.eventId,
+        session_id: result.sessionId,
+        session_status: result.sessionStatus,
+        mode: result.mode,
+        previous_status: result.previousStatus,
+        new_status: result.newStatus
+      })
+    );
+    return;
+  }
+  const sid = shortSessionId(result.sessionId);
+  console.log(
+    `Updated ${result.taskId} status: ${result.previousStatus} -> ${result.newStatus} (in session ${sid})`
+  );
+}
+async function runTaskReconcile(options, ctx = {}) {
+  try {
+    await doRunTaskReconcile(options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskReconcile(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "reconcile");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const manifest = await readManifest6(paths);
+  const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
+  const write = options.write === true;
+  const verbose = isVerbose(options);
+  const json = options.json === true;
+  if (options.task !== void 0) {
+    const taskId = await resolveTaskId2(paths, options.task);
+    const result = await reconcileTask(paths, manifest, {
+      taskId,
+      occurredAt: nowProvider().toISOString(),
+      workingDirectory: repositoryRoot,
+      write,
+      scope: "single"
+    });
+    if (json) {
+      printReconcileJson({ dryRun: !write, scanned: 1, results: [result], failed: [] });
+    } else {
+      await printReconcileSingleText(result, paths, { write, verbose });
+    }
+    return;
+  }
+  const all = await reconcileAllTasks(paths, manifest, {
+    occurredAt: () => nowProvider().toISOString(),
+    workingDirectory: repositoryRoot,
+    write
+  });
+  if (json) {
+    printReconcileJson({
+      dryRun: !write,
+      scanned: all.scanned,
+      results: all.results,
+      failed: all.failed
+    });
+  } else {
+    printReconcileAllText(all.results, all.failed, all.scanned, { write, verbose });
+  }
+  if (all.failed.length > 0) {
+    process.exitCode = 1;
+  }
+}
+function printReconcileJson(input) {
+  console.log(
+    JSON.stringify(
+      {
+        dry_run: input.dryRun,
+        scanned: input.scanned,
+        reconciled: input.results.map((r) => ({
+          task_id: r.taskId,
+          removed_created_in_session: r.brokenCreatedInSession,
+          created_in_session_replacement: r.brokenCreatedInSession !== null && r.reconcileSession !== null ? r.reconcileSession.sessionId : null,
+          removed_linked_sessions: r.brokenLinkedSessions,
+          reconcile_session_id: r.reconcileSession?.sessionId ?? null,
+          event_id: r.reconcileSession?.eventId ?? null
+        })),
+        failed: input.failed.map((f) => ({
+          task_id: f.taskId,
+          error_class: f.errorClass,
+          phase: f.phase
+        }))
+      },
+      null,
+      2
+    )
+  );
+}
+async function printReconcileSingleText(result, paths, options) {
+  if (result.clean) {
+    let createdCount = 0;
+    let linkedCount = 0;
+    try {
+      const doc = await readTaskFile(paths, result.taskId);
+      createdCount = 1;
+      linkedCount = doc.task.task.linked_sessions.length;
+    } catch {
+    }
+    console.log(
+      `${result.taskId}: no broken refs (${createdCount} created_in_session + ${linkedCount} linked_sessions, all reachable).`
+    );
+    return;
+  }
+  if (options.write) {
+    const sessionPart = result.reconcileSession !== null ? ` (in session ${shortSessionId(result.reconcileSession.sessionId)})` : "";
+    console.log(`Reconciled ${result.taskId}: ${describeReconcileSummary(result)}${sessionPart}.`);
+    return;
+  }
+  const summary = describeBrokenSummary(result, "task", options.verbose);
+  console.log(`(dry-run) Would reconcile ${result.taskId}: ${summary}`);
+  console.log("Note: events -> task.md forward sync is handled by `basou task refresh-linkage`.");
+  console.log("Re-run with --write to apply.");
+}
+function printReconcileAllText(results, failed, scanned, options) {
+  if (results.length === 0 && failed.length === 0) {
+    console.log(`Scanned ${scanned} tasks, no broken refs detected.`);
+    return;
+  }
+  let totalBrokenRefs = 0;
+  for (const r of results) {
+    totalBrokenRefs += r.brokenLinkedSessions.length + (r.brokenCreatedInSession !== null ? 1 : 0);
+  }
+  if (options.write) {
+    for (const r of results) {
+      const sessionPart = r.reconcileSession !== null ? ` (in session ${shortSessionId(r.reconcileSession.sessionId)})` : "";
+      console.log(`Reconciled ${r.taskId}: ${describeReconcileSummary(r)}${sessionPart}`);
+    }
+    for (const f of failed) {
+      const phase = f.phase ?? "unknown";
+      console.error(
+        `Failed to reconcile ${f.taskId}: ${f.errorClass} (phase: ${phase}); see Caused by with -v`
+      );
+    }
+    const reconciledCount = results.length;
+    const reconciledRefs = totalBrokenRefs;
+    const reconciledPart = `reconciled ${reconciledCount} task${reconciledCount === 1 ? "" : "s"} (${reconciledRefs} broken ref${reconciledRefs === 1 ? "" : "s"})`;
+    const failedPart = failed.length === 0 ? "" : `, ${failed.length} task${failed.length === 1 ? "" : "s"} failed`;
+    console.log(`Scanned ${scanned} tasks, ${reconciledPart}${failedPart}.`);
+    if (failed.length > 0) {
+      console.error("(exit code 1)");
+    }
+    return;
+  }
+  for (const r of results) {
+    const summary = describeBrokenSummary(r, "all", options.verbose);
+    console.log(`(dry-run) Would reconcile ${r.taskId}: ${summary}`);
+  }
+  console.log(
+    `Scanned ${scanned} tasks, would reconcile ${results.length} task${results.length === 1 ? "" : "s"} (${totalBrokenRefs} broken ref${totalBrokenRefs === 1 ? "" : "s"}).`
+  );
+  console.log("Note: events -> task.md forward sync is handled by `basou task refresh-linkage`.");
+  console.log("Re-run with --write to apply.");
+}
+function describeReconcileSummary(r) {
+  const linkedCount = r.brokenLinkedSessions.length;
+  const parts = [];
+  if (r.brokenCreatedInSession !== null) {
+    parts.push("replaced created_in_session");
+  }
+  if (linkedCount > 0) {
+    parts.push(`removed ${linkedCount} linked_sessions entr${linkedCount === 1 ? "y" : "ies"}`);
+  }
+  return parts.join(" + ");
+}
+function describeBrokenSummary(r, scope, verbose) {
+  const showIds = scope === "task" || verbose;
+  const parts = [];
+  if (r.brokenCreatedInSession !== null) {
+    parts.push(
+      showIds ? `broken created_in_session ${formatSessionIdForDisplay(r.brokenCreatedInSession, verbose, scope)}` : "broken created_in_session"
+    );
+  }
+  const linkedCount = r.brokenLinkedSessions.length;
+  if (linkedCount > 0) {
+    if (showIds) {
+      const ids = r.brokenLinkedSessions.map((id) => formatSessionIdForDisplay(id, verbose, scope)).join(", ");
+      parts.push(`${linkedCount} linked_sessions entr${linkedCount === 1 ? "y" : "ies"} [${ids}]`);
+    } else {
+      parts.push(`${linkedCount} linked_sessions entr${linkedCount === 1 ? "y" : "ies"}`);
+    }
+  }
+  return parts.join(" + ");
+}
+function formatSessionIdForDisplay(id, verbose, scope) {
+  if (verbose && scope === "task") return id;
+  return `ses_${shortSessionId(id)}`;
+}
+async function runTaskRefreshLinkage(taskIdInput, options, ctx = {}) {
+  try {
+    await doRunTaskRefreshLinkage(taskIdInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskRefreshLinkage(taskIdInput, options, ctx) {
+  if (taskIdInput.trim().length === 0) {
+    throw new Error("Task id is empty");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "refresh-linkage");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const manifest = await readManifest6(paths);
+  const taskId = await resolveTaskId2(paths, taskIdInput);
+  const nowProvider = ctx.nowProvider ?? (() => /* @__PURE__ */ new Date());
+  const write = options.write === true;
+  const result = await refreshTaskLinkedSessions(paths, manifest, {
+    taskId,
+    occurredAt: nowProvider().toISOString(),
+    workingDirectory: repositoryRoot,
+    write
+  });
+  if (options.json === true) {
+    printRefreshLinkageJson(result, { dryRun: !write });
+    return;
+  }
+  printRefreshLinkageText(result, { dryRun: !write });
+}
+function printRefreshLinkageJson(result, input) {
+  console.log(
+    JSON.stringify(
+      {
+        task_id: result.taskId,
+        clean: result.clean,
+        dry_run: input.dryRun,
+        added_linked_sessions: result.addedLinkedSessions,
+        removed_linked_sessions: result.removedLinkedSessions,
+        final_count: result.finalCount,
+        refresh_session_id: result.refreshSession?.sessionId ?? null,
+        event_id: result.refreshSession?.eventId ?? null
+      },
+      null,
+      2
+    )
+  );
+}
+function printRefreshLinkageText(result, input) {
+  if (result.clean) {
+    console.log(
+      `${result.taskId}: linked_sessions already fresh (${result.finalCount} entr${result.finalCount === 1 ? "y" : "ies"}).`
+    );
+    return;
+  }
+  const addedCount = result.addedLinkedSessions.length;
+  const removedCount = result.removedLinkedSessions.length;
+  const summaryParts = [];
+  if (addedCount > 0) {
+    summaryParts.push(`+${addedCount} added`);
+  }
+  if (removedCount > 0) {
+    summaryParts.push(`-${removedCount} removed`);
+  }
+  const summary = summaryParts.join(", ");
+  if (input.dryRun) {
+    console.log(`(dry-run) Would refresh ${result.taskId} linked_sessions: ${summary}.`);
+    console.log("Re-run with --write to apply.");
+    return;
+  }
+  const sid = result.refreshSession !== null ? ` (in session ${shortSessionId(result.refreshSession.sessionId)})` : "";
+  console.log(
+    `Refreshed ${result.taskId} linked_sessions: ${summary}${sid}; final count ${result.finalCount}.`
+  );
+}
+async function runTaskEdit(taskIdInput, options, ctx = {}) {
+  try {
+    await doRunTaskEdit(taskIdInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskEdit(taskIdInput, options, ctx) {
+  if (taskIdInput.trim().length === 0) {
+    throw new Error("Task id is empty");
+  }
+  if (options.title === void 0 && options.status === void 0) {
+    throw new Error("Nothing to edit: provide --title or --status");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "edit");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const manifest = await readManifest6(paths);
+  const taskId = await resolveTaskId2(paths, taskIdInput);
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const result = await editTask({
+    paths,
+    taskId,
+    occurredAt,
+    manifest,
+    workingDirectory: repositoryRoot,
+    ...options.title !== void 0 ? { title: options.title } : {},
+    ...options.status !== void 0 ? { newStatus: options.status } : {}
+  });
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        task_id: result.taskId,
+        title_updated: result.titleUpdated,
+        status_updated: result.statusUpdated,
+        previous_status: result.previousStatus,
+        new_status: result.newStatus,
+        status_change_session_id: result.statusChangeSession?.sessionId ?? null,
+        status_change_event_id: result.statusChangeSession?.eventId ?? null
+      })
+    );
+    return;
+  }
+  if (result.statusUpdated) {
+    const sid = result.statusChangeSession !== null ? ` (in session ${shortSessionId(result.statusChangeSession.sessionId)})` : "";
+    console.log(
+      `Updated ${result.taskId} status: ${result.previousStatus} -> ${result.newStatus}${sid}`
+    );
+  }
+  if (result.titleUpdated) {
+    console.log(`Updated ${result.taskId} title.`);
+  }
+  if (!result.statusUpdated && !result.titleUpdated) {
+    console.log(`No changes for ${result.taskId}.`);
+  }
+}
+async function runTaskDelete(taskIdInput, options, ctx = {}) {
+  try {
+    await doRunTaskDelete(taskIdInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskDelete(taskIdInput, options, ctx) {
+  if (taskIdInput.trim().length === 0) {
+    throw new Error("Task id is empty");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "delete");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const manifest = await readManifest6(paths);
+  const taskId = await resolveTaskId2(paths, taskIdInput);
+  if (options.yes !== true) {
+    await confirmDestructiveAction("delete", taskId);
+  }
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const result = await deleteTask({
+    paths,
+    manifest,
+    taskId,
+    occurredAt,
+    workingDirectory: repositoryRoot
+  });
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        task_id: result.taskId,
+        title: result.title,
+        session_id: result.sessionId,
+        event_id: result.eventId
+      })
+    );
+    return;
+  }
+  console.log(
+    `Deleted ${result.taskId} ("${result.title}") in ad-hoc session ${shortSessionId(result.sessionId)}.`
+  );
+}
+async function runTaskArchive(taskIdInput, options, ctx = {}) {
+  try {
+    await doRunTaskArchive(taskIdInput, options, ctx);
+  } catch (error) {
+    renderCliError(error, { verbose: isVerbose(options), classifiers: TASK_CLASSIFIERS });
+    process.exitCode = 1;
+  }
+}
+async function doRunTaskArchive(taskIdInput, options, ctx) {
+  if (taskIdInput.trim().length === 0) {
+    throw new Error("Task id is empty");
+  }
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveRepositoryRootForTask(cwd, "archive");
+  const paths = basouPaths9(repositoryRoot);
+  await assertWorkspaceInitialized6(paths.root);
+  const manifest = await readManifest6(paths);
+  const taskId = await resolveTaskId2(paths, taskIdInput);
+  if (options.yes !== true) {
+    await confirmDestructiveAction("archive", taskId);
+  }
+  const now = ctx.nowProvider !== void 0 ? ctx.nowProvider() : /* @__PURE__ */ new Date();
+  const occurredAt = now.toISOString();
+  const result = await archiveTask({
+    paths,
+    manifest,
+    taskId,
+    occurredAt,
+    workingDirectory: repositoryRoot
+  });
+  if (options.json === true) {
+    console.log(
+      JSON.stringify({
+        task_id: result.taskId,
+        title: result.title,
+        session_id: result.sessionId,
+        event_id: result.eventId
+      })
+    );
+    return;
+  }
+  console.log(
+    `Archived ${result.taskId} ("${result.title}") in ad-hoc session ${shortSessionId(result.sessionId)}.`
+  );
+}
+async function confirmDestructiveAction(action, taskId) {
+  if (process.stdin.isTTY !== true) {
+    throw new Error(`Refusing to ${action} without TTY; rerun with --yes to skip confirmation.`);
+  }
+  const verb = action === "delete" ? "Delete" : "Archive";
+  process.stdout.write(`${verb} task \`${taskId}\`? [y/N] `);
+  const answer = await readSingleLineFromStdin();
+  const normalized = answer.trim().toLowerCase();
+  if (normalized !== "y" && normalized !== "yes") {
+    throw new Error(`${verb} aborted by user.`);
+  }
+}
+async function readSingleLineFromStdin() {
+  const { createInterface } = await import("readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const line = await rl.question("");
+    return line;
+  } finally {
+    rl.close();
+  }
+}
+function parseTitle2(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError3("Title must not be empty");
+  }
+  return raw;
+}
+function parseLabel(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError3("Label must not be empty");
+  }
+  return raw;
+}
+function parseInitialTaskStatus(raw) {
+  const result = TaskStatusSchema.safeParse(raw);
+  if (!result.success) {
+    throw new InvalidArgumentError3(
+      `Initial task status must be one of: ${STATUS_VALUES3.join(", ")}`
+    );
+  }
+  return result.data;
+}
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+function parseIsoTimestampOption(raw) {
+  if (!ISO_DATE_RE.test(raw) || Number.isNaN(Date.parse(raw))) {
+    throw new InvalidArgumentError3(
+      "Invalid --completed-at value; expected ISO-8601 timestamp like 2026-05-10T12:34:56+09:00"
+    );
+  }
+  return raw;
+}
+function parseTaskStatusFilter(raw) {
+  const result = TaskStatusSchema.safeParse(raw);
+  if (!result.success) {
+    throw new InvalidArgumentError3(
+      `Invalid task status: ${raw}. Valid values: ${STATUS_VALUES3.join(", ")}`
+    );
+  }
+  return result.data;
+}
+function parseTaskStatusPositional(raw) {
+  const result = TaskStatusSchema.safeParse(raw);
+  if (!result.success) {
+    throw new Error(`Invalid task status: ${raw}. Valid values: ${STATUS_VALUES3.join(", ")}`);
+  }
+  return result.data;
+}
+function parseDescriptionOption(raw) {
+  if (raw.length === 0) {
+    throw new InvalidArgumentError3("Description must not be empty");
+  }
+  return raw;
+}
+function parsePositiveInt2(raw) {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n < 1 || raw.trim() !== String(n)) {
+    throw new InvalidArgumentError3(`Invalid number: ${raw}`);
+  }
+  return n;
+}
+async function readDescriptionFile(path) {
+  try {
+    return await readFile2(path, "utf8");
+  } catch (error) {
+    if (findErrorCode7(error, "ENOENT")) {
+      throw new Error("Description source not found", { cause: error });
+    }
+    if (findErrorCode7(error, "EISDIR")) {
+      throw new Error("Description source is not a file", { cause: error });
+    }
+    throw new Error("Failed to read description source", { cause: error });
+  }
+}
+async function resolveRepositoryRootForTask(cwd, subcmd) {
+  try {
+    return await resolveRepositoryRoot10(cwd);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Not a git repository") {
+      throw new Error(
+        `Not a git repository. Run 'git init' first, then re-run 'basou task ${subcmd}'.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+async function assertWorkspaceInitialized6(basouRoot) {
+  try {
+    await assertBasouRootSafe9(basouRoot);
+  } catch (error) {
+    if (findErrorCode7(error, "ENOENT")) {
+      throw new Error("Workspace not initialized. Run 'basou init' first.");
+    }
+    throw error;
+  }
+}
+var taskWriteAfterEventClassifier = {
+  match: (error) => error instanceof TaskWriteAfterEventError,
+  additionalLines: (error) => {
+    const e = error;
+    const sid = shortSessionId(e.sessionId);
+    const tid = shortTaskId(e.taskId);
+    const unsafeArtefact = describeUnsafeArtefact(e.phase, tid, sid);
+    const warning = describeWriteFailureWarning(e.phase);
+    const hint = e.phase === "reconcile-concurrent" ? "re-run `basou task reconcile`" : e.phase === "linkage-refresh-concurrent" ? "re-run `basou task refresh-linkage`" : "manual repair required; see `basou task show -v` for event payload";
+    return [
+      `Recorded ${e.eventId} in session ${sid}; ${unsafeArtefact} is in unsafe state; do not rerun`,
+      `Warning: ${warning}; events.jsonl is consistent; ${hint}`
+    ];
+  }
+};
+var TASK_CLASSIFIERS = [
+  taskWriteAfterEventClassifier,
+  failedToFinalizeClassifier
+];
+function describeUnsafeArtefact(phase, tid, sid) {
+  switch (phase) {
+    case "create":
+      return `task ${tid} file`;
+    case "overwrite":
+      return `task ${tid} file`;
+    case "link-session":
+      return "session-task linkage";
+    case "reconcile":
+      return `task ${tid} file (reconcile incomplete)`;
+    case "reconcile-finalize":
+      return `reconcile session ${sid} (finalize incomplete)`;
+    case "reconcile-concurrent":
+      return `task ${tid} file (concurrent modification detected)`;
+    case "linkage-refresh":
+      return `task ${tid} file (linkage refresh incomplete)`;
+    case "linkage-refresh-finalize":
+      return `linkage refresh session ${sid} (finalize incomplete)`;
+    case "linkage-refresh-concurrent":
+      return `task ${tid} file (concurrent modification detected)`;
+    case "delete":
+      return `task ${tid} file (delete incomplete; file still on disk)`;
+    case "archive":
+      return `task ${tid} file (archive incomplete; check tasks/ and tasks/archive/)`;
+  }
+}
+function describeWriteFailureWarning(phase) {
+  switch (phase) {
+    case "create":
+      return "task.md creation failed";
+    case "overwrite":
+      return "task.md update failed";
+    case "link-session":
+      return "session.yaml task_id update failed";
+    case "reconcile":
+      return "task.md reconciliation failed";
+    case "reconcile-finalize":
+      return "reconcile session finalize failed (session.yaml status update)";
+    case "reconcile-concurrent":
+      return "task.md was modified concurrently; re-run reconcile to retry";
+    case "linkage-refresh":
+      return "task.md linkage refresh write failed";
+    case "linkage-refresh-finalize":
+      return "linkage refresh session finalize failed (session.yaml status update)";
+    case "linkage-refresh-concurrent":
+      return "task.md was modified concurrently; re-run refresh-linkage to retry";
+    case "delete":
+      return "task.md unlink failed after task_deleted event committed";
+    case "archive":
+      return "task.md move to archive/ failed after task_archived event committed";
+  }
+}
+function pad3(value, width) {
+  return value.length >= width ? value : value + " ".repeat(width - value.length);
+}
+function maxLen3(values, floor) {
+  let max = floor;
+  for (const v of values) if (v.length > max) max = v.length;
+  return max;
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var BASOU_CLI_VERSION = pkg.version;
+var program = new Command();
+program.name("basou").description("Provenance layer for AI development").version(BASOU_CLI_VERSION).enablePositionalOptions();
+registerInitCommand(program);
+registerStatusCommand(program);
+registerExecCommand(program);
+registerRunCommand(program);
+registerSessionCommand(program);
+registerApprovalCommand(program);
+registerDecisionCommand(program);
+registerTaskCommand(program);
+registerHandoffCommand(program);
+registerDecisionsCommand(program);
+program.parseAsync(process.argv).catch((err) => {
+  renderCliError(err, { verbose: isVerbose(void 0) });
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map