@fitlab-ai/agent-infra 0.11.6 → 0.11.8

package/dist/lib/platform/pull-requests.js

@@ -1,6 +1,7 @@
 import { normalizePullRequest } from './github-data.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
@@ -19,6 +20,7 @@ import { buildBoundFact, buildSkippedFact, factFrontmatterMutation, readPrDelive
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, providerResourceIdentity, resourceIdentity, unsupportedProviderOperation } from './provider-bridge.js';
 import { isResourceIdentity, resourceIdentityEquals, resourceIdentityNumber, serializeResourceIdentity } from './resource-identity.js';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.js';
+import { coordinatePlatformWrite } from './operation-coordinator.js';
 function warningResultForPrimary(primaryResult) {
     if (primaryResult === 'pr_created')
         return 'pr_created_with_warnings';
@@ -52,6 +54,25 @@ function externalResult(base, overrides = {}) {
 function withCreation(output, creation) {
     return { ...output, creation };
 }
+async function journalPullRequestOperation(taskRef, options, intent, target, identityInput, execute) {
+    if (options.dryRun)
+        return execute();
+    const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+    if (!resolved.ok)
+        return execute();
+    const expectedDigest = createHash('sha256').update(JSON.stringify({ taskId: resolved.taskId, intent, identityInput })).digest('hex');
+    const operation = { kind: 'pull-request', target: intent.action === 'sync' ? `bound-pr:${resolved.taskId}` : target, expectedDigest };
+    const dependency = intent.action === 'sync' ? 'deferred' : 'required';
+    if (options.skipQueue)
+        return execute();
+    return coordinatePlatformWrite({
+        operation: { taskRef: resolved.taskId, cwd: resolved.repoRoot, ...operation, pullRequest: intent, dependency },
+        agent: options.agent,
+        execute,
+        block: (error) => result('blocked', resolved.taskId, null, null, { error }),
+        persistenceFailure: (error) => result('failed', resolved.taskId, null, null, { error })
+    });
+}
 const PRECONDITION_NOT_CREATED = {
     kind: 'not-created', reason: 'precondition-failed', createdByCurrentOperation: false
 };
@@ -681,7 +702,7 @@ function bindIdentity(base, pullRequest, agent, source, dryRun = false, expected
         ]
     }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
 }
-async function bindPlatformPullRequest(taskRef, options) {
+async function bindPlatformPullRequestImpl(taskRef, options) {
     const base = await resolvedContext(taskRef, options);
     if (!base.ok)
         return base.output;
@@ -723,6 +744,10 @@ async function bindPlatformPullRequest(taskRef, options) {
         operations: [{ name: 'task:bind-pr', status: options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', reasonCode: null }], error: null
     });
 }
+async function bindPlatformPullRequest(taskRef, options) {
+    const intent = { action: 'bind', prToken: String(options.pr) };
+    return journalPullRequestOperation(taskRef, options, intent, `pr:${options.pr}`, { pr: String(options.pr) }, () => bindPlatformPullRequestImpl(taskRef, options));
+}
 function externalEvidenceNote(issueIdentity, source, pullRequest) {
     return [
         `authorization=${source}`,
@@ -915,7 +940,7 @@ async function resolveExternalPullRequest(taskRef, options) {
         error: null
     }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selectedPullRequest });
 }
-async function createPlatformPullRequest(taskRef, options) {
+async function createPlatformPullRequestImpl(taskRef, options) {
     const base = await resolvedContext(taskRef, options);
     if (!base.ok)
         return withCreation(base.output, PRECONDITION_NOT_CREATED);
@@ -946,6 +971,67 @@ async function createPlatformPullRequest(taskRef, options) {
         }), PRECONDITION_NOT_CREATED);
     }
 }
