@fitlab-ai/agent-infra 0.11.6 → 0.11.8

package/lib/platform/operation-coordinator.ts

@@ -0,0 +1,96 @@
+import { recoverPlatformOperations } from '../task/platform-operation-recovery.ts';
+import { recordPlatformOperation } from '../task/platform-operation-journal.ts';
+import type { RecordOperationInput } from '../task/platform-operation-journal.ts';
+import type { PlatformError, PlatformStatus } from './types.ts';
+import type { PlatformClient } from './context.ts';
+
+type OperationResult = Readonly<{
+  status: PlatformStatus;
+  error?: PlatformError | null;
+  warnings?: readonly { code: string }[];
+}>;
+
+type CoordinateInput<T extends OperationResult> = Readonly<{
+  operation: Omit<RecordOperationInput, 'state' | 'lastCode'>;
+  agent: string;
+  client?: PlatformClient;
+  drain?: (taskRef: string, excludeId: string, agent: string, cwd?: string) => Promise<{
+    status: 'applied' | 'no-op' | 'blocked' | 'failed';
+    error: PlatformError | null;
+  }>;
+  execute: () => Promise<T>;
+  block: (error: PlatformError) => T;
+  persistenceFailure: (error: PlatformError) => T;
+}>;
+
+async function coordinatePlatformWrite<T extends OperationResult>(input: CoordinateInput<T>): Promise<T> {
+  let operationId: string;
+  try {
+    const queued = recordPlatformOperation({ ...input.operation, state: 'queued' });
+    operationId = queued.id;
+  } catch (error) {
+    const value = error as { code?: string; message?: string };
+    return input.persistenceFailure({
+      code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+      message: value.message || 'Unable to queue platform operation',
+      retryable: true
+    });
+  }
+
+  const selection = input.operation.kind === 'issue-metadata' && input.operation.issueMetadata?.state === 'closed'
+    ? 'all' : input.operation.dependency;
+  const drained = input.drain
+    ? await input.drain(input.operation.taskRef, operationId, input.agent, input.operation.cwd)
+    : await recoverPlatformOperations(input.operation.taskRef, selection, {
+      agent: input.agent,
+      client: input.client,
+      cwd: input.operation.cwd,
+      excludeId: operationId
+    });
+  if (drained.status !== 'applied' && drained.status !== 'no-op') {
+    return input.block(drained.error ?? {
+      code: 'PLATFORM_OPERATION_QUEUE_BLOCKED',
+      message: 'A previous platform operation is still unresolved; the current write remains queued',
+      retryable: true
+    });
+  }
+
+  try {
+    recordPlatformOperation({ ...input.operation, state: 'pending' });
+  } catch (error) {
+    const value = error as { code?: string; message?: string };
+    return input.persistenceFailure({
+      code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+      message: value.message || 'Unable to mark platform operation as started',
+      retryable: true
+    });
+  }
+
+  let output: T;
+  try {
+    output = await input.execute();
+  } catch (error) {
+    const value = error as { code?: string; message?: string };
+    output = input.block({ code: value.code || 'PLATFORM_WRITE_FAILED', message: value.message || String(error), retryable: true });
+  }
+  const succeeded = (output.status === 'applied' || output.status === 'no-op')
+    && !output.error && !(output.warnings?.length);
+  const state = succeeded ? 'succeeded' : output.status === 'failed' && output.error?.retryable === false ? 'failed' : 'unknown';
+  try {
+    recordPlatformOperation({
+      ...input.operation,
+      state,
+      lastCode: output.error?.code ?? output.warnings?.[0]?.code ?? null
+    });
+  } catch (error) {
+    const value = error as { code?: string; message?: string };
+    return input.persistenceFailure({
+      code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+      message: value.message || 'Unable to persist platform operation outcome',
+      retryable: true
+    });
+  }
+  return output;
+}
+
+export { coordinatePlatformWrite };

package/lib/platform/pr-review.ts

@@ -1,3 +1,8 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { platformResult } from './types.ts';
@@ -9,8 +14,10 @@ import {
   providerResourceToken,
   unsupportedProviderOperation
 } from './provider-bridge.ts';
-import { isResourceIdentity, resourceIdentityNumber, reviewMarker as resourceReviewMarker } from './resource-identity.ts';
+import { isResourceIdentity, resourceIdentityEquals, resourceIdentityNumber, reviewMarker as resourceReviewMarker } from './resource-identity.ts';
 import type { ResourceIdentity } from './resource-identity.ts';
+import type { PlatformPullRequestReviewIntent } from '../task/platform-operation-journal.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
 
 export type PrReviewEvent = 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
 export type PrReviewIdentity = { scope: string; round: number; commitSha: string; resource?: ResourceIdentity };
