@erclx/aitk 3.48.0 → 3.48.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.48.0",
+  "version": "3.48.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/git-worktree/REQUIREMENT.md

@@ -14,7 +14,7 @@ Without this skill, linked worktrees accumulate past the point where any of them
 - Resolve merge state per branch from the pull request first, and fall back to local ancestry when no pull request exists
 - Match the ancestry fallback against the branch name alone. `git branch --merged` decorates the current branch and every branch checked out in a linked worktree, which is the whole set this skill enumerates.
 - Remove the worktree and its local branch together, since either one left alone is the state the skill exists to prevent
-- Exclude four kinds of row from the remove set: the main root, the current session's worktree, any dirty tree, and any worktree registered from outside the path prefix `claude-worktree` creates under
+- Exclude five kinds of row from the remove set: the main root, the current session's worktree, any dirty tree, any worktree registered from outside the path prefix `claude-worktree` creates under, and any worktree a live session is occupying
 - Give every skipped row a one-word reason, so the skip is a decision the user can overturn rather than a silence
 - Pick exactly one mode. Listing and removing are different requests and inferring both from one invocation removes worktrees the user meant to read about.
 
@@ -22,6 +22,7 @@ Without this skill, linked worktrees accumulate past the point where any of them
 
 - Enter or create a worktree. The description states the boundary so the model routes entry elsewhere rather than discovering it here.
 - Remove a worktree with uncommitted work, whatever its merge state
+- Remove a worktree a live session is occupying, whatever its merge state
 - Remove the worktree the session is currently running in
 - Emit anything after the result line
 

package/claude/skills/git-worktree/SKILL.md

@@ -55,6 +55,10 @@ Determine current: the row whose `path` equals `git rev-parse --show-toplevel`.
 
 Determine provenance: a non-main row is `foreign` when its `path` does not start with `<MAIN_ROOT>/.claude/worktrees/`. That prefix is the folder `claude-worktree` creates under, a convention of that skill rather than a fact this one owns. A tree an operator registered by hand anywhere else on disk reads as `foreign`. Step 1 has already marked the main row `main`, so it never reaches this test.
 
+Determine occupancy: run `aitk sessions list --json` once for the whole enumeration, never once per row. Resolve each enumerated row's `path` and each live session's `worktree` field with `realpath` before comparing, since a session registered from a second clone of this repository reports a path under that clone rather than under `MAIN_ROOT`, and a raw string compare would hold nothing back. A row is `occupied` when a resolved `worktree` from any live session equals its resolved `path`. A resolved session `worktree` outside `MAIN_ROOT` names a different checkout, so it clears no row here and marks none as occupied.
+
+The roster is unreadable when the command exits non-zero, when its JSON carries a `reason` field instead of a populated `sessions` array, or when `sessions` is non-empty but no entry carries a `worktree` key at all, which is the shape an older binary prints and cannot be told apart from a roster answering that nothing is occupied. `list` leaves the Notes column silent on that failure rather than changing behavior beyond it. `cleanup` refuses instead, stated in its own section below.
+
 ## `list` mode
 
 Print the enumeration as a table, then stop. `list` has no final command.
@@ -64,7 +68,7 @@ Print the enumeration as a table, then stop. `list` has no final command.
 | -- | ---------------------------------- | ----------------- | -------- | ------ | -------- |
 ```
 
-Notes column shows the first that applies of `current`, `foreign`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`). A `foreign` row sits outside `MAIN_ROOT`, so print its path in full.
+Notes column shows the first that applies of `current`, `occupied`, `foreign`, `dirty`, or empty. Show paths relative to `MAIN_ROOT` (`.claude/worktrees/<name>`). A `foreign` row sits outside `MAIN_ROOT`, so print its path in full.
 
 After the table, append a one-line hint:
 
@@ -73,15 +77,18 @@ After the table, append a one-line hint:
 
 ## `cleanup` mode
 