+async function recoverCreatedPullRequest(taskRef, options) {
+    const base = await resolvedContext(taskRef, options);
+    if (!base.ok)
+        return base.output;
+    if (!base.issueIdentity)
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            error: { code: 'PLATFORM_OPERATION_ISSUE_REQUIRED', message: 'Pull-request recovery requires a bound Issue identity', retryable: false }
+        });
+    const head = base.provider.changeRequests?.verifyHead
+        ? await base.provider.changeRequests.verifyHead({ context: providerOperationContext(base.loadedContext), head: options.head })
+        : unsupportedProviderOperation(base.provider, 'changeRequests.verifyHead');
+    if (!head.ok)
+        return providerPullRequestError(base, head.error, base.prNumber);
+    if (base.prIdentity) {
+        const inspected = await inspectExternalPullRequest(base, base.prIdentity);
+        if (!inspected.pullRequest || inspected.status === 'failed' || inspected.status === 'blocked'
+            || inspected.pullRequest.base.repository !== base.context.platform.repository
+            || inspected.pullRequest.base.ref !== options.base || inspected.pullRequest.head.ref !== options.head
+            || inspected.pullRequest.head.sha !== head.value.sha) {
+            return result('blocked', base.resolved.taskId, base.issueNumber, base.prNumber, {
+                error: inspected.error ?? { code: 'PLATFORM_OPERATION_PR_NOT_CONFIRMED', message: 'Bound pull request does not match the pending create intent', retryable: true }
+            });
+        }
+        return inspected;
+    }
+    const candidates = base.provider.changeRequests?.listClosing
+        ? await base.provider.changeRequests.listClosing({ context: providerOperationContext(base.loadedContext), issue: base.issueIdentity })
+        : unsupportedProviderOperation(base.provider, 'changeRequests.listClosing');
+    if (!candidates.ok)
+        return providerPullRequestError(base, candidates.error, null);
+    const matches = candidates.value.map((candidate) => normalizeProviderPullRequest(candidate, base.context.platform.repository, candidate.number || 0))
+        .filter((candidate) => candidate.base.repository === base.context.platform.repository
+        && candidate.base.ref === options.base
+        && candidate.head.repository === base.context.platform.repository
+        && candidate.head.ref === options.head
+        && candidate.head.sha === head.value.sha);
+    if (matches.length !== 1 || !matches[0]?.number)
+        return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+            error: { code: matches.length > 1 ? 'PLATFORM_OPERATION_PR_AMBIGUOUS' : 'PLATFORM_OPERATION_PR_NOT_CONFIRMED',
+                message: 'Pending pull-request creation does not resolve to one exact repository/base/head identity', retryable: true }
+        });
+    const bound = await bindPlatformPullRequest(base.resolved.taskId, { agent: options.agent, cwd: base.resolved.repoRoot, pr: matches[0].number });
+    if (!bound.pullRequest || (bound.status !== 'applied' && bound.status !== 'no-op') || bound.error)
+        return bound;
+    if (bound.pullRequest.base.repository !== base.context.platform.repository || bound.pullRequest.base.ref !== options.base
+        || bound.pullRequest.head.repository !== base.context.platform.repository || bound.pullRequest.head.ref !== options.head
+        || bound.pullRequest.head.sha !== head.value.sha)
+        return result('blocked', base.resolved.taskId, base.issueNumber, bound.task.prNumber, {
+            error: { code: 'PLATFORM_OPERATION_PR_NOT_CONFIRMED', message: 'Bound pull request changed while recovering the create intent', retryable: true }
+        });
+    return bound;
+}
+async function createPlatformPullRequest(taskRef, options) {
+    const intent = { action: 'create', baseRef: options.base, headRef: options.head };
+    const identityInput = {
+        title: createHash('sha256').update(options.title).digest('hex'),
+        body: createHash('sha256').update(options.body).digest('hex'),
+        draft: options.draft === true
+    };
+    return journalPullRequestOperation(taskRef, options, intent, `head:${options.head}:base:${options.base}`, identityInput, () => createPlatformPullRequestImpl(taskRef, options));
+}
 async function createExternalPullRequest(taskRef, options, base) {
     if (!base.fact)
         return withCreation(result('failed', base.resolved.taskId, base.issueNumber, null, {
@@ -974,9 +1060,35 @@ async function createExternalPullRequest(taskRef, options, base) {
     }
     if (base.prIdentity) {
         const inspected = await inspectExternalPullRequest(base, base.prIdentity);
-        return inspected.status === 'failed' || inspected.status === 'blocked'
-            ? withCreation(inspected, PRECONDITION_NOT_CREATED)
-            : withCreation({ ...inspected, result: 'no_op' }, { kind: 'no-op', createdByCurrentOperation: false });
+        if (inspected.status === 'failed' || inspected.status === 'blocked') {
+            return withCreation(inspected, PRECONDITION_NOT_CREATED);
+        }
+        const deliveredHeadSha = typeof base.frontmatter.delivery_remote_head === 'string'
+            ? base.frontmatter.delivery_remote_head
+            : undefined;
+        const expectedHeadSha = verifiedHeadSha ?? deliveredHeadSha;
+        if (!expectedHeadSha)
+            return withCreation(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+                platform: base.context.platform,
+                capabilities: base.context.capabilities,
+                resource: { kind: 'pull-request', number: base.prNumber, identity: base.prIdentity },
+                pullRequest: inspected.pullRequest,
+                error: { code: 'PR_HEAD_UNVERIFIED', message: 'Unable to verify the bound pull request head SHA', retryable: false }
+            }), PRECONDITION_NOT_CREATED);
+        const identity = validateWriterIdentity(base, inspected.pullRequest ?? null, {
+            expectedHead: options.head,
+            expectedHeadSha,
+            errorCode: 'PR_BIND_IDENTITY_MISMATCH'
+        });
+        if (!identity.ok)
+            return withCreation(result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+                platform: base.context.platform,
+                capabilities: base.context.capabilities,
+                resource: { kind: 'pull-request', number: base.prNumber, identity: base.prIdentity },
+                pullRequest: inspected.pullRequest,
+                error: identity.error
+            }), PRECONDITION_NOT_CREATED);
+        return withCreation({ ...inspected, result: 'no_op' }, { kind: 'no-op', createdByCurrentOperation: false });
     }
     if (options.dryRun)
         return withCreation(result('planned', base.resolved.taskId, base.issueNumber, null, {
@@ -1078,7 +1190,7 @@ async function createExternalPullRequest(taskRef, options, base) {
         error: null
     }), { kind: 'created', createdByCurrentOperation: true });
 }
