simt-dev 0.6.3 → 0.7.1

package/src/commands/slice.mjs

@@ -2,9 +2,9 @@
 //
 // A row in a tracker is a promise, and these are the two moments it is acted on.
 // `start` isolates the work: a linked worktree on a branch named for the row, so the
-// main checkout stays free for whatever else is running, and the task brief already on
-// disk at `.simt/brief.md` — the same path the bench's brief arm writes — where an
-// agent picks it up. `finish` closes the loop the way the repository's own hook would:
+// main checkout stays free for whatever else is running, and a task brief assembled in
+// the main checkout at `.simt/local/briefs/<id>.md`, beside the worktree and outside
+// its tree, where an agent picks it up. `finish` closes the loop the way the repository's own hook would:
 // the declared gates run through the shared dispatcher first, because a command that
 // commits for you may not assume a hook is installed to stop it, then the commit
 // carries a Conventional subject built from the row's own title, and only then does
@@ -33,15 +33,41 @@ import { promisify } from 'node:util';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { planDone, planNext } from '../plan/index.mjs';
+import { loadFormat } from '../plan/template.mjs';
 import { assembleBrief } from '../brief/assemble.mjs';
 import { renderGateReport, runGates, stagedFiles } from '../hooks/dispatcher.mjs';
+import { GATES } from '../hooks/gates.mjs';
+import { indexTreeId, passEntryForGate, readLedger } from '../ledger/index.mjs';
+import {
+  DEFAULT_TTL_SECONDS,
+  activeLeases,
+  canonicalLeasePath,
+  readLeases,
+  withLeaseLock,
+  writeLeases,
+} from '../lease.mjs';
+import { SESSION_ENV } from '../agenthooks/policy.mjs';
+import { assertVersionPin } from '../package-version.mjs';
+import { coreIgnoreCase } from '../repo-root.mjs';
 import { readManifest } from '../projection/manifest.mjs';
-import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const exec = promisify(execFile);
 
-/** The state a started slice moves to, spelled the way the tracker template spells it. */
-const STARTED = 'In progress';
+/**
+ * The state a started slice moves to: the template's `started`-role state, not
+ * a hard-coded word. A repository that renamed its states still starts slices,
+ * and one that deleted the in-progress state fails closed in `plan done` on a
+ * word its own template never defined (review 0003 Q23).
+ */
+async function startedState(main) {
+  const loaded = await loadFormat(main);
+  if (loaded.error) return { error: loaded.error, remedy: loaded.remedy };
+  const { format } = loaded;
+  return { state: format.startedWrite ?? format.canonical('in-progress') ?? 'In progress' };
+}
 
 /**
  * A Conventional Commits type: one lower-case word, optionally scoped, optionally
@@ -74,12 +100,16 @@ async function mainCheckout(root) {
   }
 }
 
-/** The branch and worktree a slice owns. Both derive from the id: one id, one spelling. */
+/**
+ * The branch and worktree a slice owns. Both derive from the id: one id, one spelling.
+ * The worktree lives under machine-local state (review 0003 Q19): a worktree inside
+ * the checkout would be recorded as an embedded gitlink and would change the tree id.
+ */
 function places(main, id) {
   const slug = id.toLowerCase();
   return {
     branch: `slice/${slug}`,
-    worktree: join(main, STATE_DIR, 'worktrees', slug),
+    worktree: join(main, LOCAL_DIR, 'worktrees', slug),
   };
 }
 
@@ -96,6 +126,15 @@ function subjectFor(type, id, title) {
   return `${type}(${id.toLowerCase()}): ${description}`;
 }
 
