@autosk/worktree 0.1.0 → 0.1.2

package/README.md

@@ -22,8 +22,11 @@ autosk.registerWorkflow({
 ```
 
 Each isolated task runs in its own checkout so concurrent tasks never collide on
-the working tree. The engine calls `acquire` before scheduling a session (its
-returned `cwd` becomes `ctx.cwd`) and `release` on every transition.
+the working tree. The engine calls `acquire` before scheduling each session (its
+returned `cwd` becomes `ctx.cwd`) and `reap` only on a terminal transition
+(`done`/`cancel`). This provider has no live env to stop, so it **omits**
+`release` entirely — keeping the checkout on disk across sibling/human-park steps
+is exactly the absence of teardown.
 
 ## Behaviour
 
@@ -35,22 +38,27 @@ either stack resolves to the same place:
 branch = autosk/<task-id>
 ```
 
-- **acquire** — allocates the per-task worktree on branch `autosk/<task-id>`
-  (off `HEAD`), or re-uses it when a prior step kept it. A **missing** dir is
-  re-allocated on the *existing* branch (v1 "missing worktree auto-recovery").
-  Returns `{ cwd, meta: { branch, projectRoot } }`.
-- **release(`{terminal:true}`)** (done / cancel) — removes the worktree dir but
+- **acquire** (ensure-ready) — allocates the per-task worktree on branch
+  `autosk/<task-id>` (off `HEAD`), or re-uses it when a prior step kept it. A
+  **missing** dir is re-allocated on the *existing* branch (v1 "missing worktree
+  auto-recovery"). Idempotent and re-entered per step. Returns
+  `{ cwd, meta: { branch, projectRoot } }`.
+- **(no `release`)** — sibling step and human-park keep the dir on disk
+  untouched, so the next `acquire` re-uses the same checkout. There is nothing to
+  quiesce, so the method is omitted.
+- **reap** (destroy-on-terminal, done / cancel) — keyed by `(projectRoot,
+  taskId)`, so it works with no live handle (engine terminal, a manual
+  `done`/`cancel` after a park, or crash recovery). Removes the worktree dir but
   **preserves** the `autosk/<task-id>` branch (so the work survives for review /
-  merge).
-- **release(`{terminal:false}`)** (sibling step / human-park) — keeps the dir so
-  the next step re-uses the same checkout.
+  merge). With `force:false` it refuses to discard uncommitted changes and
+  reports `{ removed:false, dirty:true }`; `force:true` removes regardless.
 
 ### Failure handling
 
 The provider **only throws descriptive messages** — the engine wraps them
-(`isolation_acquire_failed: …` on acquire, `isolation_release_failed: …` on a
-happy-path release) and parks the task to `human`. It never parks or formats
-those prefixes itself. Throw cases:
+(`isolation_acquire_failed: …` on acquire, `isolation_reap_failed: …` on a
+terminal reap) and parks the task to `human`. It never parks or formats those
+prefixes itself. Throw cases:
 
 - **non-git root** — `not a git repository: <root>` (the project root isn't a
   git repo).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autosk/worktree",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shipped autoskd v2 isolation provider: per-task git worktree isolation (worktreeIsolation()) attachable to any workflow.",
   "license": "MIT",
   "author": "wierdbytes",
@@ -16,8 +16,7 @@
   "keywords": [
     "autosk",
     "autosk-extension",
-    "git-worktree",
-    "isolation"
+    "autosk-isolation"
   ],
   "type": "module",
   "publishConfig": {

package/src/index.ts

@@ -2,12 +2,15 @@
  * `@autosk/worktree` — the shipped `worktreeIsolation()` provider (plan §3.5).
  *
  * Ports v1's per-task git worktree isolation onto the v2
- * {@link IsolationProvider} contract. The
- * engine (`daemon/core/src/engine/session.ts`) calls `acquire` before scheduling
- * an isolated session and `release` on every transition; FAILURES ARE WRAPPED BY
- * THE ENGINE (`acquire` throw → `isolation_acquire_failed: <msg>`, happy-path
- * `release` throw → `isolation_release_failed: <msg>`), so this provider just
- * throws descriptive messages — it never parks or formats those prefixes itself.
+ * {@link IsolationProvider} contract. The engine
+ * (`daemon/core/src/engine/session.ts`) calls `acquire` before scheduling an
+ * isolated session (idempotently re-used across the run's steps) and `reap` on a
+ * terminal transition (`done`/`cancel`). A worktree has nothing to "stop", so
+ * this provider omits `release` entirely — keeping the dir across a step→step or
+ * a human-park IS the absence of teardown. FAILURES ARE WRAPPED BY THE ENGINE
+ * (`acquire` throw → `isolation_acquire_failed: <msg>`, `reap` throw →
+ * `isolation_reap_failed: <msg>`), so this provider just throws descriptive
+ * messages — it never parks or formats those prefixes itself.
  *
  * Deterministic mapping (byte-identical to the v1 Go/Rust slug so a worktree
  * allocated by either stack resolves to the same place):
@@ -22,7 +25,7 @@ import { createHash } from "node:crypto";
 import { mkdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
-import type { IsolationHandle, IsolationProvider } from "@autosk/sdk";
+import type { IsolationHandle, IsolationProvider, IsolationReapResult } from "@autosk/sdk";
 
 /** Options for {@link worktreeIsolation}. */
 export interface WorktreeIsolationOptions {
@@ -42,7 +45,7 @@ export const WORKTREE_TAG = "worktree";
 /** Provider-internal bookkeeping carried on every {@link IsolationHandle}. */
 interface WorktreeMeta extends Record<string, unknown> {
   branch: string;
-  /** The canonical project root — `release` needs it to drive `git -C <root>`. */
+  /** The canonical project root the worktree was checked out from. */
   projectRoot: string;
 }
 
@@ -50,9 +53,9 @@ interface WorktreeMeta extends Record<string, unknown> {
  * Builds the shipped worktree {@link IsolationProvider}. Attach it to a workflow
  * via `isolation: worktreeIsolation()` (plan §3.6). `acquire` allocates (or
  * re-uses / re-allocates) the per-task worktree and hands the engine its path as
- * `ctx.cwd`; `release({terminal:true})` removes the dir but PRESERVES the
- * `autosk/<task>` branch, `release({terminal:false})` keeps the dir so the next
- * sibling step re-uses it.
+ * `ctx.cwd`; `reap` removes the dir on a terminal transition but PRESERVES the
+ * `autosk/<task>` branch. There is no `release`: the dir is simply kept across
+ * step→step and human-park (the env is reused on the next `acquire`).
  */
 export function worktreeIsolation(opts: WorktreeIsolationOptions = {}): IsolationProvider {
   const gitBin = opts.gitBin ?? "git";
@@ -95,15 +98,11 @@ export function worktreeIsolation(opts: WorktreeIsolationOptions = {}): Isolatio
       return { cwd: path, meta };
     },
 
-    async release(handle, { terminal }): Promise<void> {
-      // Non-terminal (sibling step / human-park): keep the dir so the next step
-      // re-uses the same checkout. Nothing to do.
-      if (!terminal) return;
-      const meta = (handle.meta ?? {}) as Partial<WorktreeMeta>;
-      const path = handle.cwd;
-      const canon = meta.projectRoot ? canonRoot(meta.projectRoot) : "";
+    async reap({ projectRoot, taskId }, { force }): Promise<IsolationReapResult> {
+      const canon = canonRoot(projectRoot);
+      const path = pathFor(canon, taskId, opts.home);
       await ensureGitAvailable(gitBin);
-      await onTerminal(gitBin, canon, path);
+      return cleanupTerminal(gitBin, canon, path, force);
     },
   };
 }
@@ -172,6 +171,47 @@ async function verifyHealthy(gitBin: string, canon: string, path: string): Promi
   }
 }
 
+/**
+ * The terminal-cleanup core behind {@link IsolationProvider.reap} (session-free,
+ * keyed by identity).
+ *
+ * Removes the worktree dir while PRESERVING its branch, gated on `force`:
+ * `force:false` leaves a dirty checkout in place and reports `{dirty:true}` so
+ * the caller can warn; `force:true` removes it regardless. A vanished/absent dir
+ * is a no-op (`{removed:false}`); a stranded dir that is not a healthy checkout
+ * cannot be "dirty" in any recoverable sense and is reaped.
+ */
+async function cleanupTerminal(
+  gitBin: string,
+  canon: string,
+  path: string,
+  force: boolean,
+): Promise<IsolationReapResult> {
+  if (!existsPath(path)) {
+    // Nothing on disk; best-effort clear of any stale git registration.
+    if (canon !== "" && (await isGitRepo(gitBin, canon))) await pruneWorktrees(gitBin, canon);
+    return { removed: false, dirty: false };
+  }
+  const { dirty, detail } = await worktreeDirty(gitBin, path);
+  if (dirty && !force) return { removed: false, dirty: true, detail };
+  await onTerminal(gitBin, canon, path);
+  return { removed: true, dirty, detail: dirty ? detail : undefined };
+}
+
+/**
+ * Reports whether the checkout at `path` has uncommitted changes (modified,
+ * staged, OR untracked — anything `git status --porcelain` surfaces). A path
+ * that is not a healthy worktree (status errors) reads as NOT dirty: there is no
+ * recoverable working state to protect, so the caller may reap the stranded dir.
+ */
+async function worktreeDirty(gitBin: string, path: string): Promise<{ dirty: boolean; detail: string }> {
+  const r = await runGit(gitBin, path, ["status", "--porcelain", "--untracked-files=all"]);
+  if (r.code !== 0) return { dirty: false, detail: "" };
+  const lines = r.stdout.split("\n").filter((l) => l.trim() !== "");
+  if (lines.length === 0) return { dirty: false, detail: "" };
+  return { dirty: true, detail: `${lines.length} uncommitted file(s)` };
+}
+
 /** Removes the worktree dir on a terminal transition while PRESERVING its branch. */
 async function onTerminal(gitBin: string, canon: string, path: string): Promise<void> {
   // git itself broken / no project root → still try to reap the on-disk dir.