+If Enumeration marked the roster unreadable, stop: `❌ Session roster unreadable, so occupancy cannot be checked. Resolve the aitk sessions list failure, then re-run cleanup.` Hold every non-main row rather than computing the remove set from the other five tests alone, since removing a tree a live session holds is the failure this skill exists to prevent and a sweep that removes nothing costs one re-run.
+
 From the enumeration, include a worktree in the remove set when all hold:
 
 - Not the main row.
 - Not the current session's worktree.
+- Not occupied by a live session.
 - Not a `foreign` tree.
 - State is `merged` or `merged (local)`.
 - Working tree is clean.
 
-Every other non-main row goes to the skip set with a one-word reason, the first that applies in this order: `current`, `foreign`, `dirty`, `open`, `closed`, `unmerged`. A `foreign` tree that is also dirty reports `foreign`, since `dirty` is a state the operator can clear and `foreign` is not. Leading with the transient reason invites a commit or stash that changes nothing, after which the row reports `foreign` and holds back anyway.
+Every other non-main row goes to the skip set with a one-word reason, the first that applies in this order: `current`, `occupied`, `foreign`, `dirty`, `open`, `closed`, `unmerged`. A `foreign` tree that is also dirty reports `foreign`, since `dirty` is a state the operator can clear and `foreign` is not. Leading with the transient reason invites a commit or stash that changes nothing, after which the row reports `foreign` and holds back anyway.
 
 ### Preview
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.48.0",
+  "version": "3.48.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-path.sh

@@ -10,15 +10,44 @@
 # reports no writes at all. `scripts/eval/run.sh` keeps its fixture outside the
 # repository for the same reason.
 #
-# Twin of `SANDBOX_DIR` in `src/commands/sandbox.ts`. The exec boundary rules out
+# Mints a short random per-run identifier the first time it is asked for, then
+# holds it in AITK_SANDBOX_RUN_ID for the rest of this process. A direct call
+# (not `$(...)`) exports it into the caller's own shell, which is what lets
+# `run.sh` mint once and have manage-sandbox.sh and the check it shells out to
+# both inherit the same id as ordinary children. A call already carrying the
+# variable, inherited from such a parent, reuses it rather than minting a new one.
+#
+# Twin of `mintSandboxRunId` in `src/commands/sandbox.ts`.
+mint_sandbox_run_id() {
+  if [ -z "${AITK_SANDBOX_RUN_ID:-}" ]; then
+    AITK_SANDBOX_RUN_ID="$(date +%s)-$$-$RANDOM"
+  fi
+  export AITK_SANDBOX_RUN_ID
+}
+
+# The base every per-run tree nests under, with no run id appended. Split out
+# of `resolve_sandbox_dir` so a caller that needs to recognize any run's tree,
+# such as `require_project_root` in `scripts/lib/ui.sh`, tests against this
+# prefix instead of a single resolved path that changes on every call.
+sandbox_dir_prefix() {
+  printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
+}
+
+# Twin of `sandboxTree` in `src/commands/sandbox.ts`. The exec boundary rules out
 # a shared constant, so a change to the default lands on both sides.
+#
+# A bare fall-through with no per-run component is one path per machine, so
+# two sessions resolving the default at once would provision over each other
+# with neither told. `mint_sandbox_run_id` is what makes two such sessions
+# land on two different trees rather than one.
 resolve_sandbox_dir() {
   if [ -n "${AITK_SANDBOX_DIR:-}" ]; then
     printf '%s\n' "$AITK_SANDBOX_DIR"
     return 0
   fi
 
-  printf '%s/aitk/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
+  mint_sandbox_run_id
+  printf '%s-%s\n' "$(sandbox_dir_prefix)" "$AITK_SANDBOX_RUN_ID"
 }
 
 # Collapses repeated separators, folds `.` and `..` segments, and strips every

package/scripts/lib/ui.sh