+/**
+ * The trailer of every commit this tool writes: attribution to the tool, in the
+ * form git renders as a co-author. The slice-commit rule ends every message it
+ * defines with the same line, so a commit the tool writes and one an agent
+ * writes from the rule agree on attribution. Module-local: one caller needs no
+ * export, and an export is a promise to a caller (deadcode).
+ */
+const CO_AUTHOR = 'Co-Authored-By: Simt Dev <noreply@simt.space>';
+
 /** Resolve one named slice through `plan next`, which already knows missing and ambiguous. */
 async function resolveSlice(main, id) {
   const found = await planNext(main, id);
@@ -104,8 +143,83 @@ async function resolveSlice(main, id) {
   return { slice: found.next };
 }
 
+/** The session holding the slice, or null when the caller named none: a person
+ *  at a terminal has no session, and starting without one proceeds unleased
+ *  rather than refusing the work. */
+function sliceSession(flags) {
+  const session = flags.session ?? process.env[SESSION_ENV] ?? null;
+  return typeof session === 'string' && session !== '' ? session : null;
+}
+
+/**
+ * The slice's lease path, in the spelling the pre-edit hook compares: the
+ * worktree directory, repository-relative. Entries carry `kind: 'slice'` so a
+ * later schema (review 0003 Q74) can tell slice claims from path claims; the
+ * v1 reader keeps the extra fields without understanding them.
+ */
+function sliceLeaseRel(main, worktree) {
+  return canonicalLeasePath(main, worktree, { ignoreCase: coreIgnoreCase(main) });
+}
+
+/**
+ * Claim the slice for one session: a second session starting the same slice
+ * is refused with the holder's name instead of racing it to the worktree.
+ * A claim held by this session is refreshed; anything else on the file is
+ * left alone.
+ */
+async function claimSlice(main, id, leaseRel, session) {
+  try {
+    return await withLeaseLock(main, async () => {
+      const read = await readLeases(main);
+      if (read.error !== null) return { error: read.error, path: read.path };
+      const held = activeLeases(read);
+      const other = held.find(
+        (l) => l.session !== session && ((l.kind === 'slice' && l.slice === id) || (leaseRel !== null && l.path === leaseRel)),
+      );
+      if (other) return { conflict: other };
+      const mine = {
+        path: leaseRel,
+        session,
+        kind: 'slice',
+        slice: id,
+        expiresAt: Date.now() + DEFAULT_TTL_SECONDS * 1000,
+      };
+      const kept = held.filter((l) => !(l.kind === 'slice' && l.slice === id && l.session === session));
+      const path = await writeLeases(main, [...kept, mine]);
+      return { mine, path };
+    });
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+/**
+ * Release this session's claim on the slice. Best-effort by design: `finish`
+ * calls it after the commit exists, so a lease failure is a note about a TTL
+ * that will clean itself up, never a second failure stacked on a success.
+ */
+async function releaseSlice(main, id, session) {
+  if (session === null) return { released: false };
+  try {
+    return await withLeaseLock(main, async () => {
+      const read = await readLeases(main);
+      if (read.error !== null) return { error: read.error };
+      const held = activeLeases(read);
+      const mine = held.filter((l) => l.kind === 'slice' && l.slice === id && l.session === session);
+      if (mine.length === 0) return { released: false };
+      await writeLeases(
+        main,
+        held.filter((l) => !mine.includes(l)),
+      );
+      return { released: true };
+    });
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
 export async function sliceCommand(sub, args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (sub === 'start') {
     const id = args[0];
     if (!id) return fail(`${CLI} slice start needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
@@ -116,7 +230,16 @@ export async function sliceCommand(sub, args, flags) {
     if (!id) return fail(`${CLI} slice finish needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
     return finishSlice(root, id, flags);
   }
-  return fail(`unknown slice subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} slice start <id>  |  ${CLI} slice finish <id>`);
+  if (sub === 'abandon') {
+    const id = args[0];
+    if (!id) return fail(`${CLI} slice abandon needs a slice id`, EXIT.USAGE, `run: ${CLI} plan next`);
+    return abandonSlice(root, id, flags);
+  }
+  return fail(
+    `unknown slice subcommand ${sub}`,
+    EXIT.USAGE,
+    `run: ${CLI} slice start <id>  |  ${CLI} slice finish <id>  |  ${CLI} slice abandon <id>`,
+  );
 }
 
 async function startSlice(root, id, flags) {
@@ -126,16 +249,25 @@ async function startSlice(root, id, flags) {
   if (resolved.error) return fail(resolved.error, EXIT.USAGE, resolved.remedy);
   const { title, doc } = resolved.slice;
   const { branch, worktree } = places(main, id);
-  const briefPath = join(worktree, STATE_DIR, 'brief.md');
+  // The brief lives beside the worktree, not in it: a file inside the worktree
+  // is untracked content in the slice's own tree, and the tree id must name
+  // the code, not the briefing (review 0003 Q19, Q23).
+  const briefPath = join(main, LOCAL_DIR, 'briefs', `${id.toLowerCase()}.md`);
+  const leaseRel = sliceLeaseRel(main, worktree);
+  const session = sliceSession(flags);
   const task = `${id}: ${String(title ?? '').trim()}`;
   const apply = `run: ${CLI} slice start ${id} --yes`;
 
+  const started = await startedState(main);
+  if (started.error) return fail(started.error, EXIT.USAGE, started.remedy);
   // The row first, dry, against the main checkout: it is the only part of `start`
   // that can refuse for a reason about the tracker rather than about git, and a
   // preview that discovers it late is a preview that half-described the work.
-  const preview = await planDone(main, id, { state: STARTED, dryRun: true });
+  const preview = await planDone(main, id, { state: started.state, dryRun: true });
   if (preview.error) return fail(preview.error, EXIT.USAGE, preview.remedy ?? `run: ${CLI} plan status`);
 
+  const leaseLine = session === null ? 'lease    (no session: pass --session or set SIMT_SESSION to lease the slice)' : `lease    slice ${id} as ${session} (claimed on apply)`;
+
   if (!mode.apply) {
     if (isJson(flags)) {
       emitJson({
@@ -148,6 +280,7 @@ async function startSlice(root, id, flags) {
         branch,
         worktree: relative(main, worktree),
         brief: { path: relative(main, briefPath), bytes: null },
+        lease: session === null ? null : { slice: id, path: leaseRel, session },
         state: { from: preview.from, to: preview.to, changed: preview.wouldChange },
         remedy: apply,
       });
@@ -159,10 +292,11 @@ async function startSlice(root, id, flags) {
       `branch   ${branch}`,
       `worktree ${relative(main, worktree)}`,
       `brief    ${relative(main, briefPath)} (assembled on apply)`,
+      leaseLine,
       `state    ${preview.from} -> ${preview.to}`,
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -178,6 +312,26 @@ async function startSlice(root, id, flags) {
     return fail(`the index at ${main} is empty and will not build here`, EXIT.UNSUPPORTED, `run: ${CLI} index`);
   }
 
+  // Claimed before the worktree exists: a second session starting the same slice
+  // is refused here, not after a worktree that then has to be taken back down.
+  let lease = null;
+  if (session !== null) {
+    const claimed = await claimSlice(main, id, leaseRel, session);
+    if (claimed.error) {
+      return fail(`the slice could not be leased: ${claimed.error}`, EXIT.FAIL, `run: ${CLI} lease to see every claim`);
+    }
+    if (claimed.conflict) {
+      const holder = claimed.conflict.session;
+      const until = new Date(claimed.conflict.expiresAt).toISOString();
+      return fail(
+        `${id} is already started by session ${holder} (lease until ${until})`,
+        EXIT.FAIL,
+        `wait for the TTL or ask ${holder} to finish or abandon it; run: ${CLI} lease to see every claim`,
+      );
+    }
+    lease = claimed.mine;
+  }
+
   try {
     await git(main, ['worktree', 'add', '-b', branch, worktree]);
   } catch (error) {
@@ -185,15 +339,16 @@ async function startSlice(root, id, flags) {
     return fail(`the worktree could not be created: ${detail}`, EXIT.FAIL, `run: git -C ${main} worktree list`);
   }
 
-  await mkdir(join(worktree, STATE_DIR), { recursive: true });
+  await mkdir(dirname(briefPath), { recursive: true });
   await writeFile(briefPath, packet.packed.text, 'utf8');
 
-  const row = await planDone(main, id, { state: STARTED, dryRun: false });
+  const row = await planDone(main, id, { state: started.state, dryRun: false });
   if (row.error) {
     return fail(`${branch} exists with its brief, but the tracker row was not updated: ${row.error}`, EXIT.FAIL, row.remedy ?? `run: ${CLI} plan status`);
   }
 
   const bytes = Buffer.byteLength(packet.packed.text);
+  if (session === null) note('note     no session: the slice is not leased; a second start will not see this one');
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -204,6 +359,7 @@ async function startSlice(root, id, flags) {
       branch,
       worktree: relative(main, worktree),
       brief: { path: relative(main, briefPath), bytes },
+      lease,
       state: { from: row.from, to: row.to, changed: row.changed },
     });
     return EXIT.OK;
@@ -214,18 +370,62 @@ async function startSlice(root, id, flags) {
     `branch   ${branch}`,
     `worktree ${relative(main, worktree)}`,
     `brief    ${relative(main, briefPath)}  ${bytes} bytes`,
+    lease === null ? 'lease    (none)' : `lease    slice ${id} as ${session}`,
     `state    ${row.from} -> ${row.to}`,
   ];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
+/**
+ * Split the declared gates into the ones that must run and the ones the ledger
+ * already proves: a gate with a passing entry on exactly this staged tree, and
+ * no later failure for the same gate on the same tree, does not run again.
+ * That is the double gate the review verified — the dispatcher, then the
+ * commit hook — and the seed of the gate-run cache (review 0003 Q23).
+ *
+ * Fail-closed throughout: no tree, no ledger, a version mismatch, or an
+ * unknown gate all mean the gate runs. An entry recorded under another binary
+ * is not evidence for this one, so a pin mismatch disables the cache and
+ * routes through `runGates`, which fails on the mismatch itself.
+ */
+async function splitGates(root, declared, manifestDoc) {
+  if (!Array.isArray(declared) || declared.length === 0) return { fresh: [], skipped: [], tree: null };
+  if (assertVersionPin(manifestDoc)) return { fresh: [...declared], skipped: [], tree: null };
+  const stagedTree = await indexTreeId(root).catch(() => null);
+  if (stagedTree === null) return { fresh: [...declared], skipped: [], tree: null };
+  const { entries } = await readLedger(root).catch(() => ({ entries: [] }));
+  const fresh = [];
+  const skipped = [];
+  for (const name of declared) {
+    if (GATES[name] === undefined) {
+      fresh.push(name);
+      continue;
+    }
+    const pass = passEntryForGate(entries, name, stagedTree);
+    if (pass === null) fresh.push(name);
+    else skipped.push({ name, at: pass.ts });
+  }
+  return { fresh, skipped, tree: stagedTree };
+}
+
+/** A gate result that did not run: the ledger line is the evidence. */
+function cachedResult({ name, at }) {
+  return {
+    name,
+    status: 'passed',
+    detail: `already passed on this tree at ${at} (ledger); not re-run`,
+    cached: true,
+  };
+}
+
 async function finishSlice(root, id, flags) {
   const mode = writeMode(flags);
   const main = await mainCheckout(root);
   const resolved = await resolveSlice(main, id);
   if (resolved.error) return fail(resolved.error, EXIT.USAGE, resolved.remedy);
   const { title, doc } = resolved.slice;
+  const { branch, worktree } = places(main, id);
 
   const type = String(flags.type ?? 'feat');
   if (!TYPE.test(type)) {
@@ -245,10 +445,15 @@ async function finishSlice(root, id, flags) {
   const apply = `run: ${CLI} slice finish ${id}${test ? ` --test ${JSON.stringify(test)}` : ''} --yes`;
 
   const staged = await stagedFiles(root);
+  const split = await splitGates(root, declared, manifest.manifest);
 
   if (!mode.apply) {
     const row = await planDone(main, id, { sha: null, test, dryRun: true });
     if (row.error) return fail(row.error, EXIT.USAGE, row.remedy ?? `run: ${CLI} plan status`);
+    const gateLine =
+      declared.length === 0
+        ? '(none declared)'
+        : `${declared.join(', ')}${split.skipped.length > 0 ? `  (already passed on this tree: ${split.skipped.map((s) => s.name).join(', ')})` : ''}`;
     if (isJson(flags)) {
       emitJson({
         ok: true,
@@ -258,7 +463,7 @@ async function finishSlice(root, id, flags) {
         dryRun: true,
         subject,
         staged,
-        gates: { event: 'pre-commit', declared },
+        gates: { event: 'pre-commit', declared, skipped: split.skipped.map((s) => s.name) },
         state: { from: row.from, to: row.to, changed: row.wouldChange },
         remedy: apply,
       });
@@ -267,25 +472,72 @@ async function finishSlice(root, id, flags) {
     const lines = [
       `repo     ${root}`,
       `slice    ${id}  ${doc}`,
-      `gates    pre-commit  ${declared.length > 0 ? declared.join(', ') : '(none declared)'} (run on apply)`,
+      `gates    pre-commit  ${gateLine} (run on apply)`,
       `staged   ${staged.length} file(s)${staged.length === 0 ? '  (finish refuses without one)' : ''}`,
       `subject  ${subject}`,
       `state    ${row.from} -> ${row.to}`,
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
+  // The commit lands on the slice branch or not at all: finishing from `main`
+  // commits main's tree under the slice's subject, which is the defect this
+  // guard closes (review 0003 Q23).
+  const head = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => null);
+  if (head !== branch) {
+    return fail(
+      `not on the slice branch: HEAD is ${head ?? 'unknown'}, expected ${branch}`,
+      EXIT.USAGE,
+      `move to the slice worktree (${relative(main, worktree)}) and rerun: ${apply}`,
+    );
+  }
+
   if (staged.length === 0) {
     return fail(`${root} has nothing staged to commit`, EXIT.USAGE, `stage what the slice changed, then rerun: ${apply}`);
   }
 
   // The gates the hook would run, run here. This command is the one place a commit
   // happens where a hook could not have stopped it, so it runs the same dispatcher
-  // over the same event, in the checkout that holds the staged diff.
-  const gates = await runGates('pre-commit', { root, manifest: manifest.manifest });
-  if (gates.error) return fail(gates.error, EXIT.USAGE);
+  // over the same event, in the checkout that holds the staged diff — except the
+  // gates the ledger already proves for this tree, which are reported, not re-run.
+  const manifestForGates =
+    split.fresh.length === declared.length
+      ? manifest.manifest
+      : { ...manifest.manifest, gates: { ...(manifest.manifest?.gates ?? {}), preCommit: split.fresh } };
+  const freshGates =
+    split.fresh.length === 0 && declared.length > 0
+      ? { event: 'pre-commit', gates: [], failed: false, notes: [] }
+      : await runGates('pre-commit', { root, manifest: manifestForGates });
+  if (freshGates.error) return fail(freshGates.error, EXIT.USAGE);
+
+  // A gate that rewrites the tree (the formatter restaging) moves the commit
+  // off the tree the skipped gates passed on. Their evidence is stale, so they
+  // run once on the new tree; those results stand, the way fresh results do.
+  let skipped = split.skipped;
+  if (skipped.length > 0 && split.tree !== null) {
+    const afterTree = await indexTreeId(root).catch(() => null);
+    if (afterTree !== null && afterTree !== split.tree) {
+      const { entries } = await readLedger(root).catch(() => ({ entries: [] }));
+      const stale = skipped.filter((s) => passEntryForGate(entries, s.name, afterTree) === null);
+      if (stale.length > 0) {
+        const rerun = await runGates('pre-commit', {
+          root,
+          manifest: { ...manifest.manifest, gates: { ...(manifest.manifest?.gates ?? {}), preCommit: stale.map((s) => s.name) } },
+        });
+        if (rerun.error) return fail(rerun.error, EXIT.USAGE);
+        freshGates.gates.push(...rerun.gates);
+        if (rerun.failed) freshGates.failed = true;
+        for (const n of rerun.notes ?? []) freshGates.notes.push(n);
+        skipped = skipped.filter((s) => !stale.some((t) => t.name === s.name));
+      }
+    }
+  }
+
+  const byName = new Map(freshGates.gates.map((g) => [g.name, g]));
+  const combined = declared.map((name) => byName.get(name) ?? cachedResult(skipped.find((s) => s.name === name)));
+  const gates = { ...freshGates, gates: combined };
 
   if (gates.failed) {
     const failed = gates.gates.filter((g) => g.status === 'failed').map((g) => g.name).join(', ');
@@ -303,17 +555,18 @@ async function finishSlice(root, id, flags) {
       return EXIT.FAIL;
     }
     for (const n of gates.notes ?? []) note(`note     ${n}`);
-    emit(renderGateReport('pre-commit', declared, gates).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(renderGateReport('pre-commit', declared, gates).join('\n'));
     return EXIT.FAIL;
   }
 
   let sha = null;
+  const message = `${subject}\n\n${CO_AUTHOR}`;
   try {
-    await git(root, ['commit', '-m', subject]);
+    await git(root, ['commit', '-m', message]);
     sha = await git(root, ['rev-parse', 'HEAD']);
   } catch (error) {
     const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
-    return fail(`the gates passed but the commit failed: ${detail}`, EXIT.FAIL, `run: git -C ${root} commit -m ${JSON.stringify(subject)}`);
+    return fail(`the gates passed but the commit failed: ${detail}`, EXIT.FAIL, `run: git -C ${root} commit -m ${JSON.stringify(message)}`);
   }
 
   const row = await planDone(main, id, { sha, test, dryRun: false });
@@ -321,6 +574,12 @@ async function finishSlice(root, id, flags) {
     return fail(`${sha} is committed, but the tracker row could not record it: ${row.error}`, EXIT.FAIL, row.remedy ?? `run: ${CLI} plan status`);
   }
 
+  // The slice is done: its lease goes with it. A failure here is a note — the
+  // commit exists, and a lease the TTL will reap is not a second failure.
+  const released = await releaseSlice(main, id, sliceSession(flags));
+  if (released.error) note(`note     the slice lease could not be released (${released.error}); the TTL reaps it`);
+
+  for (const s of skipped) note(`note     ${s.name}: already passed on this tree; not re-run`);
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -348,6 +607,117 @@ async function finishSlice(root, id, flags) {
   ];
   if (row.evidenceRecorded) lines.push(`evidence ${sha}${test ? `  test: ${test}` : ''}`);
   else if (row.evidenceNote) lines.push(`note     ${row.evidenceNote}`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
+  return EXIT.OK;
+}
+
+/**
+ * `simt slice abandon <id>`: take the slice back down. The worktree is
+ * removed, the branch deleted, and the tracker row returns to the ready
+ * state — abandonment is a state the tracker can see, not a worktree that
+ * silently rots. Preview names everything that would be destroyed; `--yes`
+ * is the consent to destroy it (review 0003 Q23).
+ */
+async function abandonSlice(root, id, flags) {
+  const mode = writeMode(flags);
+  const main = await mainCheckout(root);
+  const resolved = await resolveSlice(main, id);
+  if (resolved.error) return fail(resolved.error, EXIT.USAGE, resolved.remedy);
+  const { doc } = resolved.slice;
+  const { branch, worktree } = places(main, id);
+  const session = sliceSession(flags);
+  const apply = `run: ${CLI} slice abandon ${id} --yes`;
+
+  const loaded = await loadFormat(main);
+  if (loaded.error) return fail(loaded.error, EXIT.USAGE, loaded.remedy);
+  const readyDisplay = loaded.format.canonical(loaded.format.ready) ?? 'Queued';
+  const preview = await planDone(main, id, { state: readyDisplay, dryRun: true });
+  if (preview.error) return fail(preview.error, EXIT.USAGE, preview.remedy ?? `run: ${CLI} plan status`);
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'slice abandon',
+        root,
+        id,
+        dryRun: true,
+        branch,
+        worktree: relative(main, worktree),
+        state: { from: preview.from, to: preview.to, changed: preview.wouldChange },
+        remedy: apply,
+      });
+      return EXIT.OK;
+    }
+    const lines = [
+      `repo     ${root}`,
+      `slice    ${id}  ${doc}`,
+      `remove   ${relative(main, worktree)} and branch ${branch} (on apply)`,
+      `state    ${preview.from} -> ${preview.to}`,
+      `apply    ${apply}`,
+    ];
+    emit(lines.join('\n'));
+    return EXIT.OK;
+  }
+
+  // Abandoning from inside the worktree would pull the floor out: the shell's
+  // own directory is the thing being removed. Compared through git, not through
+  // strings, because the caller's spelling of the path may differ in symlinks.
+  const top = await git(root, ['rev-parse', '--show-toplevel']).catch(() => null);
+  if (top !== null && (top === worktree || top.startsWith(`${worktree}/`))) {
+    return fail(
+      `cannot abandon ${id} from inside its worktree`,
+      EXIT.USAGE,
+      `move to the main checkout (${main}) and rerun: ${apply}`,
+    );
+  }
+
+  const removed = [];
+  try {
+    await git(main, ['worktree', 'remove', '--force', worktree]);
+    removed.push(`removed  ${relative(main, worktree)}`);
+  } catch (error) {
+    const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
+    removed.push(`kept     ${relative(main, worktree)} (${detail})`);
+  }
+  try {
+    await git(main, ['branch', '-D', branch]);
+    removed.push(`deleted  ${branch}`);
+  } catch (error) {
+    const detail = String(error.stderr ?? error.message ?? error).trim().split('\n')[0];
+    removed.push(`kept     ${branch} (${detail})`);
+  }
+
+  const row = await planDone(main, id, { state: readyDisplay, dryRun: false });
+  if (row.error) {
+    return fail(
+      `the worktree is down, but the tracker row was not updated: ${row.error}`,
+      EXIT.FAIL,
+      row.remedy ?? `run: ${CLI} plan status`,
+    );
+  }
+
+  const released = await releaseSlice(main, id, session);
+  const leaseLine =
+    released.released === true
+      ? `released the slice lease`
+      : released.error
+        ? `the slice lease could not be released (${released.error}); the TTL reaps it`
+        : 'no slice lease was held';
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'slice abandon',
+      root,
+      id,
+      branch,
+      worktree: relative(main, worktree),
+      lease: released.released === true ? { slice: id, session } : null,
+      state: { from: row.from, to: row.to, changed: row.changed },
+    });
+    return EXIT.OK;
+  }
+  const lines = [`repo     ${root}`, `slice    ${id}  ${doc}`, ...removed, `state    ${row.from} -> ${row.to}`, `lease    ${leaseLine}`];
+  emit(lines.join('\n'));
   return EXIT.OK;
 }