@@ -38,6 +45,36 @@ function normalizeBody(body: string): string {
   return String(body || '').replace(/\r\n/g, '\n').replace(/\n+$/, '\n');
 }
 
+function canonicalReviewBody(body: string): string {
+  return normalizeBody(body).replace(/\n$/u, '');
+}
+
+function reviewArtifactName(round: number, artifactFile: string): boolean {
+  return path.basename(artifactFile) === artifactFile
+    && (artifactFile === 'pr-review.md' && round === 1 || artifactFile === `pr-review-r${round}.md`);
+}
+
+export function readReviewBodyFile(taskRef: string, round: number, artifactFile: string, bodyDigest: string, cwd?: string): string {
+  if (!/^TASK-\d{8}-\d{6}$/u.test(taskRef) || path.basename(artifactFile) !== artifactFile
+    || !reviewArtifactName(round, artifactFile)) {
+    throw Object.assign(new Error('Pull-request review artifact identity is invalid'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+  }
+  const task = resolveTaskRef(taskRef, cwd ? { repoRoot: cwd } : {});
+  if (!task.ok) throw Object.assign(new Error(task.message), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+  const bodyFile = artifactFile.replace(/^pr-review/u, 'pr-review-body');
+  const report = fs.readFileSync(path.join(task.taskDir, artifactFile), 'utf8');
+  const bodyReferences = [...report.matchAll(/^\*\*(?:正文文件|Body file)\*\*(?:：|:)\s*`([^`]+)`[^\r\n]*$/gmu)]
+    .map((match) => match[1]);
+  if (bodyReferences.length !== 1 || bodyReferences[0] !== bodyFile) {
+    throw Object.assign(new Error('Pull-request review artifact does not reference its canonical body file'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+  }
+  const body = canonicalReviewBody(fs.readFileSync(path.join(task.taskDir, bodyFile), 'utf8'));
+  if (!body || createHash('sha256').update(body).digest('hex') !== bodyDigest) {
+    throw Object.assign(new Error('Canonical pull-request review body does not match its persisted digest'), { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID' });
+  }
+  return body;
+}
+
 function firstLine(body: string): string {
   return normalizeBody(String(body || '')).split('\n', 1)[0] || '';
 }
@@ -90,6 +127,11 @@ export async function publishPrReview(options: {
   cwd?: string;
   client?: PlatformClient;
   dryRun?: boolean;
+  agent?: string;
+  skipQueue?: boolean;
+  expectedResource?: ResourceIdentity;
+  expectedProviderScopeId?: string;
+  recoveryArtifact?: string;
   prNumber: PrToken;
   identity: PrReviewIdentity;
   event: PrReviewEvent;
@@ -100,6 +142,13 @@ export async function publishPrReview(options: {
   if (!hasUsableContext(context)) {
     return platformResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error });
   }
+  const providerScopeId = loaded.ok ? loaded.value.snapshot.scope.id : null;
+  if (options.expectedProviderScopeId && providerScopeId !== options.expectedProviderScopeId) {
+    return platformResult('failed', {
+      platform: context.platform, capabilities: context.capabilities,
+      error: { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Current provider scope differs from the persisted operation target', retryable: false }
+    });
+  }
   const identity = loaded.ok ? (() => { try { return providerResourceToken(loaded.value.provider, 'pull-request', String(options.prNumber)); } catch { return null; } })() : null;
   if (!identity) {
     return platformResult('failed', {
@@ -108,6 +157,13 @@ export async function publishPrReview(options: {
     });
   }
   const identityNumber = resourceIdentityNumber(identity);
+  if (options.expectedResource && !resourceIdentityEquals(identity, options.expectedResource)) {
+    return platformResult('failed', {
+      platform: context.platform, capabilities: context.capabilities,
+      resource: { kind: 'pull-request', number: identityNumber, identity },
+      error: { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Current pull request identity differs from the persisted operation target', retryable: false }
+    });
+  }
   if (!REVIEW_EVENTS.includes(options.event)) {
     return platformResult('failed', {
       platform: context.platform, capabilities: context.capabilities,
@@ -123,6 +179,62 @@ export async function publishPrReview(options: {
     });
   }
 
+  if (/^TASK-\d{8}-\d{6}$/u.test(options.identity.scope) && !options.skipQueue && !options.dryRun) {
+    if (!options.agent) return platformResult('failed', {
+      platform: context.platform, capabilities: context.capabilities,
+      resource: { kind: 'pull-request', number: identityNumber, identity },
+      error: { code: 'PR_REVIEW_AGENT_REQUIRED', message: 'task-scoped review publication requires an agent token', retryable: false }
+    });
+    if (!options.recoveryArtifact || !reviewArtifactName(options.identity.round, options.recoveryArtifact)) return platformResult('failed', {
+      platform: context.platform, capabilities: context.capabilities,
+      resource: { kind: 'pull-request', number: identityNumber, identity },
+      error: { code: 'PR_REVIEW_ARTIFACT_REQUIRED', message: 'task-scoped review publication requires its canonical review artifact', retryable: false }
+    });
+    const body = canonicalReviewBody(options.body);
+    const bodyDigest = createHash('sha256').update(body).digest('hex');
+    try {
+      if (readReviewBodyFile(options.identity.scope, options.identity.round, options.recoveryArtifact, bodyDigest, options.cwd) !== body) throw new Error('body mismatch');
+    } catch {
+      return platformResult('failed', {
+        platform: context.platform, capabilities: context.capabilities,
+        resource: { kind: 'pull-request', number: identityNumber, identity },
+        error: { code: 'PR_REVIEW_ARTIFACT_MISMATCH', message: 'Review body must match the canonical review body file', retryable: false }
+      });
+    }
+    const pullRequestReview: PlatformPullRequestReviewIntent = {
+      prNumber: String(options.prNumber),
+      resource: identity,
+      providerScopeId: providerScopeId!,
+      scope: options.identity.scope,
+      round: options.identity.round,
+      commitSha: options.identity.commitSha,
+      event: options.event,
+      artifactFile: options.recoveryArtifact,
+      bodyDigest
+    };
+    return coordinatePlatformWrite({
+      operation: {
+        taskRef: options.identity.scope,
+        cwd: options.cwd || process.cwd(),
+        kind: 'pull-request-review',
+        target: JSON.stringify(identity),
+        expectedDigest: createHash('sha256').update(JSON.stringify(pullRequestReview)).digest('hex'),
+        dependency: 'deferred',
+        pullRequestReview
+      },
+      agent: options.agent,
+      execute: () => publishPrReview({ ...options, expectedProviderScopeId: providerScopeId!, skipQueue: true }),
+      block: (error) => platformResult('blocked', {
+        platform: context.platform, capabilities: context.capabilities,
+        resource: { kind: 'pull-request', number: identityNumber, identity }, error
+      }),
+      persistenceFailure: (error) => platformResult('failed', {
+        platform: context.platform, capabilities: context.capabilities,
+        resource: { kind: 'pull-request', number: identityNumber, identity }, error
+      })
+    });
+  }
+
   const marker = reviewMarker({ ...options.identity, resource: identity });
   const listed = await listPrReviews(options.prNumber, { cwd: options.cwd, client: options.client });
   if (listed.status === 'failed' || listed.status === 'blocked') return listed;

package/lib/platform/pr-summary.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 
 import { enumerateArtifacts } from '../task/artifacts.ts';
 import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
@@ -13,6 +14,7 @@ import { normalizeCommentContent } from './issue-comments.ts';
 import { CONTROL_MARKER_PATTERN, sanitizeMarkdownDocument, splitDocumentPlaceholder } from './comment-safety.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
+import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import type { OperationWarning } from '../task/operation-outcome.ts';
 import { providerError, providerOperationContext, providerStatus, providerResourceToken, resourceIdentityNumber, unsupportedProviderOperation } from './provider-bridge.ts';
 import { resourceIdentityEquals } from './resource-identity.ts';
@@ -491,7 +493,7 @@ async function reportWrite(taskRef: string, options: ReportWriteOptions): Promis
 
 async function syncPullRequestSummary(
   taskRef: string,
-  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string; manualValidation?: ManualValidationSummaryOptions; lockAlreadyHeld?: boolean }
+  options: { agent: string; body: string; changeReportFile?: string; cwd?: string; client?: PlatformClient; dryRun?: boolean; strict?: boolean; primaryResult: PullRequestPrimaryResult; runtimeVersion?: string; manualValidation?: ManualValidationSummaryOptions; lockAlreadyHeld?: boolean; skipQueue?: boolean }
 ): Promise<PullRequestSummaryResult> {
   const warningResult = warningResultForPrimary(options.primaryResult);
   let knownPrNumber: number | null = null;
@@ -657,6 +659,7 @@ async function syncPullRequestSummary(
         operations: [{ name: `summary:${reconciliation.action}`, status: 'planned', reasonCode: null }],
         result: null, warnings: [], ...info
       };
+      const publish = async (): Promise<PullRequestSummaryResult> => {
       const existingComment = reconciliation.commentId === null
         ? undefined
         : providerResourceToken(loaded.value.provider, 'comment', String(reconciliation.commentId));
@@ -722,6 +725,24 @@ async function syncPullRequestSummary(
         operations: [{ name: `summary:${reconciliation.action}`, status: 'applied', reasonCode: null }],
         result: null, warnings: [], ...info
       };
+      };
+      const operation = {
+        taskRef: resolved.taskId,
+        cwd: resolved.repoRoot,
+        kind: 'pull-request-summary' as const,
+        target: JSON.stringify(prIdentity),
+        expectedDigest: createHash('sha256').update(desired).digest('hex'),
+        dependency: 'deferred' as const,
+        pullRequestSummary: { body: options.body, changeReportFile: options.changeReportFile! }
+      };
+      if (options.skipQueue) return publish();
+      return coordinatePlatformWrite({
+        operation,
+        agent: options.agent,
+        execute: publish,
+        block: (error) => fail('blocked', context, error, prNumber),
+        persistenceFailure: (error) => fail('failed', context, error, prNumber)
+      });
     };
     return await (options.lockAlreadyHeld
       ? execute()

package/lib/platform/pull-requests.ts

@@ -1,6 +1,7 @@
 import { normalizePullRequest, type RemotePullRequest } from './github-data.ts';
 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.ts';
@@ -41,6 +42,8 @@ import {
 import { isResourceIdentity, resourceIdentityEquals, resourceIdentityNumber, serializeResourceIdentity } from './resource-identity.ts';
 import type { ResourceIdentity } from './resource-identity.ts';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.ts';
+import { coordinatePlatformWrite } from './operation-coordinator.ts';
+import type { PlatformPullRequestIntent } from '../task/platform-operation-journal.ts';
 import type { ChangeRequestSnapshot as ProviderChangeRequestSnapshot, IssueSnapshot as ProviderIssueSnapshot } from './provider-contract.ts';
 
 type PullRequestSnapshot = PlatformChangeRequestSnapshot;
@@ -63,7 +66,7 @@ type PullRequestResult = PlatformResult & {
   }>;
 };
 type InspectionOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
-type SharedOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
+type SharedOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string; skipQueue?: boolean };
 type CreateOptions = SharedOptions & {
   agent: string;
   base: string;
@@ -137,6 +140,30 @@ function withCreation(output: PullRequestResult, creation: CreationOutcome): Pul
   return { ...output, creation };
 }
 
+async function journalPullRequestOperation(
+  taskRef: string,
+  options: SharedOptions & { agent: string; dryRun?: boolean },
+  intent: PlatformPullRequestIntent,
+  target: string,
+  identityInput: unknown,
+  execute: () => Promise<PullRequestResult>
+): Promise<PullRequestResult> {
+  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' as const, 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: CreationOutcome = {
   kind: 'not-created', reason: 'precondition-failed', createdByCurrentOperation: false
 };
@@ -851,7 +878,7 @@ function bindIdentity(
   }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
 }
 
-async function bindPlatformPullRequest(taskRef: string, options: BindOptions): Promise<PullRequestResult> {
+async function bindPlatformPullRequestImpl(taskRef: string, options: BindOptions): Promise<PullRequestResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
   if (!base.fact) return result('failed', base.resolved.taskId, base.issueNumber, null, {
@@ -884,6 +911,12 @@ async function bindPlatformPullRequest(taskRef: string, options: BindOptions): P
   });
 }
 
+async function bindPlatformPullRequest(taskRef: string, options: BindOptions): Promise<PullRequestResult> {
+  const intent: PlatformPullRequestIntent = { action: 'bind', prToken: String(options.pr) };
+  return journalPullRequestOperation(taskRef, options, intent, `pr:${options.pr}`, { pr: String(options.pr) },
+    () => bindPlatformPullRequestImpl(taskRef, options));
+}
+
 function externalEvidenceNote(
   issueIdentity: ResourceIdentity | null,
   source: 'unique' | 'explicit',
@@ -1077,7 +1110,7 @@ async function resolveExternalPullRequest(taskRef: string, options: ResolveExter
   }), { mode: 'external', authorization: selected.source, candidates: selected.candidates, eligible: selected.eligible, selected: selectedPullRequest });
 }
 
-async function createPlatformPullRequest(taskRef: string, options: CreateOptions): Promise<PullRequestResult> {
+async function createPlatformPullRequestImpl(taskRef: string, options: CreateOptions): Promise<PullRequestResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return withCreation(base.output, PRECONDITION_NOT_CREATED);
   if (!options.base || !options.head || !options.title.trim() || !options.body.trim()) {
@@ -1112,6 +1145,66 @@ async function createPlatformPullRequest(taskRef: string, options: CreateOptions
   }
 }
 
+async function recoverCreatedPullRequest(
+  taskRef: string,
+  options: SharedOptions & { agent: string; base: string; head: string }
+): Promise<PullRequestResult> {
+  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: string, options: CreateOptions): Promise<PullRequestResult> {
+  const intent: PlatformPullRequestIntent = { 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: string,
   options: CreateOptions,
@@ -1140,9 +1233,33 @@ async function createExternalPullRequest(
   }
   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, {
     platform: base.context.platform,
@@ -1242,7 +1359,7 @@ async function createExternalPullRequest(
   }), { kind: 'created', createdByCurrentOperation: true });
 }
 
-async function syncPlatformPullRequest(taskRef: string, options: SyncOptions): Promise<PullRequestResult> {
+async function syncPlatformPullRequestImpl(taskRef: string, options: SyncOptions): Promise<PullRequestResult> {
   const warningResult = warningResultForPrimary(options.primaryResult);
   const softenFailure = (output: PullRequestResult): PullRequestResult => {
     const authorityError = output.error?.code.startsWith('IN_LABEL_SYNC') || output.error?.code.startsWith('PR_IDENTITY');
@@ -1406,6 +1523,13 @@ async function syncPlatformPullRequest(taskRef: string, options: SyncOptions): P
   }
 }
 
+async function syncPlatformPullRequest(taskRef: string, options: SyncOptions): Promise<PullRequestResult> {
+  const intent: PlatformPullRequestIntent = { 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: string): 'required' | 'disabled' | undefined {
   try {
     const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')) as { prFlow?: unknown };
@@ -1503,6 +1627,6 @@ async function skipPlatformPullRequestFact(taskRef: string, options: SkipFactOpt
   }
 }
 
-export { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, resolveExternalPullRequest, skipPlatformPullRequestFact, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest, syncPlatformPullRequestInLabels };
+export { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, inspectPlatformPullRequestByNumber, recoverCreatedPullRequest, resolveExternalPullRequest, skipPlatformPullRequestFact, selectExternalPullRequest, selectPullRequest, syncPlatformPullRequest, syncPlatformPullRequestInLabels };
 export type { BindOptions, CreateOptions, ExternalPullRequestResult, ExternalPullRequestSelection, PullRequestPrimaryResult, PullRequestResult, PullRequestSnapshot, ResolveExternalOptions, SkipFactOptions, SyncOptions };
 export { warningResultForPrimary };

package/lib/sandbox/commands/create.ts

@@ -83,6 +83,7 @@ import { atomicWriteJson } from '../control/state.ts';
 import { inspectSandboxControlContainer } from '../control/container-identity.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from '../mounts.ts';
+import { materializeSandboxGitMetadata } from '../git-metadata.ts';
 import {
   assertSandboxTaskSource,
   finalizeSandboxControlManifest,
@@ -950,9 +951,10 @@ function runSandboxAuthoritySafeCommand(
 
 // `docker run` args for mounting a tool's containerMount as an in-container
 // tmpfs. containerMount is an in-container path, so it is NOT engine-converted.
-export function buildTmpfsRunArgs(containerMount: string, tmpfs: { size?: string }): string[] {
+export function buildTmpfsRunArgs(containerMount: string, tmpfs: { size?: string; exec?: boolean }): string[] {
   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(
@@ -1459,6 +1461,7 @@ export async function create(
               engine,
               replacementLease,
             });
+            const gitMetadata = materializeSandboxGitMetadata(worktree, control.channelDir);
             hostShellConfig = prepareHostShellConfig({
               home: effectiveConfig.home,
               project: effectiveConfig.project,
@@ -1466,6 +1469,8 @@ export async function create(
               repoRoot: effectiveConfig.repoRoot
             });
             const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
+              gitCommonDir: gitMetadata.commonDir,
+              worktreeGitFile: gitMetadata.worktreeGitFile,
               worktree,
               shellConfigHostDir: hostShellConfig.hostDir,
               workspaceViewRoot: workspaceView.root,
@@ -1572,12 +1577,6 @@ export async function create(
               `${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/lib/sandbox/commands/ls.ts

@@ -22,8 +22,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.`;
@@ -97,7 +98,7 @@ export function ls(args: string[] = []): void {
     }
     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`
+        `  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/lib/sandbox/commands/rm.ts

@@ -14,7 +14,7 @@ import { rmOne, rmPurge, rmUnbound } from '../removal.ts';
 
 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: string, config: ReturnType<typeof loadConfig>): string | null {