mixdog 1.2.3 → 1.2.4

package/src/runtime/shared/transcript-turn-keys.mjs

@@ -0,0 +1,33 @@
+function stableItemKey(item, index) {
+  if (item?.id !== undefined && item?.id !== null) return String(item.id);
+  return `${item?.kind || 'item'}:${item?.text || item?.label || item?.status || ''}:${index}`;
+}
+
+/** Completed attempts keep the same identity in live, full and tail projections. */
+export function transcriptTurnKeys(items) {
+  const transcript = Array.isArray(items) ? items : [];
+  const keys = [];
+  let activeTurn = null;
+  let start = 0;
+  for (let index = 0; index < transcript.length; index += 1) {
+    const item = transcript[index];
+    if (item?.kind === 'user') {
+      activeTurn = `turn:${stableItemKey(item, index)}`;
+      start = index;
+    }
+    if (!activeTurn) {
+      activeTurn = `segment:${stableItemKey(item, index)}`;
+      start = index;
+    }
+    keys.push(activeTurn);
+    if (item?.kind === 'turndone') {
+      if (typeof item.attemptId === 'string' && item.attemptId) {
+        for (let row = start; row <= index; row += 1) keys[row] = `attempt:${item.attemptId}`;
+      } else if (typeof item.checkpointId === 'string' && item.checkpointId) {
+        for (let row = start; row <= index; row += 1) keys[row] = `checkpoint:${item.checkpointId}`;
+      }
+      activeTurn = null;
+    }
+  }
+  return keys;
+}

package/src/runtime/shared/transcript-writer/transcript-file.mjs

@@ -29,7 +29,15 @@ export function conversationText(content) {
     .join('\n');
 }
 