-async function syncPlatformPullRequest(taskRef, options) {
+async function syncPlatformPullRequestImpl(taskRef, options) {
     const warningResult = warningResultForPrimary(options.primaryResult);
     const softenFailure = (output) => {
         const authorityError = output.error?.code.startsWith('IN_LABEL_SYNC') || output.error?.code.startsWith('PR_IDENTITY');
@@ -1262,6 +1374,12 @@ async function syncPlatformPullRequest(taskRef, options) {
         }));
     }
 }
+async function syncPlatformPullRequest(taskRef, options) {
+    const intent = { action: 'sync', metadata: options.metadata === true, closingIssue: options.closingIssue === true };
+    return journalPullRequestOperation(taskRef, options, intent, `bound-pr:${taskRef}`, {
+        metadata: options.metadata === true, closingIssue: options.closingIssue === true
+    }, () => syncPlatformPullRequestImpl(taskRef, options));
+}
 function readProjectPrFlow(repoRoot) {
     try {
         const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
@@ -1360,6 +1478,6 @@ async function skipPlatformPullRequestFact(taskRef, options) {
         });
     }
 }
-export { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, resolveExternalPullRequest, skipPlatformPullRequestFact, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest, syncPlatformPullRequestInLabels };
+export { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, recoverCreatedPullRequest, resolveExternalPullRequest, skipPlatformPullRequestFact, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest, syncPlatformPullRequestInLabels };
 export { warningResultForPrimary };
 //# sourceMappingURL=pull-requests.js.map

package/dist/lib/sandbox/commands/create.js

@@ -22,6 +22,7 @@ import { atomicWriteJson } from '../control/state.js';
 import { inspectSandboxControlContainer } from '../control/container-identity.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from '../mounts.js';
+import { materializeSandboxGitMetadata } from '../git-metadata.js';
 import { assertSandboxTaskSource, finalizeSandboxControlManifest, materializeSandboxControl, materializeSandboxWorkspaceView, prepareSandboxWorkspaceMountTargets, sandboxControlPaths, } from '../workspace-view.js';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.js';
 import { validateSelinuxDisableEnv } from '../engines/selinux.js';