@@ -115,9 +115,15 @@ guard_root() {
 require_project_root() {
   local GREEN RED YELLOW WHITE GREY NC
   set_palette 2
-  local sandbox
-  sandbox="$(resolve_sandbox_dir)"
-  if [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]]; then
+  local sandbox in_sandbox=0
+  if [ -n "${AITK_SANDBOX_DIR:-}" ]; then
+    sandbox="$AITK_SANDBOX_DIR"
+    [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* ]] && in_sandbox=1
+  else
+    sandbox="$(sandbox_dir_prefix)"
+    [[ "$PWD" == "$sandbox" || "$PWD" == "$sandbox"/* || "$PWD" == "$sandbox"-* ]] && in_sandbox=1
+  fi
+  if [ "$in_sandbox" -eq 1 ]; then
     echo -e "${GREY}┌${NC}" >&2
     log_error "Execution restricted: Command cannot be run from inside the sandbox environment."
   fi

package/src/commands/sandbox.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
@@ -22,6 +21,7 @@ import {
   type RunEnvelope,
   type Verdict,
 } from '@/sandbox/expect'
+import { sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
   intro,
@@ -64,29 +64,6 @@ function reportAbsentScenarioTree(): boolean {
   return true
 }
 
-/**
- * The provisioned tree, as opposed to `SANDBOX_DIR` above, which holds the
- * scenario scripts. It sits outside the toolkit worktree so the toolkit's own
- * `CLAUDE.md` stays off the ancestor chain of the session `run.sh` spawns with
- * cwd here.
- *
- * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
- * boundary rules out a shared constant, so a change to the default lands on both
- * sides.
- */
-function sandboxTree(): string {
-  const override = process.env.AITK_SANDBOX_DIR
-  if (override !== undefined && override !== '') return override
-
-  const state = process.env.XDG_STATE_HOME
-  const base =
-    state !== undefined && state !== ''
-      ? state
-      : join(homedir(), '.local', 'state')
-
-  return join(base, 'aitk', 'sandbox')
-}
-
 /**
  * Holds fixture content for scenarios rather than scenarios of its own.
  * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.

package/src/sandbox/tree.ts

@@ -0,0 +1,47 @@
+import { randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Mints a short per-run identifier the first time it is asked for and holds it
+ * in `AITK_SANDBOX_RUN_ID` for the rest of this process, so a script that
+ * spawns a child inheriting `process.env` — `run.sh` calling `manage-sandbox.sh`
+ * and then `aitk sandbox check` — resolves the same tree in every one of them.
+ * A process that already carries the variable, inherited from such a parent,
+ * reuses it rather than minting a new one.
+ *
+ * Twin of `mint_sandbox_run_id` in `scripts/lib/sandbox-path.sh`.
+ */
+export function mintSandboxRunId(): string {
+  const existing = process.env.AITK_SANDBOX_RUN_ID
+  if (existing !== undefined && existing !== '') return existing
+
+  const id = randomBytes(4).toString('hex')
+  process.env.AITK_SANDBOX_RUN_ID = id
+  return id
+}
+
+/**
+ * The provisioned tree's path, split out of `src/commands/sandbox.ts` so the
+ * per-run default is unit-testable on its own rather than only through the
+ * command's registration.
+ *
+ * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
+ * boundary rules out a shared constant, so a change to the default lands on
+ * both sides. The fall-through used to be one path per machine, so two
+ * sessions each resolving the default at once provisioned over each other
+ * with neither told; `mintSandboxRunId` gives the path a per-run component
+ * instead, which is what makes two such sessions land on two different trees.
+ */
+export function sandboxTree(): string {
+  const override = process.env.AITK_SANDBOX_DIR
+  if (override !== undefined && override !== '') return override
+
+  const state = process.env.XDG_STATE_HOME
+  const base =
+    state !== undefined && state !== ''
+      ? state
+      : join(homedir(), '.local', 'state')
+
+  return join(base, 'aitk', `sandbox-${mintSandboxRunId()}`)
+}