@fitlab-ai/agent-infra 0.11.14 → 0.12.0

package/lib/sandbox/commands/list-running.ts

@@ -5,6 +5,7 @@ import { runSafeEngine, runVerboseEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { isRemovedHashShortIdInput } from '../../task/short-id.ts';
 import { parseSandboxWorkspaceIdentity } from '../workspace-identity.ts';
+import { resolveProjectTaskWorkspaceRoot } from '../../task/workspace-root.ts';
 
 export type SandboxRow = {
   name: string;
@@ -143,7 +144,7 @@ function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
     );
   }
   for (const sub of ['active', 'completed', 'blocked', 'archive']) {
-    const taskMdPath = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    const taskMdPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), sub, taskId, 'task.md');
     if (!fs.existsSync(taskMdPath)) continue;
     const content = fs.readFileSync(taskMdPath, 'utf8');
     const fm = content.match(/^branch:\s*(.+)$/m);

package/lib/sandbox/control/client.ts

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { resolveProjectTaskWorkspaceRoot } from '../../task/workspace-root.ts';
+import { detectRepoRoot } from '../../task/resolve-ref.ts';
 import {
   SANDBOX_CONTROL_MAX_BYTES,
   SANDBOX_CONTROL_STATUS_STALE_MS,
@@ -158,18 +160,11 @@ type CanonicalRequestTask =
 
 // Use the current short-id contract for the first visible active registry.
 export function resolveVisibleActiveShortId(ref: string): string | null {
-  let dir = process.cwd();
-  for (let depth = 0; depth < 64; depth += 1) {
-    const registryPath = path.join(dir, '.agents', 'workspace', 'active', '.short-ids.json');
-    if (fs.existsSync(registryPath)) {
-      const resolved = resolveShortIdReadOnly(ref, dir, { shortIdLength: configuredShortIdLength(dir) });
-      return resolved.ok ? resolved.taskId : null;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
+  const repoRoot = detectRepoRoot();
+  const registryPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', '.short-ids.json');
+  if (!fs.existsSync(registryPath)) return null;
+  const resolved = resolveShortIdReadOnly(ref, repoRoot, { shortIdLength: configuredShortIdLength(repoRoot) });
+  return resolved.ok ? resolved.taskId : null;
 }
 
 // A request's leading argument is only a task reference for some families and

package/lib/sandbox/control/completed-reentry.ts

@@ -4,6 +4,7 @@ import { resolveTaskWorkspace } from '../task-resolver.ts';
 import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
 import { parseTypedTaskFrontmatter } from '../../task/frontmatter.ts';
 import { readTaskFinalizationReceipt } from '../../task/finalization.ts';
+import { resolveProjectTaskWorkspaceRoot } from '../../task/workspace-root.ts';
 import { inspectSandboxControlContainer } from './container-identity.ts';
 import type { SandboxControlManifest } from './protocol.ts';
 import { atomicWriteJson, readSandboxControlStatus } from './state.ts';
@@ -53,7 +54,7 @@ export async function prepareCompletedReentry(
     || previous.receipt.generation !== view.receipt.generation
     || previous.receipt.requestId !== view.receipt.requestId
     || previous.receipt.revision > view.receipt.revision) throw invalid();
-  const completedRoot = fs.realpathSync.native(path.join(manifest.repoRoot, '.agents', 'workspace', 'completed'));
+  const completedRoot = fs.realpathSync.native(path.join(resolveProjectTaskWorkspaceRoot(manifest.repoRoot), 'completed'));
   const source = fs.realpathSync.native(path.join(completedRoot, manifest.taskId));
   if (source !== path.join(completedRoot, manifest.taskId)) throw invalid();
   const stat = fs.statSync(source, { bigint: true });

package/lib/sandbox/control/lifecycle.ts

@@ -661,28 +661,11 @@ function readTaskCompletionManifest(
   return manifest;
 }
 
-export async function quiesceSandboxControlForTaskCompletion(
+export function validateSandboxControlTaskIdentity(
   root: string,
-  binding: Readonly<{ taskId: string; generation: string; controlRootId: string; statusDir: string }>,
-  timeoutMs = DEFAULT_QUIESCE_TIMEOUT_MS
-): Promise<void> {
-  const resolvedRoot = path.resolve(root);
-  const manifest = readTaskCompletionManifest(resolvedRoot, binding);
-  markSandboxControlRootQuiescing(resolvedRoot);
-  const deadline = Date.now() + timeoutMs;
-  const startupPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
-  const brokerPath = path.join(resolvedRoot, 'broker.json');
-  while (true) {
-    const startup = readStartupOwner(startupPath);
-    if (fs.existsSync(startupPath) && !startup) throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
-    const broker = readBrokerOwner(brokerPath);
-    if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
-      throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
-    }
-    if (!startup && !broker) return;
-    if (Date.now() >= deadline) throw new Error('SANDBOX_CONTROL_BROKER_DRAIN_TIMEOUT');
-    await new Promise((resolve) => setTimeout(resolve, 25));
-  }
+  binding: Readonly<{ taskId: string; generation: string; controlRootId: string; statusDir: string }>
+): void {
+  readTaskCompletionManifest(path.resolve(root), binding);
 }
 
 function recordSandboxRemovalPending(

package/lib/sandbox/control/task-view.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveProjectTaskWorkspaceRoot } from '../../task/workspace-root.ts';
 
 export const SANDBOX_TASK_VIEW_STATES = ['not-applicable', 'current', 'finalized-stale', 'unknown'] as const;
 export const SANDBOX_TASK_VIEW_SOURCES = ['active', 'completed', 'unknown'] as const;
@@ -119,8 +120,9 @@ export function taskViewForManifest(params: Readonly<{
   if (params.mode !== 'task-bound' || !params.taskId) {
     return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
   }
-  const active = path.join(params.repoRoot, '.agents', 'workspace', 'active', params.taskId, 'task.md');
-  const completed = path.join(params.repoRoot, '.agents', 'workspace', 'completed', params.taskId, 'task.md');
+  const taskRoot = resolveProjectTaskWorkspaceRoot(params.repoRoot);
+  const active = path.join(taskRoot, 'active', params.taskId, 'task.md');
+  const completed = path.join(taskRoot, 'completed', params.taskId, 'task.md');
   const activeExists = fs.existsSync(active);
   const completedExists = fs.existsSync(completed);
   if (activeExists === completedExists) {

package/lib/sandbox/mounts.ts

@@ -24,12 +24,12 @@ function workspaceStateMounts(workspaceViewRoot: string, taskBound: boolean): Sa
     .map(({ state, hostPath }) => taskBound && state === 'active'
       ? {
           hostPaths: [path.join(hostPath, '.short-ids.json')],
-          containerPath: '/workspace/.agents/workspace/active/.short-ids.json',
+          containerPath: '/task-workspace/active/.short-ids.json',
           readOnly: true
         }
       : {
           hostPaths: [hostPath],
-          containerPath: path.posix.join('/workspace/.agents/workspace', state),
+          containerPath: path.posix.join('/task-workspace', state),
           readOnly: true
         }
     );
@@ -60,12 +60,12 @@ function taskWorkspaceMounts(taskSources: string[], taskBound: boolean, override
   const taskId = overrides.taskId!;
   const mounts: SandboxBindMountDeclaration[] = [{
     hostPaths: taskSources,
-    containerPath: path.posix.join('/workspace/.agents/workspace/active', taskId),
+    containerPath: path.posix.join('/task-workspace/active', taskId),
     readOnly: false
   }];
   if (overrides.completedTaskSource) mounts.push({
     hostPaths: [overrides.completedTaskSource],
-    containerPath: path.posix.join('/workspace/.agents/workspace/completed', taskId),
+    containerPath: path.posix.join('/task-workspace/completed', taskId),
     readOnly: false
   });
   return mounts;

package/lib/sandbox/recovery.ts

@@ -30,6 +30,7 @@ import {
   sandboxWorkspaceViewPaths
 } from './workspace-view.ts';
 import { resolveTaskWorkspace } from './task-resolver.ts';
+import { resolveProjectTaskWorkspaceRoot } from '../task/workspace-root.ts';
 import {
   parseSandboxWorkspaceIdentity,
   sameSandboxWorkspaceIdentity,
@@ -450,11 +451,13 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
     });
   }
   if (snapshot.workspaceTopology === 'legacy-parent') {
+    const legacyRoot = snapshot.mounts.some((mount) => mount.path === '/task-workspace')
+      ? '/task-workspace' : '/workspace/.agents/workspace';
     findings.push({
       repairKind: 'hard-failure',
       code: 'SANDBOX_WORKSPACE_TOPOLOGY_MISMATCH',
       message: 'Sandbox uses the legacy workspace parent-mount topology; recreate the container explicitly to migrate it.',
-      path: '/workspace/.agents/workspace'
+      path: legacyRoot
     });
   }
   if (snapshot.taskView && !snapshot.taskView.readable) {
@@ -476,7 +479,8 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
   for (const mount of snapshot.mounts) {
     if (
       snapshot.workspaceTopology === 'legacy-parent'
-      && mount.path.startsWith('/workspace/.agents/workspace')
+      && (mount.path.startsWith('/workspace/.agents/workspace')
+        || mount.path.startsWith('/task-workspace'))
     ) continue;
     if (
       mount.actualType !== mount.expectedType
@@ -571,13 +575,14 @@ function inspectContainer(
 }
 
 function workspaceTopology(mountsByDestination: ReadonlyMap<string, DockerMount>): SandboxRecoverySnapshot['workspaceTopology'] {
-  if (mountsByDestination.has('/workspace/.agents/workspace')) return 'legacy-parent';
+  if (mountsByDestination.has('/workspace/.agents/workspace')
+    || mountsByDestination.has('/task-workspace')) return 'legacy-parent';
   const perState = [
-    '/workspace/.agents/workspace/active',
-    '/workspace/.agents/workspace/active/.short-ids.json',
-    '/workspace/.agents/workspace/completed',
-    '/workspace/.agents/workspace/blocked',
-    '/workspace/.agents/workspace/archive'
+    '/task-workspace/active',
+    '/task-workspace/active/.short-ids.json',
+    '/task-workspace/completed',
+    '/task-workspace/blocked',
+    '/task-workspace/archive'
   ];
   return perState.some((destination) => mountsByDestination.has(destination))
     ? 'per-state'
@@ -618,8 +623,9 @@ function recoveryTaskSources(repoRoot: string, taskId: string): {
   mountPaths: string[];
   accessiblePaths: string[];
 } {
-  const activePath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
-  const completedPath = path.join(repoRoot, '.agents', 'workspace', 'completed', taskId);
+  const taskRoot = resolveProjectTaskWorkspaceRoot(repoRoot);
+  const activePath = path.join(taskRoot, 'active', taskId);
+  const completedPath = path.join(taskRoot, 'completed', taskId);
   if (fs.existsSync(activePath) && !fs.existsSync(completedPath)) {
     const source = assertSandboxTaskSource(repoRoot, taskId);
     return { mountPaths: [source], accessiblePaths: [source] };
@@ -635,7 +641,7 @@ function recoveryTaskSources(repoRoot: string, taskId: string): {
   }
 
   const completedRoot = fs.realpathSync.native(
-    path.join(repoRoot, '.agents', 'workspace', 'completed')
+    path.join(taskRoot, 'completed')
   );
   const completedSource = fs.realpathSync.native(path.dirname(task.taskMd));
   if (path.dirname(completedSource) !== completedRoot) {
@@ -643,9 +649,7 @@ function recoveryTaskSources(repoRoot: string, taskId: string): {
   }
 
   const historicalActivePath = path.join(
-    repoRoot,
-    '.agents',
-    'workspace',
+    taskRoot,
     'active',
     taskId
   );
@@ -670,7 +674,7 @@ export function startCompletedSandboxContainer(params: {
 }): void {
   const taskSources = recoveryTaskSources(params.config.repoRoot, params.taskId);
   const completedSource = taskSources.accessiblePaths[0]!;
-  const activeRoot = path.join(params.config.repoRoot, '.agents', 'workspace', 'active');
+  const activeRoot = path.join(resolveProjectTaskWorkspaceRoot(params.config.repoRoot), 'active');
   const historicalSource = path.join(activeRoot, params.taskId);
   fs.mkdirSync(activeRoot, { recursive: true });
   let replacedEmptyRoot = false;
@@ -791,11 +795,11 @@ function expectedMounts(params: {
     expectedType: 'bind' as const,
     hostPaths: mount.hostPaths,
     ...(taskSources !== null && taskId !== null
-      && mount.containerPath === `/workspace/.agents/workspace/active/${taskId}`
+      && mount.containerPath === `/task-workspace/active/${taskId}`
       ? { sourceAccessiblePaths: taskSources!.accessiblePaths }
       : {}),
     ...(completedTaskSource !== null && taskId !== null
-      && mount.containerPath === `/workspace/.agents/workspace/completed/${taskId}`
+      && mount.containerPath === `/task-workspace/completed/${taskId}`
       ? { sourceAccessiblePaths: [completedTaskSource] }
       : {}),
     expectedRW: !mount.readOnly
@@ -929,7 +933,7 @@ export function collectSandboxRecoverySnapshot(params: {
   const tools = [...capabilityPlan.tools];
   const topology = workspaceTopology(mountsByDestination);
   const taskViewPath = workspace.mode === 'task-bound'
-    ? `/workspace/.agents/workspace/active/${workspace.taskId}/task.md`
+    ? `/task-workspace/active/${workspace.taskId}/task.md`
     : null;
   const seeds = declaredTmpfsSeedEntries(tools).map((seed) => {
     const mounted = mountsByDestination.get(seed.stagingPath)?.Type === 'bind';
@@ -1215,6 +1219,10 @@ function canRetryFreshReadiness(findings: SandboxRecoveryFinding[]): boolean {
     && finding.path !== undefined
     && (
       finding.path.startsWith('/workspace/.agents/workspace')
+      || finding.path.startsWith('/task-workspace/active')
+      || finding.path.startsWith('/task-workspace/blocked')
+      || finding.path.startsWith('/task-workspace/completed')
+      || finding.path.startsWith('/task-workspace/archive')
       || finding.path === '/home/devuser/.host-shell-config'
       || finding.path === '/home/devuser/.bash_aliases'
       || finding.path === '/run/agent-infra/runtime'

package/lib/sandbox/removal.ts

@@ -48,7 +48,6 @@ import { toolConfigDirCandidates, toolProjectDirCandidates } from './tools.ts';
 import type { SandboxTool } from './tools.ts';
 import { getProcessStartTime } from '../server/process-state.ts';
 import { releaseStaleShortIdRegistry } from '../task/short-id.ts';
-import { withRepositoryMutationLock } from '../task/task-execution-lock.ts';
 import { fetchSandboxRows, type SandboxRow } from './commands/list-running.ts';
 import { createSandboxControlBindingEvidence } from './task-cleanup.ts';
 import {
@@ -933,7 +932,7 @@ async function authorizeWorktrees(
   return permits;
 }
 
-async function runRmOneUnderRepositoryLock(
+async function runRmOne(
   config: SandboxConfig,
   tools: SandboxTool[],
   branch: string,
@@ -953,10 +952,7 @@ async function rmOne(
   branch: string,
   options: RmOneOptions = {}
 ): Promise<void> {
-  await withRepositoryMutationLock(
-    config.repoRoot,
-    () => runRmOneUnderRepositoryLock(config, tools, branch, options)
-  );
+  await runRmOne(config, tools, branch, options);
 }
 
 async function removeUncheckedSandbox(
@@ -1060,14 +1056,6 @@ async function rmPurge(
   config: SandboxConfig,
   tools: SandboxTool[],
   prompt: PromptDependencies = {}
-): Promise<void> {
-  return withRepositoryMutationLock(config.repoRoot, () => rmPurgeCore(config, tools, prompt));
-}
-
-async function rmPurgeCore(
-  config: SandboxConfig,
-  tools: SandboxTool[],
-  prompt: PromptDependencies = {}
 ): Promise<void> {
   const engine = detectEngine(config);
   const confirm = prompt.confirm ?? p.confirm;
@@ -1142,17 +1130,6 @@ async function rmUnbound(
   config: SandboxConfig,
   tools: SandboxTool[],
   options: { dryRun: boolean; assumeYes: boolean }
-): Promise<void> {
-  return withRepositoryMutationLock(
-    config.repoRoot,
-    () => rmUnboundCore(config, tools, options)
-  );
-}
-
-async function rmUnboundCore(
-  config: SandboxConfig,
-  tools: SandboxTool[],
-  options: { dryRun: boolean; assumeYes: boolean }
 ): Promise<void> {
   const engine = detectEngine(config);
   const listed = fetchSandboxRows(
@@ -1215,7 +1192,7 @@ async function rmUnboundCore(
     return;
   }
   for (const { row, cleanupTarget, target } of targets) {
-    await runRmOneUnderRepositoryLock(config, tools, cleanupTarget.branch, {
+    await runRmOne(config, tools, cleanupTarget.branch, {
       assumeYes: options.assumeYes,
       target,
       cleanupTarget

package/lib/sandbox/task-resolver.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { isRemovedHashShortIdInput } from '../task/short-id.ts';
+import { resolveProjectTaskWorkspaceRoot } from '../task/workspace-root.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
@@ -35,10 +36,11 @@ function stripQuotes(value: string): string {
 }
 
 function readTaskContent(repoRoot: string, taskId: string): { content: string; state: TaskWorkspaceState; taskMd: string } {
+  const taskRoot = resolveProjectTaskWorkspaceRoot(repoRoot);
   for (const state of TASK_WORKSPACE_STATES) {
     const taskPath = state === 'archive'
-      ? path.join(repoRoot, '.agents', 'workspace', state, ...findArchiveTaskParts(repoRoot, taskId), 'local', 'task.md')
-      : path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+      ? path.join(taskRoot, state, ...findArchiveTaskParts(repoRoot, taskId), 'local', 'task.md')
+      : path.join(taskRoot, state, taskId, 'task.md');
     if (fs.existsSync(taskPath)) {
       return { content: fs.readFileSync(taskPath, 'utf8'), state, taskMd: taskPath };
     }
@@ -47,8 +49,9 @@ function readTaskContent(repoRoot: string, taskId: string): { content: string; s
 }
 
 function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspace[] {
+  const taskRoot = resolveProjectTaskWorkspaceRoot(repoRoot);
   const hot = TASK_WORKSPACE_STATES.filter((state) => state !== 'archive').flatMap((state) => {
-    const taskMd = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+    const taskMd = path.join(taskRoot, state, taskId, 'task.md');
     if (!fs.existsSync(taskMd)) return [];
     const content = fs.readFileSync(taskMd, 'utf8');
     return [{
@@ -60,7 +63,7 @@ function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspac
   });
   const parts = findArchiveTaskParts(repoRoot, taskId);
   if (parts.length === 0) return hot;
-  const taskMd = path.join(repoRoot, '.agents', 'workspace', 'archive', ...parts, 'local', 'task.md');
+  const taskMd = path.join(taskRoot, 'archive', ...parts, 'local', 'task.md');
   if (!fs.existsSync(taskMd)) return hot;
   const content = fs.readFileSync(taskMd, 'utf8');
   return [...hot, {
@@ -72,7 +75,7 @@ function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspac
 }
 
 function findArchiveTaskParts(repoRoot: string, taskId: string): string[] {
-  const archiveRoot = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  const archiveRoot = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'archive');
   if (!fs.existsSync(archiveRoot)) return [];
   for (const year of fs.readdirSync(archiveRoot).sort().reverse()) {
     if (!/^\d{4}$/.test(year)) continue;
@@ -129,7 +132,7 @@ export function resolveTaskWorkspace(taskId: string, repoRoot: string): TaskWork
 }
 
 export function listTaskWorkspaces(repoRoot: string, state: TaskWorkspaceState): TaskWorkspace[] {
-  const stateRoot = path.join(repoRoot, '.agents', 'workspace', state);
+  const stateRoot = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), state);
   if (state === 'archive') {
     if (!fs.existsSync(stateRoot)) return [];
     const rows: TaskWorkspace[] = [];

package/lib/sandbox/workspace-identity.ts

@@ -1,8 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { isRemovedHashShortIdInput } from '../task/short-id.ts';
-import { resolveTaskRef } from '../task/resolve-ref.ts';
 import {
+  configuredShortIdLength,
+  inspectShortIdRegistry,
+  isRemovedHashShortIdInput,
+  normalizeShortIdInput
+} from '../task/short-id.ts';
+import { resolveProjectTaskWorkspaceRoot } from '../task/workspace-root.ts';
+import {
+  TASK_WORKSPACE_STATES,
+  listTaskWorkspaces,
   resolveTaskWorkspace,
   type TaskWorkspaceState
 } from './task-resolver.ts';
@@ -51,7 +58,7 @@ function taskBranch(taskMd: string, taskId: string): string {
 }
 
 function activeRegistry(repoRoot: string): Record<string, string> {
-  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', '.short-ids.json');
+  const registryPath = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', '.short-ids.json');
   if (!fs.existsSync(registryPath)) return {};
   const value = JSON.parse(fs.readFileSync(registryPath, 'utf8')) as unknown;
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -68,7 +75,7 @@ function activeRegistry(repoRoot: string): Record<string, string> {
 }
 
 function taskIdentity(repoRoot: string, taskId: string, registry: Record<string, string>): SandboxWorkspaceIdentity {
-  const taskMd = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+  const taskMd = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', taskId, 'task.md');
   if (!fs.existsSync(taskMd)) throw new Error(`Active task not found: ${taskId}`);
   const shortIds = Object.entries(registry).filter(([, id]) => id === taskId).map(([shortId]) => shortId);
   if (shortIds.length !== 1) {
@@ -79,10 +86,29 @@ function taskIdentity(repoRoot: string, taskId: string, registry: Record<string,
 
 function cleanupTaskId(requestedRef: string, repoRoot: string): string | null {
   if (TASK_ID_RE.test(requestedRef)) return requestedRef;
-  if (!SHORT_ID_RE.test(requestedRef)) return null;
-  const task = resolveTaskRef(requestedRef, { repoRoot });
-  if (!task.ok) throw new Error(task.message);
-  return task.taskId;
+  const shortIdLength = configuredShortIdLength(repoRoot);
+  const normalized = normalizeShortIdInput(requestedRef, { shortIdLength });
+  if (normalized.kind === 'error') throw new Error(normalized.message);
+  if (normalized.kind !== 'shortId') return null;
+
+  const registry = inspectShortIdRegistry(repoRoot, shortIdLength);
+  if (registry.status !== 'valid') throw new Error(registry.error.message);
+  const match = [...registry.shortIds].find(([, shortId]) => shortId === normalized.value);
+  if (!match) {
+    throw new Error(`Short id '${normalized.value}' not found in active task registry`);
+  }
+  return match[0];
+}
+
+function cleanupTaskIdByBranch(requestedRef: string, repoRoot: string): string | null {
+  const taskIds = new Set(TASK_WORKSPACE_STATES
+    .flatMap((state) => listTaskWorkspaces(repoRoot, state))
+    .filter((task) => task.branch === requestedRef)
+    .map((task) => task.taskId));
+  if (taskIds.size > 1) {
+    throw new Error(`SANDBOX_TASK_IDENTITY_AMBIGUOUS: branch '${requestedRef}' is bound to multiple tasks`);
+  }
+  return taskIds.values().next().value ?? null;
 }
 
 export function resolveSandboxTarget(requestedRef: string, repoRoot: string): SandboxTarget {
@@ -101,14 +127,14 @@ export function resolveSandboxTarget(requestedRef: string, repoRoot: string): Sa
     const taskId = canonicalShortId ? registry[canonicalShortId] : undefined;
     if (!taskId) throw new Error(`Short id '${requestedRef}' not found in active task registry`);
     const workspace = taskIdentity(repoRoot, taskId, registry);
-    return { requestedRef, branch: taskBranch(path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md'), taskId), workspace };
+    return { requestedRef, branch: taskBranch(path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', taskId, 'task.md'), taskId), workspace };
   }
   if (TASK_ID_RE.test(requestedRef)) {
     const workspace = taskIdentity(repoRoot, requestedRef, registry);
-    return { requestedRef, branch: taskBranch(path.join(repoRoot, '.agents', 'workspace', 'active', requestedRef, 'task.md'), requestedRef), workspace };
+    return { requestedRef, branch: taskBranch(path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active', requestedRef, 'task.md'), requestedRef), workspace };
   }
 
-  const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
+  const activeRoot = path.join(resolveProjectTaskWorkspaceRoot(repoRoot), 'active');
   const matches = fs.existsSync(activeRoot)
     ? fs.readdirSync(activeRoot, { withFileTypes: true }).flatMap((entry) => {
       if (!entry.isDirectory() || !TASK_ID_RE.test(entry.name)) return [];
@@ -139,7 +165,8 @@ export function resolveSandboxCleanupTarget(
     throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
   }
 
-  const taskId = cleanupTaskId(requestedRef, repoRoot);
+  const taskId = cleanupTaskId(requestedRef, repoRoot)
+    ?? cleanupTaskIdByBranch(requestedRef, repoRoot);
   if (taskId) {
     let task: ReturnType<typeof resolveTaskWorkspace>;
     try {
@@ -166,14 +193,11 @@ export function resolveSandboxCleanupTarget(
     };
   }
 
-  const target = resolveSandboxTarget(requestedRef, repoRoot);
   return {
     requestedRef,
-    branch: target.branch,
-    workspace: target.workspace.mode === 'task-bound'
-      ? { mode: 'task-bound', taskId: target.workspace.taskId }
-      : { mode: 'branch-only' },
-    taskState: target.workspace.mode === 'task-bound' ? 'active' : 'branch-only'
+    branch: requestedRef,
+    workspace: { mode: 'branch-only' },
+    taskState: 'branch-only'
   };
 }
 

package/lib/sandbox/workspace-view.ts

@@ -1,6 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { resolveProjectTaskWorkspaceRoot } from '../task/workspace-root.ts';
 import type { SandboxWorkspaceIdentity, SandboxWorkspaceKey } from './workspace-identity.ts';
 import { resolveTaskWorkspace } from './task-resolver.ts';
 import type { SandboxControlManifest } from './control/protocol.ts';
@@ -147,7 +149,8 @@ function assertSafeMountTargetPath(
 
 export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  const activeSource = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+  const workspaceRootPath = resolveProjectTaskWorkspaceRoot(repoRoot);
+  const activeSource = path.join(workspaceRootPath, 'active', taskId);
   try {
     const stat = fs.lstatSync(activeSource);
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
@@ -155,7 +158,7 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
     }
     const canonical = fs.realpathSync.native(activeSource);
     const activeRoot = fs.realpathSync.native(path.dirname(activeSource));
-    const workspaceRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace'));
+    const workspaceRoot = fs.realpathSync.native(workspaceRootPath);
     const relative = path.relative(workspaceRoot, canonical);
     if (path.dirname(canonical) !== activeRoot || relative.startsWith('..') || path.isAbsolute(relative)) {
       throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${activeSource} escapes the task workspace`);
@@ -173,7 +176,7 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
     throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} must be a real directory`);
   }
   const canonical = fs.realpathSync.native(source);
-  const workspaceRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace'));
+  const workspaceRoot = fs.realpathSync.native(workspaceRootPath);
   const relative = path.relative(workspaceRoot, canonical);
   if (path.basename(canonical) !== taskId || relative.startsWith('..') || path.isAbsolute(relative)) {
     throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} escapes the task workspace`);
@@ -181,30 +184,38 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
   return canonical;
 }
 
-export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string, taskId?: string): void {
-  const resolvedWorktreeRoot = path.resolve(worktreeRoot);
-  const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
-  const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
+export function prepareSandboxWorkspaceMountTargets(repoRoot: string): void {
+  const resolvedHome = path.resolve(process.env.HOME || os.homedir());
+  const canonicalHome = fs.realpathSync.native(resolvedHome);
+  const workspaceRoot = path.resolve(resolveProjectTaskWorkspaceRoot(repoRoot));
+  const relativeRoot = path.relative(resolvedHome, workspaceRoot);
+  if (relativeRoot.startsWith('..') || path.isAbsolute(relativeRoot)) {
+    throw new Error(`Sandbox workspace mount target escapes the host home: ${workspaceRoot}`);
+  }
   const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
   const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
-  const completedTaskTarget = taskId ? path.join(workspaceRoot, 'completed', taskId) : null;
-  if (taskId && !/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget, ...(completedTaskTarget ? [completedTaskTarget] : [])]) {
-    assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
+  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
+    assertSafeMountTargetPath(target, resolvedHome, canonicalHome);
   }
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
   for (const { hostPath } of statePaths) {
     fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
     fs.chmodSync(hostPath, 0o700);
   }
-  if (completedTaskTarget) fs.mkdirSync(completedTaskTarget, { recursive: true, mode: 0o700 });
   fs.chmodSync(workspaceRoot, 0o700);
-  fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
+  const registryFd = fs.openSync(registryTarget, 'a', 0o600);
+  try {
+    if (fs.fstatSync(registryFd).size === 0) {
+      fs.writeFileSync(registryFd, `${JSON.stringify({ version: 1, ids: {} })}\n`);
+    }
+  } finally {
+    fs.closeSync(registryFd);
+  }
 }
 
 export function prepareSandboxCompletedTaskMountSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  const workspaceRoot = path.resolve(repoRoot, '.agents', 'workspace');
+  const workspaceRoot = resolveProjectTaskWorkspaceRoot(repoRoot);
   fs.mkdirSync(path.join(workspaceRoot, 'completed'), { recursive: true, mode: 0o700 });
   const completedRoot = path.join(workspaceRoot, 'completed');
   const completedStat = fs.lstatSync(completedRoot);
@@ -224,16 +235,13 @@ export function prepareSandboxCompletedTaskMountSource(repoRoot: string, taskId:
 
 export function sandboxCompletedTaskMountSource(repoRoot: string, taskId: string): string {
   if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  const source = path.resolve(repoRoot, '.agents', 'workspace', 'completed', taskId);
+  const source = path.resolve(resolveProjectTaskWorkspaceRoot(repoRoot), 'completed', taskId);
   const stat = fs.lstatSync(source);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  const canonicalWorkspace = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace'));
+  const canonicalWorkspace = fs.realpathSync.native(resolveProjectTaskWorkspaceRoot(repoRoot));
   const canonicalSource = fs.realpathSync.native(source);
-  const canonicalRepoRoot = fs.realpathSync.native(repoRoot);
-  const workspaceRelative = path.relative(canonicalRepoRoot, canonicalWorkspace);
   const relative = path.relative(canonicalWorkspace, canonicalSource);
-  if (workspaceRelative.startsWith('..') || path.isAbsolute(workspaceRelative)
-    || path.dirname(canonicalSource) !== fs.realpathSync.native(path.dirname(source))
+  if (path.dirname(canonicalSource) !== fs.realpathSync.native(path.dirname(source))
     || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
   return canonicalSource;
 }