@@ -630,7 +631,8 @@ function runSandboxAuthoritySafeCommand(authority, args) {
 // tmpfs. containerMount is an in-container path, so it is NOT engine-converted.
 export function buildTmpfsRunArgs(containerMount, tmpfs) {
     const size = tmpfs.size ?? '512m';
-    return ['--tmpfs', `${containerMount}:rw,size=${size}`];
+    const options = ['rw', ...(tmpfs.exec ? ['exec'] : []), `size=${size}`];
+    return ['--tmpfs', `${containerMount}:${options.join(',')}`];
 }
 export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env, refresh = false, lastRefresh, buildProxyArgs = [], buildEnv } = {}) {
     const selectedEngine = engine ?? detectEngine({ engine: config.engine });
@@ -1050,6 +1052,7 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                 engine,
                                 replacementLease,
                             });
+                            const gitMetadata = materializeSandboxGitMetadata(worktree, control.channelDir);
                             hostShellConfig = prepareHostShellConfig({
                                 home: effectiveConfig.home,
                                 project: effectiveConfig.project,
@@ -1057,6 +1060,8 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                 repoRoot: effectiveConfig.repoRoot
                             });
                             const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
+                                gitCommonDir: gitMetadata.commonDir,
+                                worktreeGitFile: gitMetadata.worktreeGitFile,
                                 worktree,
                                 shellConfigHostDir: hostShellConfig.hostDir,
                                 workspaceViewRoot: workspaceView.root,
@@ -1153,8 +1158,6 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                     `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
                                     ...coreVolumes,
                                     ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
-                                    '-v',
-                                    volumeArg(engine, path.join(effectiveConfig.repoRoot, '.git'), `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`),
                                     ...dotfilesMount,
                                     ...toolVolumes,
                                     ...tmpfsArgs,

package/dist/lib/sandbox/commands/ls.js

@@ -15,8 +15,9 @@ display-only row number; the 'SHORT' column shows the active task short
 id bound to each container's branch (via
 .agents/workspace/active/.short-ids.json), or '-' if no active task is
 bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
-A '-' means no active task is bound to that branch, so the sandbox is free
-to remove with "ai sandbox rm <branch>".
+A SHORT value of '-' means this container has no active task short id and may
+be eligible for "ai sandbox rm --unbound" cleanup. Use a full TASK-id to
+remove a specific task-bound sandbox.
 
 Use "ai sandbox show <ref>" for a single sandbox's worktree and per-tool
 state paths.`;
@@ -63,7 +64,7 @@ export function ls(args = []) {
             process.stdout.write(`  ${row.name}: health=${controlStatus?.state ?? 'unavailable'} task-view=${controlStatus?.taskView.state ?? 'unavailable'}\n`);
         }
         if (tableRows.some((r) => r.shortId === '-')) {
-            process.stdout.write(`  SHORT '-' = no active task bound; that sandbox is free to remove with 'ai sandbox rm <branch>'.\n`);
+            process.stdout.write(`  SHORT '-' = no active task short id is displayed; --unbound may clean this sandbox if its branch is not tied to an active task.\n`);
         }
     }
 }

package/dist/lib/sandbox/commands/rm.js

@@ -8,7 +8,7 @@ import { fetchSandboxRows } from './list-running.js';
 import { rmOne, rmPurge, rmUnbound } from '../removal.js';
 const USAGE = `Usage:
   ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
-  ai sandbox rm --unbound [--dry-run] [--yes] Remove discovered task-bound and branch-only sandboxes
+  ai sandbox rm --unbound [--dry-run] [--yes] Remove sandboxes not bound to an active task short id
   ai sandbox rm --purge                     Tear down ALL sandboxes for the project (containers, worktrees, image, VM)`;
 function resolveMissingTaskSandboxBranch(taskId, config) {
     const engine = detectEngine(config);

package/dist/lib/sandbox/config.js

@@ -50,10 +50,22 @@ function cloneDefaults() {
     };
 }
 function resolveSandboxToolIds(sandbox, defaults) {
-    if (Array.isArray(sandbox.tools)) {
-        return sandbox.tools.filter((tool) => typeof tool === 'string');
+    if (sandbox.tools === undefined) {
+        return [...defaults];
     }
-    return [...defaults];
+    if (typeof sandbox.tools !== 'object' || sandbox.tools === null || Array.isArray(sandbox.tools)) {
+        throw new Error('sandbox.tools must be an object when configured');
+    }
+    const tools = sandbox.tools;
+    if (!Array.isArray(tools.ids)) {
+        throw new Error('sandbox.tools.ids must be an array');
+    }
+    return tools.ids.map((id, index) => {
+        if (typeof id !== 'string') {
+            throw new Error(`sandbox.tools.ids[${index}] must be a string`);
+        }
+        return id;
+    });
 }
 export function loadConfig({ platformFn = platform, writeStderr = (chunk) => process.stderr.write(chunk) } = {}) {
     const repoRoot = detectRepoRoot();
@@ -100,7 +112,13 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
                 '  Update "sandbox.runtimes" in .agents/.airc.json (e.g. "node22"), or relax "engines.node".\n'));
         }
     }