-export function createTranscriptFile({ projectDir, transcriptPath, sessionId, resolvedCwd, logOnce, rotation }) {
+export function createTranscriptFile({
+  projectDir,
+  transcriptPath,
+  sessionId,
+  resolvedCwd,
+  logOnce,
+  rotation,
+  memoryEligible = true,
+}) {
   let projectDirReady = false;
   function ensureProjectDir() {
     if (projectDirReady) return;
@@ -81,6 +89,7 @@ export function createTranscriptFile({ projectDir, transcriptPath, sessionId, re
         const text = conversationText(message?.content);
         if (!text.trim()) continue;
         const entry = { type: role, sessionId, cwd: resolvedCwd };
+        if (!memoryEligible) entry.memoryEligible = false;
         if (message?.timestamp != null) entry.timestamp = message.timestamp;
         else if (message?.ts != null) entry.ts = message.ts;
         entry.message = { content: [{ type: 'text', text }] };

package/src/runtime/shared/transcript-writer.mjs

@@ -30,7 +30,7 @@ const textOrEmpty = (text) => {
   return text == null ? '' : String(text);
 };
 
-export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {}) {
+export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid, memoryEligible = true } = {}) {
   if (!mixdogHome) throw new Error('transcript-writer: mixdogHome is required');
   if (!sessionId) throw new Error('transcript-writer: sessionId is required');
   if (!cwd) throw new Error('transcript-writer: cwd is required');
@@ -42,7 +42,15 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
 
   const logOnce = createFailureLog();
   const rotation = createRotationTracker({ transcriptPath, logOnce });
-  const file = createTranscriptFile({ projectDir, transcriptPath, sessionId, resolvedCwd, logOnce, rotation });
+  const file = createTranscriptFile({
+    projectDir,
+    transcriptPath,
+    sessionId,
+    resolvedCwd,
+    logOnce,
+    rotation,
+    memoryEligible,
+  });
   const record = createSessionRecord({ sessionRecordPath, sessionId, resolvedCwd, transcriptPath, logOnce });
 
   noteSessionTranscript(sessionId, transcriptPath);
@@ -59,6 +67,7 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
         entry?.timestamp != null || entry?.ts != null
           ? { ...entry, cwd: resolvedCwd }
           : { ...entry, cwd: resolvedCwd, timestamp: formatUtcTimestamp() };
+      if (!memoryEligible) stampedEntry.memoryEligible = false;
       const line = `${JSON.stringify(stampedEntry)}\n`;
       appendBuffered(transcriptPath, line);
       rotation.noteAppended(Buffer.byteLength(line));
@@ -95,7 +104,8 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
   return {
     transcriptPath,
     sessionRecordPath,
-    writeSessionRecord: record.write,
+    // Agent runtimes can share a PID with their parent; never replace its discovery record.
+    writeSessionRecord: memoryEligible ? record.write : () => {},
     ensureConversationBackfill: (messages) =>
       isSessionTranscriptPurged(sessionId) ? false : file.ensureConversationBackfill(messages),
     ensureTranscriptFile: () => {
@@ -103,7 +113,7 @@ export function createTranscriptWriter({ mixdogHome, sessionId, cwd, pid } = {})
     },
     // Refresh only the session record's updatedAt so discovery keeps ranking
     // this session as live across long-lived remote sessions.
-    refresh: record.write,
+    refresh: memoryEligible ? record.write : () => {},
     appendAssistant: (text) => appendText('assistant', text),
     // User prompt row. It exists so the memory transcript watcher ingests BOTH
     // sides of the conversation (user rows were previously never written,

package/src/runtime/shared/turn-changes.mjs

@@ -960,8 +960,9 @@ export async function sessionChangeReview(base, { baselines = null, records = []
     (Boolean(entry.root) &&
       insideDirectory(entry.root, entry.path) &&
       changePathKey(relative(entry.root, entry.path)) === targetKey);
+  const baselineTarget = targetKey ? targeted : null;
   const baselineUnits = baselines
-    ? await baselineChanges(baselines, covered, unvouched, diffBudget, { target: targetKey ? targeted : null })
+    ? await baselineChanges(baselines, covered, unvouched, diffBudget, { target: baselineTarget })
     : [];
   // Units named but not measured still claim their names (see `show`).
   const measured = baselineUnits.filter((unit) => !unit.nameOnly);

package/src/runtime/shared/turn-snapshot.mjs

@@ -649,7 +649,8 @@ function foldTrackedChanges(tracker, list, snapshot) {
     const after = contentBuffer(raw?.after);
     if (!destinationPath && before === null && after === null) continue;
     dropUndoneChains(tracker, new Set([sourceKey, ...(destination ? [pathKey(destinationPath)] : [])]));
-    const seq = (_writeSeq += 1);
+    _writeSeq += 1;
+    const seq = _writeSeq;
     appendSegment(tracker, {
       before: { path: sourcePath, displayPath: sourceDisplay, content: before },
       after: destination
@@ -1279,7 +1280,11 @@ export async function getTurnReviewFilePatch(_worktree, sessionId, file) {
   // Only a file the recorded review lists, by its own path.
   const record = await latestTurnRecord(ownerSessionId);
   const match = record ? findChangeFile(record, path) : null;
-  if (!match || fileState(match) !== 'applied' || changePathKey(match.path) !== changePathKey(relativeRecordPath(record, path))) {
+  if (
+    !match ||
+    fileState(match) !== 'applied' ||
+    changePathKey(match.path) !== changePathKey(relativeRecordPath(record, path))
+  ) {
     return filePatchReply(path, '');
   }
   const patch = changeDisplayPatch(match);
@@ -1547,7 +1552,10 @@ async function latestRecordedCheckpoint(ownerSessionId) {
 }
 
 const recordFilePaths = (root, files) =>
-  files.flatMap((entry) => [entry.path, entry.oldPath]).filter(Boolean).map((path) => resolve(root, path));
+  files
+    .flatMap((entry) => [entry.path, entry.oldPath])
+    .filter(Boolean)
+    .map((path) => resolve(root, path));
 
 /** Undo a sealed turn's applied record files (all, or the one named). */
 async function revertRecordedTurn(ownerSessionId, record, file) {

package/src/runtime/shared/worktrees/activity-gate.mjs

@@ -0,0 +1,175 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { withFileLockSync, writeJsonAtomicSync } from '../atomic-file.mjs';
+import { isPidAliveOrUnknown } from '../pid-liveness.mjs';
+import { findGitLayout } from './git-head.mjs';
+import { canonicalPath, isWithin, samePath } from './paths.mjs';
+import { worktreeError, worktreeRefusal } from './contract.mjs';
+import { registryPath } from './registry.mjs';
+
+const FILE = 'mixdog-workspace-admission.json';
+const overlaps = (a, b) => isWithin(a, b) || isWithin(b, a);
+
+/**
+ * The admission policy's external exception: a linked checkout Mixdog did not
+ * create (not a project's main folder, not a registered managed worktree) is
+ * never lock-blocked. Management takes no lease on it and its readers are
+ * admitted whatever is held elsewhere; its running readers still refuse a
+ * management action that touches it.
+ */
+export function isExternalCheckout(folder) {
+  const layout = findGitLayout(folder, { strict: true });
+  if (!layout || samePath(layout.gitDir, layout.commonDir)) return false;
+  let entries;
+  try {
+    entries = JSON.parse(readFileSync(registryPath(), 'utf8'))?.entries ?? {};
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw worktreeRefusal('workspace-admission-unreadable');
+    entries = {};
+  }
+  return !Object.values(entries).some(
+    (record) => typeof record?.path === 'string' && samePath(record.path, layout.topLevel)
+  );
+}
+
+function mutate(commonDir, update) {
+  const path = join(commonDir, FILE);
+  return withFileLockSync(
+    `${path}.lock`,
+    () => {
+      let state;
+      try {
+        state = JSON.parse(readFileSync(path, 'utf8'));
+      } catch (error) {
+        if (error?.code === 'ENOENT') state = { version: 1, leases: [] };
+        else throw worktreeRefusal('workspace-admission-unreadable');
+      }
+      if (
+        state?.version !== 1 ||
+        !Array.isArray(state.leases) ||
+        state.leases.some(
+          (lease) =>
+            !lease ||
+            !['turn', 'command', 'management'].includes(lease.kind) ||
+            typeof lease.token !== 'string' ||
+            !Number.isSafeInteger(lease.pid) ||
+            lease.pid <= 0 ||
+            typeof lease.path !== 'string' ||
+            !isAbsolute(lease.path)
+        )
+      ) {
+        throw worktreeRefusal('workspace-admission-unreadable');
+      }
+      // Only a pid PROVEN dead (ESRCH) drops its lease, whatever its kind; an
+      // unprobeable pid still counts as running. A live runtime keeps a command
+      // whose tree it cannot verify reserved under its own (live) pid until the
+      // tree is confirmed gone, so a lease that outlives every pid belongs to a
+      // restarted runtime that can no longer release it.
+      state.leases = state.leases.filter((lease) => isPidAliveOrUnknown(lease.pid));
+      const result = update(state.leases);
+      writeJsonAtomicSync(path, state, { lock: false });
+      return result;
+    },
+    { strictOwner: true }
+  );
+}
+
+function release(commonDir, token) {
+  let done = false;
+  return () => {
+    if (done) return;
+    mutate(commonDir, (leases) => {
+      for (let i = leases.length - 1; i >= 0; i--) if (leases[i].token === token) leases.splice(i, 1);
+    });
+    done = true;
+  };
+}
+
+/**
+ * Readers share a checkout freely. Null means a management writer currently
+ * owns it; a reader in an external checkout is never held back.
+ */
+export function tryAdmitWorkspaceActivity(sessionId, cwd, { pid = process.pid, kind = 'turn' } = {}) {
+  if (!['turn', 'command'].includes(kind)) throw new TypeError('Invalid workspace reader kind.');
+  const layout = findGitLayout(cwd, { strict: true });
+  if (!layout) return () => {};
+  const external = isExternalCheckout(cwd);
+  const path = canonicalPath(cwd);
+  const token = randomUUID();
+  const admitted = mutate(layout.commonDir, (leases) => {
+    if (!external && leases.some((lease) => lease.kind === 'management' && overlaps(lease.path, path))) return false;
+    leases.push({ kind, sessionId, pid, token, path });
+    return true;
+  });
+  return admitted ? release(layout.commonDir, token) : null;
+}
+
+export async function admitWorkspaceActivity(sessionId, cwd, signal, options) {
+  for (;;) {
+    signal?.throwIfAborted();
+    const leave = tryAdmitWorkspaceActivity(sessionId, cwd, options);
+    if (leave) {
+      if (signal?.aborted) {
+        leave();
+        signal.throwIfAborted();
+      }
+      return leave;
+    }
+    await delay(100, undefined, { signal });
+  }
+}
+
+/**
+ * Writers refuse while any process's reader overlaps an affected folder, then
+ * exclude later readers until the returned release is called. External
+ * checkouts are only checked, never held. `sessionId`: the acting session,
+ * whose own readers in this process do not count (its idleness is the
+ * caller's check).
+ */
+export function holdWorkspaceActivity(folders, { sessionId = null } = {}) {
+  const groups = new Map();
+  for (const folder of folders) {
+    const layout = findGitLayout(folder, { strict: true });
+    if (!layout) throw worktreeError('WORKTREE_UNSUPPORTED_REPO');
+    const paths = groups.get(layout.commonDir) ?? [];
+    paths.push({ path: canonicalPath(folder), external: isExternalCheckout(folder) });
+    groups.set(layout.commonDir, paths);
+  }
+  const releases = [];
+  try {
+    for (const [commonDir, paths] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+      const token = randomUUID();
+      mutate(commonDir, (leases) => {
+        const conflicts = leases.filter(
+          (lease) =>
+            !(sessionId && lease.sessionId === sessionId && lease.pid === process.pid) &&
+            paths.some(({ path }) => overlaps(path, lease.path))
+        );
+        if (conflicts.length) throw worktreeRefusal('folder-in-use');
+        for (const { path, external } of paths) {
+          if (!external) leases.push({ kind: 'management', pid: process.pid, token, path });
+        }
+      });
+      releases.push(release(commonDir, token));
+    }
+  } catch (error) {
+    releaseAll(releases);
+    throw error;
+  }
+  return () => releaseAll(releases);
+}
+
+/** Runs every release in reverse order even when one throws; the first failure is rethrown after all ran. */
+export function releaseAll(releases) {
+  let failure = null;
+  for (const done of [...releases].reverse()) {
+    try {
+      done();
+    } catch (error) {
+      failure ??= error;
+    }
+  }
+  if (failure) throw failure;
+}

package/src/runtime/shared/worktrees/branch-management.mjs

@@ -0,0 +1,179 @@
+import { existsSync } from 'node:fs';
+import { branchCommit, inspectRepo, listWorktrees, runGit, validBranchName } from './git.mjs';
+import { worktreeError, worktreeRefusal } from './contract.mjs';
+import { samePath } from './paths.mjs';
+import { getRecord, putRecord, readRegistry } from './registry.mjs';
+import { readOwnerLease } from './owner.mjs';
+import { isPidAliveOrUnknown } from '../pid-liveness.mjs';
+import { operationInProgress, uncommittedPaths } from './merge.mjs';
+import { gitStatusRunner } from './git.mjs';
+import {
+  withRepoLock,
+  getWorktreeByPath,
+  mergeBranchIntoProject,
+  assertWorktreeRemovable,
+  removeManagedWorktree,
+  managedWorktreeDirtyPaths,
+} from './manager.mjs';
+
+/**
+ * WORKTREE_UNSUPPORTED_REPO when the project folder has no checked-out branch
+ * to merge into; WORKTREE_TARGET_MISMATCH when the confirmed `target` (null:
+ * none confirmed) is no longer the checked-out branch.
+ */
+function assertMergeTarget(currentBranch, target) {
+  if (!currentBranch) {
+    throw worktreeError('WORKTREE_UNSUPPORTED_REPO', 'The project folder has no checked-out branch to merge into.');
+  }
+  if (target !== null && target !== currentBranch) {
+    throw worktreeError(
+      'WORKTREE_TARGET_MISMATCH',
+      `The project folder is now on "${currentBranch}"; confirm the merge again.`,
+      { target, current: currentBranch }
+    );
+  }
+}
+
+async function inspect(projectPath, branch) {
+  const repo = await inspectRepo(projectPath);
+  if (!(await validBranchName(repo.projectPath, branch))) throw new TypeError('Invalid local branch name.');
+  const commit = await branchCommit(repo.projectPath, branch);
+  if (!commit) throw worktreeError('WORKTREE_MISSING', 'The local branch no longer exists.');
+  const holder = (await listWorktrees(repo.projectPath)).find((row) => row.branch === branch && !row.prunable);
+  const entry = holder ? await getWorktreeByPath(holder.path) : null;
+  return {
+    repo,
+    branch,
+    commit,
+    target: repo.currentBranch,
+    targetCommit: repo.currentBranch ? await branchCommit(repo.projectPath, repo.currentBranch) : null,
+    path: holder?.path ?? null,
+    worktreeId: entry?.id ?? null,
+    kind: holder ? (samePath(holder.path, repo.topLevel) ? 'project' : entry ? 'managed' : 'external') : 'free',
+  };
+}
+
+export async function inspectProjectBranch({ projectPath, branch }) {
+  const repo = await inspectRepo(projectPath);
+  return withRepoLock(repo.repoCommonDir, async () => {
+    const { repo: _repo, ...state } = await inspect(projectPath, branch);
+    return state;
+  });
+}
+
+/**
+ * A merge confirmed by its target branch only (the dock, a session merging
+ * its own checkout): the identities inspected now are the confirmed ones, and
+ * the merge then takes the one guarded path (manageProjectBranch). `target`
+ * null accepts the folder's checked-out branch.
+ */
+export async function mergeConfirmedTarget({ projectPath, branch, target = null }, withFolders) {
+  const state = await inspectProjectBranch({ projectPath, branch });
+  assertMergeTarget(state.target, target);
+  return manageProjectBranch(
+    {
+      projectPath,
+      branch,
+      action: 'merge',
+      commit: state.commit,
+      target: state.target,
+      targetCommit: state.targetCommit,
+      confirmed: true,
+    },
+    withFolders
+  );
+}
+
+/**
+ * The one guarded path of every merge, folder cleanup and branch deletion.
+ * The caller supplies process/session admission (`withFolders(folders,
+ * removing, run)`: a merge holds both the project folder and the source
+ * checkout) while this module owns Git/ref validation: a merge refuses a dirty
+ * source or one with a Git operation in progress, and the destination's own
+ * preflight refuses a dirty target.
+ */
+export async function manageProjectBranch(input, withFolders) {
+  const { projectPath, branch, action, commit, target, targetCommit } = input;
+  if (input.confirmed !== true) throw worktreeError('WORKTREE_CONFIRM_REQUIRED');
+  if (!['merge', 'remove-worktree', 'delete-branch'].includes(action)) throw new TypeError('Unknown branch action.');
+  const initial = await inspect(projectPath, branch);
+  const folders =
+    action === 'merge'
+      ? [initial.repo.topLevel, initial.path].filter(Boolean)
+      : action === 'remove-worktree' && initial.path
+        ? [initial.path]
+        : [];
+  return withFolders([...new Set(folders)], action === 'remove-worktree', async (retainedSessionIds) =>
+    withRepoLock(initial.repo.repoCommonDir, async () => {
+      const state = await inspect(projectPath, branch);
+      if (
+        state.commit !== commit ||
+        state.path !== initial.path ||
+        (action !== 'remove-worktree' && (state.target !== target || state.targetCommit !== targetCommit))
+      ) {
+        throw worktreeError('WORKTREE_REVISION_CONFLICT', 'The branch changed; reopen the menu and confirm again.');
+      }
+      const record = state.worktreeId ? await getRecord(state.worktreeId) : null;
+      if (record) {
+        const leases = [
+          await readOwnerLease(record, { strict: true }),
+          ...Object.values(record.sharedLeases ?? {}),
+        ].filter(Boolean);
+        if (
+          leases.some(
+            (lease) => isPidAliveOrUnknown(lease.pid) && (action === 'remove-worktree' || lease.pid !== process.pid)
+          )
+        ) {
+          throw worktreeRefusal('workspace-lease');
+        }
+      }
+      if (action === 'remove-worktree') {
+        if (
+          state.kind !== 'managed' ||
+          !record ||
+          !(record.state === 'ready' || (record.state === 'deleting' && record.deleting?.safeOnly)) ||
+          !existsSync(record.path)
+        ) {
+          throw worktreeError('WORKTREE_PATH_UNSAFE', 'Only an unused Mixdog-managed worktree can be removed.');
+        }
+        const retained = new Set(retainedSessionIds);
+        const users = [record.ownerSessionId, ...(record.sharedSessionIds ?? [])].filter((id) => retained.has(id));
+        if (users.length) throw worktreeRefusal('workspace-retained', { sessions: users });
+        await assertWorktreeRemovable({ entryId: record.id });
+        return removeManagedWorktree({ entryId: record.id, preserveBranch: true, safeOnly: true });
+      }
+      if (!target || branch === target)
+        throw worktreeError('WORKTREE_TARGET_MISMATCH', 'Select a different source branch.');
+      if (action === 'delete-branch') {
+        if (state.path)
+          throw worktreeError('WORKTREE_BRANCH_OCCUPIED', 'Remove or leave the checkout before deleting its branch.');
+        const held = Object.values((await readRegistry()).entries).some(
+          (row) => row.branch === branch && samePath(row.repoCommonDir, state.repo.repoCommonDir)
+        );
+        if (held) throw worktreeError('WORKTREE_BUSY_JOBS', 'A managed worktree still retains this branch.');
+        const merged = await runGit(projectPath, ['merge-base', '--is-ancestor', commit, targetCommit], {
+          allowFailure: true,
+        });
+        if (merged.code !== 0) throw worktreeError('WORKTREE_UNMERGED', `The branch is not merged into ${target}.`);
+        await runGit(projectPath, ['branch', '-d', '--', branch]);
+        return { deleted: true, branch };
+      }
+      if (state.path) {
+        const operation = await operationInProgress(gitStatusRunner, state.path);
+        const dirty = record
+          ? await managedWorktreeDirtyPaths(record.id)
+          : await uncommittedPaths(gitStatusRunner, state.path);
+        if (operation || dirty.length)
+          throw worktreeError('WORKTREE_DIRTY', 'Commit or finish the source work before merging.', {
+            operation,
+            count: dirty.length,
+          });
+      }
+      const merged = await mergeBranchIntoProject({ projectPath, source: branch, target, confirmed: true });
+      // A managed worktree remembers where it was merged (its later removal checks against it).
+      const current = merged.merged && record ? await getRecord(record.id) : null;
+      if (current && current.mergeTarget !== target) await putRecord({ ...current, mergeTarget: target });
+      return merged;
+    })
+  );
+}

package/src/runtime/shared/worktrees/carry.mjs

@@ -48,8 +48,8 @@ import { operationInProgress } from './merge.mjs';
 const IDENTITY_PATH = '.mixdog/project.id';
 const RECOVERY_REF_PREFIX = 'refs/mixdog/carry/';
 /** Untracked files beyond these limits are refused rather than snapshotted. */
-export const CARRY_UNTRACKED_MAX_BYTES = 256 * 1024 * 1024;
-export const CARRY_UNTRACKED_MAX_FILES = 10_000;
+const CARRY_UNTRACKED_MAX_BYTES = 256 * 1024 * 1024;
+const CARRY_UNTRACKED_MAX_FILES = 10_000;
 const CHECK_ATTR_CHUNK = 200;
 // Recovery commits are Mixdog's own, independent of the user's identity config.
 const COMMIT_ENV = Object.freeze({
@@ -66,6 +66,8 @@ function identityPath(projectSubdir) {
 /** CE_INTENT_TO_ADD in an index entry's flags (`git add -N`). */
 const INTENT_TO_ADD_FLAG = 0x20000000;
 
+const PORCELAIN_LEAD_FIELDS = { 1: 8, 2: 9, u: 10 };
+
 /**
  * `git status --porcelain=v2 -z` rows: path, untracked, unmerged, submodule.
  * @returns {Array<{ path: string, untracked: boolean, unmerged: boolean, submodule: boolean }>}
@@ -82,8 +84,8 @@ function parseStatusV2(raw) {
       continue;
     }
     // Leading fields before the path: 1 → 8, 2 → 9 (then the original path), u → 10.
-    const lead = kind === '1' ? 8 : kind === '2' ? 9 : kind === 'u' ? 10 : -1;
-    if (lead < 0) continue;
+    const lead = PORCELAIN_LEAD_FIELDS[kind];
+    if (lead === undefined) continue;
     const parts = field.split(' ');
     rows.push({
       path: parts.slice(lead).join(' '),

package/src/runtime/shared/worktrees/contract.mjs

@@ -59,7 +59,8 @@ const DEFAULT_ERROR_MESSAGES = Object.freeze({
   WORKTREE_DIRTY: 'The worktree has uncommitted changes.',
   WORKTREE_DIRTY_CHOICE:
     'The project folder has uncommitted changes; choose whether to leave them there or carry them into the worktree.',
-  WORKTREE_FILE_RECOVERY: 'Retained file recovery records block worktree removal, including force. Inspect and explicitly delete them first.',
+  WORKTREE_FILE_RECOVERY:
+    'Retained file recovery records block worktree removal, including force. Inspect and explicitly delete them first.',
   WORKTREE_UNMERGED: 'The worktree branch has commits that are not merged.',
   WORKTREE_MISSING: 'The managed worktree no longer exists.',
   WORKTREE_UNSUPPORTED_REPO: 'This repository does not support managed worktrees.',
@@ -105,6 +106,31 @@ export function worktreeError(code, message, details) {
   return new WorktreeError(code, message, details);
 }
 
+/**
+ * Why a workspace management action (merge, folder cleanup, branch deletion,
+ * checkout) was refused because something still uses an affected folder. Every
+ * surface shows the same meaning: the runtime throws exactly this text (TUI,
+ * remote) and the desktop translates the same English source string.
+ * @readonly
+ */
+export const WORKTREE_REFUSAL_REASONS = Object.freeze({
+  'workspace-retained': 'Sessions still retain this folder. Close or remove those sessions before cleaning it up.',
+  'workspace-lease': 'A runtime still holds this folder. Stop its work and release the workspace first.',
+  'folder-in-use': 'Sessions or workers still use an affected folder. Finish or move them before continuing.',
+  'folder-shell-jobs': 'Background commands still use an affected folder. Wait for them or stop them first.',
+  'workspace-admission-unreadable': 'Workspace activity cannot be verified. Nothing was changed.',
+});
+
+/**
+ * WORKTREE_BUSY_JOBS with the shared text of `reason` (WORKTREE_REFUSAL_REASONS).
+ * @param {keyof typeof WORKTREE_REFUSAL_REASONS} reason
+ * @param {Record<string, unknown>} [details]
+ */
+export function worktreeRefusal(reason, details = {}) {
+  if (!Object.hasOwn(WORKTREE_REFUSAL_REASONS, reason)) throw new TypeError(`Unknown refusal reason "${reason}".`);
+  return worktreeError('WORKTREE_BUSY_JOBS', WORKTREE_REFUSAL_REASONS[reason], { ...details, reason });
+}
+
 /**
  * @param {unknown} error
  * @param {WorktreeErrorCode} [code] When given, also require this code.