-    const customTools = parseCustomTools(sandbox.customTools, { home });
+    const toolsConfig = sandbox.tools && typeof sandbox.tools === 'object' && !Array.isArray(sandbox.tools)
+        ? sandbox.tools
+        : undefined;
+    if (sandbox.customTools !== undefined) {
+        throw new Error('sandbox.customTools is no longer supported; use sandbox.tools.definitions');
+    }
+    const customTools = parseCustomTools(toolsConfig?.definitions, { home });
     const tools = resolveSandboxToolIds(sandbox, defaults.tools);
     return {
         repoRoot,

package/dist/lib/sandbox/control/server.js

@@ -171,13 +171,17 @@ function taskCreateDomainEvidence(manifest, output) {
         ? output.task : null;
     const taskId = typeof task?.id === 'string' ? task.id : null;
     const shortId = typeof task?.shortId === 'string' ? task.shortId : null;
-    if (!taskId || !shortId)
+    const state = task?.state;
+    if (!taskId || !['active', 'blocked', 'completed', 'archive'].includes(String(state)))
+        return { consistent: false };
+    if (state === 'active' ? !shortId : output.status !== 'no-op' || shortId !== null)
         return { consistent: false };
     try {
         const resolved = resolveTaskRef(taskId, { repoRoot: manifest.repoRoot });
         const shortIds = loadShortIdByTaskId(manifest.repoRoot);
         return {
-            consistent: resolved.ok && resolved.taskId === taskId && resolved.state === 'active' && shortIds.get(taskId) === shortId,
+            consistent: resolved.ok && resolved.taskId === taskId && resolved.state === state
+                && (state === 'active' ? shortIds.get(taskId) === shortId : !shortIds.has(taskId)),
             taskId,
             shortId
         };

package/dist/lib/sandbox/git-metadata.js

@@ -0,0 +1,50 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+export const SANDBOX_GIT_COMMON_DIR = '/run/agent-infra/git';
+function gitText(worktreeRoot, args) {
+    const env = { ...process.env };
+    for (const key of [
+        'GIT_DIR',
+        'GIT_COMMON_DIR',
+        'GIT_WORK_TREE',
+        'GIT_INDEX_FILE',
+        'GIT_PREFIX',
+        'GIT_NAMESPACE',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_CEILING_DIRECTORIES',
+        'GIT_DISCOVERY_ACROSS_FILESYSTEM'
+    ]) {
+        delete env[key];
+    }
+    return execFileSync('git', ['-C', worktreeRoot, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env
+    }).trim();
+}
+export function resolveSandboxGitMetadata(worktreeRoot, controlDir) {
+    const commonDir = fs.realpathSync.native(gitText(worktreeRoot, [
+        'rev-parse', '--path-format=absolute', '--git-common-dir'
+    ]));
+    const gitDir = fs.realpathSync.native(gitText(worktreeRoot, ['rev-parse', '--absolute-git-dir']));
+    const relativeGitDir = path.relative(commonDir, gitDir);
+    if (path.isAbsolute(relativeGitDir) || relativeGitDir.startsWith(`..${path.sep}`) || relativeGitDir === '..') {
+        throw new Error('SANDBOX_GIT_METADATA_INVALID: worktree git directory is outside its common directory');
+    }
+    const containerGitDir = relativeGitDir === '.'
+        ? SANDBOX_GIT_COMMON_DIR
+        : path.posix.join(SANDBOX_GIT_COMMON_DIR, ...relativeGitDir.split(path.sep));
+    return {
+        commonDir,
+        worktreeGitFile: path.join(controlDir, 'workspace.git'),
+        worktreeGitFileContent: `gitdir: ${containerGitDir}\n`
+    };
+}
+export function materializeSandboxGitMetadata(worktreeRoot, controlDir) {
+    const metadata = resolveSandboxGitMetadata(worktreeRoot, controlDir);
+    fs.mkdirSync(controlDir, { recursive: true });
+    fs.writeFileSync(metadata.worktreeGitFile, metadata.worktreeGitFileContent, 'utf8');
+    return metadata;
+}
+//# sourceMappingURL=git-metadata.js.map

package/dist/lib/sandbox/index.js

@@ -19,7 +19,7 @@ Commands:
   rm <branch | TASK-id> | --unbound | --purge
                                Remove one sandbox; use a full TASK-id for task-bound
                                cleanup and a branch for branch-only cleanup. --unbound
-                               removes discovered task-bound and branch-only sandboxes.
+                               removes sandboxes not bound to an active task short id.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/dist/lib/sandbox/mounts.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { shareBranchDir, shareCommonDir, shellConfigDirCandidates, worktreeDirCandidates } from './constants.js';
 import { sandboxWorkspaceViewStatePaths } from './workspace-view.js';
+import { SANDBOX_GIT_COMMON_DIR } from './git-metadata.js';
 export function sandboxCoreBindMounts(config, branch, overrides) {
     const taskSources = overrides.taskSources ?? [];
     const taskBound = Boolean(taskSources.length > 0 && overrides.taskId);
@@ -15,7 +16,17 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
             containerPath: path.posix.join('/workspace/.agents/workspace', state),
             readOnly: true
         });
+    if (Boolean(overrides.gitCommonDir) !== Boolean(overrides.worktreeGitFile)) {
+        throw new Error('SANDBOX_GIT_METADATA_INCOMPLETE');
+    }
+    const gitCommonMount = overrides.gitCommonDir
+        ? { hostPaths: [overrides.gitCommonDir], containerPath: SANDBOX_GIT_COMMON_DIR, readOnly: false }
+        : null;
+    const worktreeGitFileMount = overrides.worktreeGitFile
+        ? { hostPaths: [overrides.worktreeGitFile], containerPath: '/workspace/.git', readOnly: true }
+        : null;
     const mounts = [
+        ...(gitCommonMount ? [gitCommonMount] : []),
         {
             hostPaths: overrides.worktree
                 ? [overrides.worktree]
@@ -23,6 +34,7 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
             containerPath: '/workspace',
             readOnly: false
         },
+        ...(worktreeGitFileMount ? [worktreeGitFileMount] : []),
         ...workspaceMounts,
     ];
     if (taskBound) {

package/dist/lib/sandbox/recovery.js

@@ -9,6 +9,7 @@ import { isAgentClientId } from '../agent-clients/types.js';
 import { createSandboxCapabilityPlan } from './agent-client-reconciler.js';
 import { toEnginePath } from './engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from './mounts.js';
+import { resolveSandboxGitMetadata } from './git-metadata.js';
 import { assertSandboxTaskSource, sandboxControlPaths, sandboxWorkspaceViewPaths } from './workspace-view.js';
 import { resolveTaskWorkspace } from './task-resolver.js';
 import { parseSandboxWorkspaceIdentity, sameSandboxWorkspaceIdentity } from './workspace-identity.js';
@@ -530,7 +531,17 @@ function expectedMounts(params) {
         ? recoveryTaskSources(config.repoRoot, params.workspace.taskId)
         : null;
     const taskId = params.workspace.mode === 'task-bound' ? params.workspace.taskId : null;
+    const worktrees = worktreeDirCandidates(config, branch).filter((candidate) => fs.existsSync(path.join(candidate, '.git')));
+    const gitMetadata = worktrees.length === 1
+        ? resolveSandboxGitMetadata(worktrees[0], control.channelDir)
+        : null;
     const core = sandboxCoreBindMounts(config, branch, {
+        ...(gitMetadata === null
+            ? {}
+            : {
+                gitCommonDir: gitMetadata.commonDir,
+                worktreeGitFile: gitMetadata.worktreeGitFile
+            }),
         workspaceViewRoot: view.root,
         controlDir: control.channelDir,
         controlStatusDir: control.statusDir,

package/dist/lib/sandbox/removal.js

@@ -8,7 +8,7 @@ import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedV
 import { pruneSandboxDanglingImages } from './image-prune.js';
 import { assertManagedPath, removeManagedDir, removeWorktreeDir } from './managed-fs.js';
 import { run, runEngine, runOk, runOkEngine, runSafe, runSafeEngine } from './shell.js';
-import { parseSandboxWorkspaceIdentity, resolveSandboxCleanupTarget, sameSandboxWorkspaceIdentity } from './workspace-identity.js';
+import { parseSandboxWorkspaceIdentity, resolveSandboxCleanupTarget, resolveSandboxTarget, sameSandboxWorkspaceIdentity } from './workspace-identity.js';
 import { sandboxControlPaths, sandboxWorkspaceViewPaths } from './workspace-view.js';
 import { advanceSandboxRemovalJournalToPhase, advanceSandboxRemovalJournalPhase, claimSandboxRemovalJournal, clearSandboxRemovalJournalRecord, isDefaultSandboxRemovalJournal, listSandboxRemovalJournals, removeSandboxControlRoot, readSandboxControlManifest, sandboxRemovalPhaseIndex } from './control/lifecycle.js';
 import { inspectSandboxControlContainer } from './control/container-identity.js';
@@ -792,38 +792,76 @@ async function rmPurgeCore(config, tools, prompt = {}) {
     p.outro(pc.green('All project sandboxes removed'));
 }
 async function rmUnbound(config, tools, options) {
-    return rmUnboundCore(config, tools, options);
+    return withRepositoryMutationLock(config.repoRoot, () => rmUnboundCore(config, tools, options));
 }
 async function rmUnboundCore(config, tools, options) {
     const engine = detectEngine(config);
     const listed = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config), { mode: sandboxWorkspaceModeLabel(config), taskId: sandboxTaskIdLabel(config) });
-    const rows = [...listed.running, ...listed.nonRunning];
+    const discovered = [...listed.running, ...listed.nonRunning];
+    const branchMismatches = [];
+    const classified = discovered.map((row) => {
+        if (!row.branch)
+            return { row, protected: true, cleanupTarget: null };
+        if (row.workspaceMode === 'task-bound' && row.taskId) {
+            try {
+                resolveSandboxTarget(row.taskId, config.repoRoot);
+                return { row, protected: true, cleanupTarget: null };
+            }
+            catch {
+                try {
+                    const cleanupTarget = resolveSandboxCleanupTarget(row.taskId, config.repoRoot, { allowProtected: true });
+                    if (cleanupTarget.taskState === 'blocked'
+                        || cleanupTarget.taskState === 'completed'
+                        || cleanupTarget.taskState === 'archive') {
+                        if (row.branch !== cleanupTarget.branch) {
+                            branchMismatches.push({ container: row.name, labelBranch: row.branch, taskBranch: cleanupTarget.branch });
+                            return { row, protected: true, cleanupTarget: null };
+                        }
+                        const activeBranchTarget = resolveSandboxTarget(cleanupTarget.branch, config.repoRoot);
+                        if (activeBranchTarget.workspace.mode === 'branch-only') {
+                            return { row, protected: false, cleanupTarget };
+                        }
+                    }
+                }
+                catch {
+                    // An unresolved task identity has no active short-id evidence, so keep it out of bulk cleanup.
+                }
+                return { row, protected: true, cleanupTarget: null };
+            }
+        }
+        if (row.workspaceMode !== 'branch-only')
+            return { row, protected: true, cleanupTarget: null };
+        const cleanupTarget = resolveSandboxCleanupTarget(row.branch, config.repoRoot);
+        return cleanupTarget.workspace.mode === 'branch-only'
+            ? { row, protected: false, cleanupTarget }
+            : { row, protected: true, cleanupTarget: null };
+    });
+    const protectedBranches = new Set(classified
+        .filter((entry) => entry.protected)
+        .map(({ row }) => row.branch));
+    const targets = classified
+        .filter((entry) => !entry.protected && !protectedBranches.has(entry.row.branch) && entry.cleanupTarget)
+        .map(({ row, cleanupTarget }) => ({
+        row,
+        cleanupTarget: cleanupTarget,
+        target: resolveRmTarget(config, tools, cleanupTarget, { discoveredContainers: [row.name] })
+    }));
     p.intro(pc.cyan(`Removing sandboxes for ${config.project}`));
+    for (const mismatch of branchMismatches) {
+        p.log.warn(`Skipping task-bound sandbox '${mismatch.container}': container branch '${mismatch.labelBranch}' differs from task record branch '${mismatch.taskBranch}'. Inspect the task record and container labels before retrying cleanup.`);
+    }
     if (options.dryRun) {
-        p.outro(`Dry run: ${rows.length} sandbox(es) found, nothing deleted`);
+        p.outro(`Dry run: ${targets.length} sandbox(es) found, nothing deleted`);
         return;
     }
-    for (const row of rows) {
-        if (!row.branch) {
-            runSafeEngine(engine, 'docker', ['rm', '-f', row.name]);
-            continue;
-        }
-        const cleanupTarget = {
-            requestedRef: row.branch,
-            branch: row.branch,
-            workspace: row.workspaceMode === 'task-bound' && row.taskId
-                ? { mode: 'task-bound', taskId: row.taskId }
-                : { mode: 'branch-only' },
-            taskState: 'branch-only'
-        };
-        const target = resolveRmTarget(config, tools, cleanupTarget, { discoveredContainers: [row.name] });
-        await rmOne(config, tools, cleanupTarget.branch, {
+    for (const { row, cleanupTarget, target } of targets) {
+        await runRmOneUnderRepositoryLock(config, tools, cleanupTarget.branch, {
             assumeYes: options.assumeYes,
             target,
             cleanupTarget
         });
     }
-    p.outro(pc.green(`Removed ${rows.length} sandbox(es)`));
+    p.outro(pc.green(`Removed ${targets.length} sandbox(es)`));
 }
 export { authorizeWorktrees, rmOne, rmPurge, rmUnbound };
 //# sourceMappingURL=removal.js.map

package/dist/lib/sandbox/tools.js

@@ -56,6 +56,15 @@ function asOptionalNonEmptyString(value, field, context) {
     }
     return value;
 }
+function asOptionalBoolean(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'boolean') {
+        throw new Error(`${context}: field "${field}" must be a boolean when provided`);
+    }
+    return value;
+}
 function asStringRecord(value, field, context) {
     if (value === undefined) {
         return undefined;
@@ -158,13 +167,14 @@ function parseTmpfs(value, context) {
     if (!isPlainObject(value)) {
         throw new Error(`${context}: field "tmpfs" must be an object when provided`);
     }
+    const exec = asOptionalBoolean(value.exec, 'tmpfs.exec', context);
     return {
         size: asOptionalNonEmptyString(value.size, 'tmpfs.size', context),
-        seed: asStringArray(value.seed, 'tmpfs.seed', context)
+        seed: asStringArray(value.seed, 'tmpfs.seed', context),
+        ...(exec === undefined ? {} : { exec })
     };
 }
-export function parseCustomTool(entry, index, options) {
-    const context = `customTools[${index}]`;
+export function parseCustomTool(entry, index, options, context = `customTools[${index}]`) {
     if (!isPlainObject(entry)) {
         throw new Error(`${context} must be an object`);
     }
@@ -198,13 +208,25 @@ export function parseCustomTool(entry, index, options) {
     return tool;
 }
 export function parseCustomTools(value, options) {
-    if (value === undefined || value === null) {
+    if (value === undefined) {
         return [];
     }
-    if (!Array.isArray(value)) {
-        throw new Error('sandbox: "customTools" must be an array');
+    if (!isPlainObject(value)) {
+        throw new Error('sandbox.tools.definitions must be an object');
     }
-    return value.map((entry, index) => parseCustomTool(entry, index, options));
+    return Object.entries(value).map(([id, definition], index) => {
+        const context = `sandbox.tools.definitions.${id}`;
+        if (!TOOL_ID_PATTERN.test(id)) {
+            throw new Error(`${context}: tool id must match ${TOOL_ID_PATTERN.source}`);
+        }
+        if (!isPlainObject(definition)) {
+            throw new Error(`${context} must be an object`);
+        }
+        if (Object.hasOwn(definition, 'id')) {
+            throw new Error(`${context}.id is not allowed; the definition key is the tool id`);
+        }
+        return parseCustomTool({ ...definition, id }, index, options, context);
+    });
 }
 export function resolveTools(config) {
     return [...createSandboxCapabilityPlan(config).tools];