@amistio/cli 0.1.34 → 0.1.36

package/README.md

@@ -53,7 +53,7 @@ When `--tool codex` uses the Codex SDK, intermediate progress can be quiet until
 
 The runner advertises its supported work kinds in heartbeats. Current runners can claim read-only `projectContextRefresh` jobs from the workspace Context panel and create due runner-driven refreshes when no fresh approved map exists. Context refreshes inspect the paired checkout locally without modifying files and submit only bounded summaries, slices, entities, relations, safe citations, confidence, freshness, and repo-relative paths. If a submitted context refresh contains unsafe evidence, unsafe paths, or a map too large to store safely, Amistio marks the refresh failed with a safe reason instead of storing the rejected raw result. Approved maps are reused as context packs for source-aware assistant and impact-preview work. Current runners can also claim read-only issue diagnosis jobs from the web Issues panel, generate root-cause analysis and a proposed fix, and submit that result without modifying source. They can claim manual read-only `appEvaluationScan` jobs from the workspace Evaluate panel and create at most one due hourly evaluation during normal watch/background polling when app evaluation is enabled for the repository link. Evaluation results contain bounded summaries, safe evidence, suggested actions, lifecycle proposals, and repo-relative paths only. Current runners can also claim manual read-only `securityPostureScan` jobs from the workspace Security panel and create due daily posture checks during normal watch/background polling. Security scan results contain bounded summaries, standard references, safe evidence, and repo-relative paths only. Current runners can claim manual read-only `testQualityScan` jobs from the workspace Test panel and create one due daily Test scan per repository when Test quality is enabled. Test scans run only existing lint, typecheck, test, coverage, build, or verify commands and submit bounded command summaries, coverage summaries, safe findings, blocked reasons, warnings, and repo-relative paths. Missing tests, missing coverage, low coverage, failing checks, flaky tests, and test gaps create reviewable plan-backed findings in the app. Current runners also claim `implementationTestGate` jobs before implementation completion, PR handoff, or runner-managed push; a passing gate is required unless the web Test panel records an audited override. Blocked implementation Test gates submit structured Test findings, such as `blockedEnvironment`, with safe evidence, a suggested action, and a verification plan. Current runners can claim read-only `implementationVerification` jobs from Tasks to prove whether completed implementation work actually landed; verification submits bounded acceptance-criteria evidence, checks, gaps, outcome, and recommendation without mutating source. Source, secrets, environment variables, command lines, process lists, credentials, provider sessions, and arbitrary local paths stay local. Implementation or cleanup is queued separately only after the user approves an issue analysis, app evaluation finding, security remediation plan, or Test quality plan in the app.
 
-Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as `.env.local` or `.env.test.local` from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status. It then commits all source and artifact changes, fetches and rebases from the linked remote's default branch, pushes an `amistio/work/...` branch, opens or reuses a pull request with the locally authenticated `gh` CLI, reports only safe PR and artifact-inclusion metadata to Amistio, and removes the local worktree after the PR URL is durable. Artifact-only materialization changes still create or reuse a PR; no-change completion requires no source changes and no approved artifact changes. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and `gh auth status`. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked and the branch/worktree stay on disk for manual recovery; source files and patches are not uploaded to Amistio.
+Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as `.env.local` or `.env.test.local` from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status. It then commits all source and artifact changes, fetches and rebases from the linked remote's default branch, pushes an `amistio/work/...` branch, opens or reuses a pull request with the locally authenticated `gh` CLI, reports only safe PR and artifact-inclusion metadata to Amistio, and removes the local worktree after the PR URL is durable. Artifact-only materialization changes still create or reuse a PR; no-change completion requires no source changes and no approved artifact changes, and runner-created no-change worktrees are removed after final clean checks. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and `gh auth status`. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked with safe recovery choices; source files and patches are not uploaded to Amistio. The Work panel can queue scoped Retry handoff or Retry cleanup commands to the paired runner for the same work item, branch, and worktree key. Rebase conflicts capture bounded repo-relative conflict files and try `git rebase --abort` so the implementation branch can be retried or manually reviewed without leaving an active rebase. Dirty, unmerged, or ambiguous worktrees are preserved rather than discarded.
 
 Failed or stale work can be requeued from the web Tasks panel. Requeue creates a new linked work attempt and preserves the original terminal attempt for audit history; it is blocked while equivalent work is already active or when the paired runner does not advertise the needed work kind. Completed implementation status is separate from proof: queue `implementationVerification` from Tasks when a plan needs source-aware evidence before cleanup or implementation status decisions.
 

package/dist/index.js

@@ -148,6 +148,9 @@ var autopilotGuardCheckSchema = z.object({
 });
 var implementationHandoffStatusSchema = z.enum(["notStarted", "noChanges", "prReady", "blocked", "failed"]);
 var implementationHandoffCleanupStatusSchema = z.enum(["notApplicable", "pending", "completed", "failed"]);
+var implementationHandoffRecoveryCategorySchema = z.enum(["noChangeCleaned", "rebaseConflict", "dirtyWorktree", "unresolvedConflicts", "providerBlocked", "cleanupRetryAvailable", "manualReview", "artifactBlocked", "nonGithubProvider"]);
+var implementationHandoffRecoveryActionSchema = z.enum(["retryHandoff", "requeueFreshAttempt", "keepForManualRepair", "cleanNoChangeWorktree", "markSupersededNoChanges", "exportHandoffDetails", "retryCleanup"]);
+var implementationHandoffRebaseAbortStatusSchema = z.enum(["notAttempted", "succeeded", "failed", "notApplicable"]);
 var safeRepoPathSchema = z.string().trim().min(1).max(300).refine((value) => {
   if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value)) {
     return false;
@@ -168,6 +171,15 @@ var implementationHandoffArtifactsSchema = z.object({
   skipped: z.array(implementationHandoffArtifactSchema).max(50).default([]),
   blocked: z.array(implementationHandoffArtifactSchema).max(50).default([])
 }).strict();
+var implementationHandoffRecoverySchema = z.object({
+  category: implementationHandoffRecoveryCategorySchema,
+  availableActions: z.array(implementationHandoffRecoveryActionSchema).max(8).default([]),
+  cleanupEligible: z.boolean().optional(),
+  conflictFiles: z.array(safeRepoPathSchema).max(25).default([]),
+  rebaseAbortStatus: implementationHandoffRebaseAbortStatusSchema.optional(),
+  summary: z.string().trim().min(1).max(600).optional(),
+  worktreeKey: z.string().trim().min(1).max(200).optional()
+}).strict();
 var implementationVerificationOutcomeSchema = z.enum(["verifiedImplemented", "partiallyImplemented", "notImplemented", "inconclusive", "verificationBlocked"]);
 var implementationVerificationStatusSchema = z.enum(["queued", "running", "completed", "failed", "blocked", "stale"]);
 var implementationProofStatusSchema = z.enum(["unverified", "verificationQueued", "verificationRunning", "verifiedImplemented", "partiallyImplemented", "notImplemented", "inconclusive", "verificationBlocked", "humanOverride"]);
@@ -183,6 +195,7 @@ var implementationHandoffSchema = z.object({
   cleanupStatus: implementationHandoffCleanupStatusSchema.optional(),
   cleanupMessage: z.string().trim().min(1).max(600).optional(),
   artifacts: implementationHandoffArtifactsSchema.optional(),
+  recovery: implementationHandoffRecoverySchema.optional(),
   message: z.string().trim().min(1).max(600).optional(),
   error: z.string().trim().min(1).max(1200).optional()
 }).strict();
@@ -905,7 +918,7 @@ var runnerCredentialItemSchema = baseItemSchema.extend({
   lastUsedAt: isoDateTimeSchema.optional(),
   status: z.enum(["active", "revoked"]).default("active")
 });
-var runnerCommandKindSchema = z.enum(["update", "restart", "remove"]);
+var runnerCommandKindSchema = z.enum(["update", "restart", "remove", "implementationHandoffRecovery"]);
 var runnerCommandStatusSchema = z.enum(["pending", "acknowledged", "running", "completed", "failed", "expired", "cancelled"]);
 var runnerCommandItemSchema = baseItemSchema.extend({
   type: z.literal("runnerCommand"),
@@ -915,6 +928,10 @@ var runnerCommandItemSchema = baseItemSchema.extend({
   status: runnerCommandStatusSchema,
   runnerId: z.string().min(1),
   repositoryLinkId: z.string().min(1),
+  workItemId: z.string().min(1).optional(),
+  handoffRecoveryAction: implementationHandoffRecoveryActionSchema.optional(),
+  executionBranch: z.string().min(1).optional(),
+  executionWorktreeKey: z.string().min(1).optional(),
   requestedByUserId: z.string().min(1),
   idempotencyKey: z.string().min(1),
   lastStatusIdempotencyKey: z.string().min(1).optional(),
@@ -5773,6 +5790,25 @@ var canonicalProjectContextCitationSources = /* @__PURE__ */ new Map([
   ["runnerstate", "runnerState"],
   ["mixed", "mixed"]
 ]);
+var canonicalProjectContextFreshnessValues = /* @__PURE__ */ new Map([
+  ["fresh", "fresh"],
+  ["current", "fresh"],
+  ["uptodate", "fresh"],
+  ["accurate", "fresh"],
+  ["stale", "stale"],
+  ["outdated", "stale"],
+  ["outofdate", "stale"],
+  ["old", "stale"],
+  ["historical", "stale"],
+  ["partial", "partial"],
+  ["partiallyfresh", "partial"],
+  ["incomplete", "partial"],
+  ["mixed", "partial"],
+  ["missing", "missing"],
+  ["absent", "missing"],
+  ["notfound", "missing"],
+  ["notpresent", "missing"]
+]);
 function createImplementationVerificationPrompt(workItem) {
   return [
     "# Amistio Implementation Verification",
@@ -6065,6 +6101,7 @@ function createProjectContextRefreshPrompt(workItem, context) {
     "- Use only these exact singular slice kind values: overview, architecture, domain, data, api, frontend, backend, cli, workflow, operations, security, testing, unknown.",
     "- Capture entities and relations that explain how the app is put together and where future work should look first.",
     "- Prefer summaries, repository-relative paths, short citations, tags, and freshness status over raw source excerpts.",
+    "- Use only these exact freshness values for coverage.status and slices[].freshness: fresh, stale, partial, missing.",
     "- Use only these exact citation source values: projectBrain, localSource, runnerState, mixed. Approved project-brain records use projectBrain, not approvedBrain.",
     "- Mark stale or missing areas explicitly instead of guessing.",
     "- Keep coverage.missingAreas entries concise noun phrases under 160 characters.",
@@ -6811,6 +6848,11 @@ function normalizeProjectContextRefreshEnums(value) {
     return value;
   }
   const normalized = { ...value };
+  if (isObjectRecord(normalized.coverage)) {
+    const normalizedCoverage = { ...normalized.coverage };
+    normalizedCoverage.status = normalizeProjectContextFreshness(normalizedCoverage.status);
+    normalized.coverage = normalizedCoverage;
+  }
   if (Array.isArray(normalized.slices)) {
     normalized.slices = normalized.slices.map((slice) => {
       if (!isObjectRecord(slice)) {
@@ -6818,6 +6860,7 @@ function normalizeProjectContextRefreshEnums(value) {
       }
       const normalizedSlice = { ...slice };
       normalizedSlice.kind = normalizeProjectContextSliceKind(slice.kind);
+      normalizedSlice.freshness = normalizeProjectContextFreshness(slice.freshness);
       return normalizedSlice;
     });
   }
@@ -6928,6 +6971,26 @@ function normalizeProjectContextSliceKind(value) {
   }
   return "unknown";
 }
+function normalizeProjectContextFreshness(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return value;
+  }
+  const direct = canonicalProjectContextFreshnessValues.get(normalizeEnumKey(trimmed));
+  if (direct) {
+    return direct;
+  }
+  for (const segment of trimmed.split(/[\/,|]+/)) {
+    const segmentFreshness = canonicalProjectContextFreshnessValues.get(normalizeEnumKey(segment));
+    if (segmentFreshness) {
+      return segmentFreshness;
+    }
+  }
+  return "partial";
+}
 function normalizeProjectContextRefreshBoundedText(value) {
   if (!isObjectRecord(value)) {
     return value;
@@ -7744,6 +7807,14 @@ async function prepareGitWorktreeIsolation(rootDir, workItem) {
   const preparedLocalEnvironmentFileCount = await prepareLocalWorktreeEnvironment(repoRoot, worktreePath);
   return { ...identity, baseRevision, worktreePath, ...preparedLocalEnvironmentFileCount ? { preparedLocalEnvironmentFileCount } : {} };
 }
+async function resolveExistingGitWorktreeIsolation(rootDir, workItem) {
+  const identity = resolveWorktreeIdentity(workItem);
+  const repoRoot = await gitOutput(rootDir, ["rev-parse", "--show-toplevel"]);
+  const baseRevision = await gitOutput(repoRoot, ["rev-parse", "HEAD"]);
+  const worktreePath = localWorktreePath(repoRoot, identity.worktreeKey);
+  await assertExistingWorktree(worktreePath, identity.branch);
+  return { ...identity, baseRevision, worktreePath };
+}
 function localWorktreePath(repoRoot, worktreeKey) {
   const repoName = path14.basename(repoRoot);
   const worktreeSlug = worktreeKey.split("/").filter(Boolean).pop() ?? "work";
@@ -7875,16 +7946,37 @@ async function completeImplementationHandoff(input) {
     }
     const unmergedFiles = await gitOutput2(run, input.worktreePath, ["diff", "--name-only", "--diff-filter=U"]);
     if (unmergedFiles.trim()) {
-      return blockedHandoff({ ...common, artifacts: artifactResult, message: "Implementation handoff is blocked because the worktree has unresolved merge conflicts." });
+      return blockedHandoff({
+        ...common,
+        artifacts: artifactResult,
+        message: "Implementation handoff is blocked because the worktree has unresolved merge conflicts.",
+        recovery: handoffRecovery(input, {
+          category: "unresolvedConflicts",
+          availableActions: ["requeueFreshAttempt", "keepForManualRepair", "exportHandoffDetails"],
+          cleanupEligible: false,
+          conflictFiles: safeRepoPaths(unmergedFiles),
+          rebaseAbortStatus: "notApplicable",
+          summary: "Resolve the local conflicts manually or requeue a fresh attempt after reviewing the preserved worktree."
+        })
+      });
     }
     const status = await gitOutput2(run, input.worktreePath, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
     if (!status) {
+      const cleanup2 = input.worktreeIsolation ? await cleanupWorktree(run, input) : { status: "notApplicable" };
       return {
         ...common,
         status: "noChanges",
-        cleanupStatus: "notApplicable",
+        cleanupStatus: cleanup2.status,
+        ...cleanup2.message ? { cleanupMessage: cleanup2.message } : {},
         artifacts: artifactResult,
-        message: "Local execution completed with no repository changes to hand off."
+        recovery: handoffRecovery(input, {
+          category: cleanup2.status === "completed" ? "noChangeCleaned" : cleanup2.status === "failed" ? "cleanupRetryAvailable" : "manualReview",
+          availableActions: cleanup2.status === "failed" ? ["retryCleanup", "markSupersededNoChanges", "exportHandoffDetails"] : ["markSupersededNoChanges", "exportHandoffDetails"],
+          cleanupEligible: cleanup2.status === "failed",
+          rebaseAbortStatus: "notApplicable",
+          summary: cleanup2.status === "completed" ? "No repository changes were found and the runner-created worktree was removed." : "No repository changes were found for handoff."
+        }),
+        message: cleanup2.status === "completed" ? "Local execution completed with no repository changes to hand off and the local worktree was cleaned up." : "Local execution completed with no repository changes to hand off."
       };
     }
     const remoteName = await resolveRemoteName(run, input.worktreePath);
@@ -7896,12 +7988,25 @@ async function completeImplementationHandoff(input) {
         provider,
         remoteName,
         artifacts: artifactResult,
-        message: "Automated pull request handoff currently requires a GitHub remote. Commit and push manually, or link a GitHub repository."
+        message: "Automated pull request handoff currently requires a GitHub remote. Commit and push manually, or link a GitHub repository.",
+        recovery: handoffRecovery(input, {
+          category: "nonGithubProvider",
+          availableActions: ["requeueFreshAttempt", "keepForManualRepair", "exportHandoffDetails"],
+          cleanupEligible: false,
+          rebaseAbortStatus: "notApplicable",
+          summary: "Automated retry is unavailable until this project uses a GitHub repository link."
+        })
       });
     }
     await gitOutput2(run, input.worktreePath, ["add", "-A"]);
     await gitOutput2(run, input.worktreePath, ["commit", "-m", commitSubject(input.workItem), "-m", commitBody(input)]);
-    await rebaseBranchFromRemoteBase(run, input.worktreePath, { baseBranch, remoteName });
+    const preRebaseCommitSha = await gitOutput2(run, input.worktreePath, ["rev-parse", "HEAD"]);
+    await fetchRemoteBase(run, input.worktreePath, { baseBranch, remoteName });
+    try {
+      await rebaseBranchFromRemoteBase(run, input.worktreePath);
+    } catch (error) {
+      return blockedRebaseHandoff({ artifactResult, baseBranch, error, headBranch, input, preRebaseCommitSha, remoteName, run });
+    }
     const commitSha = await gitOutput2(run, input.worktreePath, ["rev-parse", "HEAD"]);
     await gitOutput2(run, input.worktreePath, ["push", "--set-upstream", remoteName, headBranch]);
     const pullRequest = await ensureGithubPullRequest(run, input.worktreePath, { artifacts: artifactResult, baseBranch, headBranch, workItem: input.workItem, ...input.verificationSummary ? { verificationSummary: input.verificationSummary } : {} });
@@ -7917,13 +8022,60 @@ async function completeImplementationHandoff(input) {
       prUrl: pullRequest.url,
       cleanupStatus: cleanup.status,
       ...cleanup.message ? { cleanupMessage: cleanup.message } : {},
+      ...cleanup.status === "failed" ? {
+        recovery: handoffRecovery(input, {
+          category: "cleanupRetryAvailable",
+          availableActions: ["retryCleanup", "exportHandoffDetails"],
+          cleanupEligible: true,
+          rebaseAbortStatus: "notApplicable",
+          summary: "The pull request is durable, but local worktree cleanup needs another runner-local attempt."
+        })
+      } : {},
       artifacts: artifactResult,
       message: cleanup.status === "completed" ? "GitHub pull request is ready for review and the local worktree was cleaned up." : "GitHub pull request is ready for review; local worktree cleanup needs attention."
     };
   } catch (error) {
-    return blockedHandoff({ ...common, message: "Implementation handoff is blocked and the local worktree was preserved for recovery.", error: safeErrorMessage(error) });
+    return blockedHandoff({
+      ...common,
+      message: "Implementation handoff is blocked and the local worktree was preserved for recovery.",
+      error: safeErrorMessage(error),
+      recovery: handoffRecovery(input, {
+        category: "providerBlocked",
+        availableActions: ["retryHandoff", "requeueFreshAttempt", "keepForManualRepair", "exportHandoffDetails"],
+        cleanupEligible: false,
+        rebaseAbortStatus: "notAttempted",
+        summary: "Retry handoff after fixing local Git, remote, or GitHub CLI access; requeue only if a fresh attempt is preferable."
+      })
+    });
   }
 }
+async function cleanupImplementationWorktree(input) {
+  const run = input.commandRunner ?? defaultCommandRunner;
+  return cleanupWorktree(run, input);
+}
+async function blockedRebaseHandoff(input) {
+  const conflictFiles = await safeConflictFiles(input.run, input.input.worktreePath);
+  const rebaseAbortStatus = await abortRebaseForRecovery(input.run, input.input.worktreePath, input.preRebaseCommitSha);
+  return blockedHandoff({
+    provider: "github",
+    status: "blocked",
+    baseBranch: input.baseBranch,
+    headBranch: input.headBranch,
+    remoteName: input.remoteName,
+    commitSha: input.preRebaseCommitSha,
+    artifacts: input.artifactResult,
+    message: rebaseAbortStatus === "succeeded" ? "Implementation handoff hit a rebase conflict. Conflict files were captured and the branch was restored for recovery." : "Implementation handoff hit a rebase conflict and the local worktree was preserved for recovery.",
+    error: safeErrorMessage(input.error),
+    recovery: handoffRecovery(input.input, {
+      category: "rebaseConflict",
+      availableActions: ["retryHandoff", "requeueFreshAttempt", "keepForManualRepair", "exportHandoffDetails"],
+      cleanupEligible: false,
+      conflictFiles,
+      rebaseAbortStatus,
+      summary: rebaseAbortStatus === "succeeded" ? "The failed rebase was aborted after conflict metadata was captured, so the implementation branch can be retried or reviewed manually." : "The failed rebase could not be safely aborted; review the preserved worktree before retrying."
+    })
+  });
+}
 async function materializeApprovedArtifacts(input) {
   const { selected: artifacts, skipped } = selectApprovedWorkArtifacts(input.workItem, input.approvedArtifacts ?? []);
   if (!artifacts.length) {
@@ -7941,6 +8093,38 @@ async function materializeApprovedArtifacts(input) {
     blocked: materialized.conflicts.map((conflict) => artifactStatus(findArtifactByPath(artifacts, conflictRepoPath(conflict)), "blocked", conflict))
   };
 }
+function handoffRecovery(input, recovery) {
+  const worktreeKey = input.worktreeIsolation?.worktreeKey ?? input.workItem.executionWorktreeKey;
+  return {
+    ...recovery,
+    conflictFiles: recovery.conflictFiles ?? [],
+    ...worktreeKey ? { worktreeKey } : {}
+  };
+}
+async function safeConflictFiles(run, cwd) {
+  const unmergedFiles = await gitOutput2(run, cwd, ["diff", "--name-only", "--diff-filter=U"]).catch(() => "");
+  return safeRepoPaths(unmergedFiles);
+}
+async function abortRebaseForRecovery(run, cwd, expectedHead) {
+  try {
+    await gitOutput2(run, cwd, ["rebase", "--abort"]);
+    const currentHead = await gitOutput2(run, cwd, ["rev-parse", "HEAD"]);
+    return currentHead === expectedHead ? "succeeded" : "failed";
+  } catch {
+    return "failed";
+  }
+}
+function safeRepoPaths(output) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of output.split(/\0|\r?\n/g)) {
+    const repoPath = value.trim();
+    if (!repoPath || repoPath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(repoPath) || repoPath.split(/[\\/]+/).includes("..")) {
+      continue;
+    }
+    seen.add(repoPath);
+  }
+  return [...seen].slice(0, 25);
+}
 function selectApprovedWorkArtifacts(workItem, documents) {
   const draftId = workItem.generatedDraftId;
   const explicitDocumentIds = new Set([workItem.reviewDocumentId, workItem.impactDocumentId].filter((value) => Boolean(value)));
@@ -8017,8 +8201,10 @@ async function resolveRemoteName(run, cwd) {
   }
   return remotes.includes("origin") ? "origin" : remotes[0];
 }
-async function rebaseBranchFromRemoteBase(run, cwd, input) {
+async function fetchRemoteBase(run, cwd, input) {
   await gitOutput2(run, cwd, ["fetch", input.remoteName, input.baseBranch]);
+}
+async function rebaseBranchFromRemoteBase(run, cwd) {
   await gitOutput2(run, cwd, ["rebase", "FETCH_HEAD"]);
 }
 async function gitOutput2(run, cwd, args) {
@@ -9671,7 +9857,7 @@ async function runPendingRunnerCommand(apiClient, context, heartbeatMetadata) {
   }
   await updateRunnerCommandStatus(apiClient, context, command, "acknowledged", "Command acknowledged by local runner.");
   await updateRunnerCommandStatus(apiClient, context, command, "running", `Running ${runnerCommandLabel(command.commandKind)} command.`);
-  const result = await executeRunnerCommand(command, context);
+  const result = await executeRunnerCommand(apiClient, command, context);
   await updateRunnerCommandStatus(apiClient, context, command, result.succeeded ? "completed" : "failed", result.message, result.error);
   if (command.commandKind === "remove" && result.succeeded) {
     await new LocalCredentialStore().delete(credentialKey(context.accountId, context.projectId, context.repositoryLinkId));
@@ -9692,18 +9878,100 @@ async function updateRunnerCommandStatus(apiClient, context, command, status, me
   });
   return result.command;
 }
-async function executeRunnerCommand(command, context) {
+async function executeRunnerCommand(apiClient, command, context) {
   if (command.commandKind === "remove") {
     return { succeeded: true, stopRunner: true, message: "Runner credential revoked. This local runner will stop after removing its stored credential." };
   }
   if (command.commandKind === "restart") {
     return restartCurrentRunner(context);
   }
+  if (command.commandKind === "implementationHandoffRecovery") {
+    return executeImplementationHandoffRecoveryCommand(apiClient, command, context);
+  }
   return runOfficialCliUpdateWithRuntimeRefresh({
     mode: currentRunnerMode(),
     restartBackgroundRunner: () => restartCurrentRunner(context, { useUpdatedCliExecutable: true })
   });
 }
+async function executeImplementationHandoffRecoveryCommand(apiClient, command, context) {
+  if (!command.workItemId || !command.handoffRecoveryAction) {
+    return { succeeded: false, message: "Handoff recovery command is missing a scoped work item or action." };
+  }
+  const workItem = await findRecoveryWorkItem(apiClient, context.projectId, command.workItemId);
+  if (!workItem) {
+    return { succeeded: false, message: "Handoff recovery work item was not found." };
+  }
+  if (workItem.repositoryLinkId && workItem.repositoryLinkId !== context.repositoryLinkId) {
+    return { succeeded: false, message: "Handoff recovery command is not scoped to this repository link." };
+  }
+  if (!workItem.implementationHandoff?.recovery?.availableActions.includes(command.handoffRecoveryAction)) {
+    return { succeeded: false, message: "Handoff recovery action is no longer available for this work item." };
+  }
+  try {
+    if (command.handoffRecoveryAction === "retryHandoff") {
+      return retryImplementationHandoff(apiClient, context, workItem);
+    }
+    if (isCleanupHandoffRecoveryAction(command.handoffRecoveryAction)) {
+      return retryImplementationHandoffCleanup(apiClient, context, workItem);
+    }
+    return { succeeded: false, message: "Handoff recovery action is not a runner-local command." };
+  } catch (error) {
+    return { succeeded: false, message: "Handoff recovery command failed locally.", error: errorMessage3(error) };
+  }
+}
+async function retryImplementationHandoff(apiClient, context, workItem) {
+  const worktreeIsolation = await resolveExistingGitWorktreeIsolation(context.root, workItem);
+  const [{ repositoryLinks }, { documents }] = await Promise.all([apiClient.listRepositoryLinks(context.projectId), apiClient.listBrainDocuments(context.projectId)]);
+  const repositoryLink = repositoryLinks.find((link) => link.repositoryLinkId === context.repositoryLinkId);
+  const handoff = await completeImplementationHandoff({ approvedArtifacts: documents, primaryRepoRoot: context.root, ...repositoryLink ? { repositoryLink } : {}, workItem, worktreeIsolation, worktreePath: worktreeIsolation.worktreePath });
+  await submitRecoveredHandoff(apiClient, context, workItem, handoff, "retryHandoff");
+  return {
+    succeeded: handoff.status === "prReady" || handoff.status === "noChanges",
+    message: handoff.message ?? handoffStatusMessage(handoff),
+    ...handoff.error ? { error: handoff.error } : {}
+  };
+}
+async function retryImplementationHandoffCleanup(apiClient, context, workItem) {
+  const worktreeIsolation = await resolveExistingGitWorktreeIsolation(context.root, workItem);
+  const cleanup = await cleanupImplementationWorktree({ primaryRepoRoot: context.root, worktreePath: worktreeIsolation.worktreePath });
+  const previousHandoff = workItem.implementationHandoff;
+  const handoff = {
+    ...previousHandoff ?? { status: "noChanges" },
+    cleanupStatus: cleanup.status,
+    ...cleanup.message ? { cleanupMessage: cleanup.message } : {},
+    message: cleanup.status === "completed" ? "Local handoff worktree cleanup completed." : "Local handoff worktree cleanup still needs attention.",
+    ...cleanup.status === "failed" && previousHandoff?.recovery ? { recovery: previousHandoff.recovery } : {}
+  };
+  await submitRecoveredHandoff(apiClient, context, workItem, handoff, "retryCleanup");
+  return { succeeded: cleanup.status === "completed", message: handoff.message ?? handoffStatusMessage(handoff), ...cleanup.message ? { error: cleanup.message } : {} };
+}
+async function findRecoveryWorkItem(apiClient, projectId, workItemId) {
+  const { workItems } = await apiClient.listWorkItems(projectId);
+  return workItems.find((item) => item.workItemId === workItemId);
+}
+async function submitRecoveredHandoff(apiClient, context, workItem, handoff, action) {
+  await apiClient.updateWorkStatus(context.projectId, workItem.workItemId, recoveredHandoffWorkStatus(handoff), `handoff_recovery_${workItem.workItemId}_${action}_${randomUUID()}`, context.runnerId, {
+    implementationHandoff: handoff,
+    ...handoff.message ? { message: handoff.message } : {},
+    ...workItem.controllingAdrId ? { controllingAdrId: workItem.controllingAdrId } : {},
+    ...workItem.implementationScopeId ? { implementationScopeId: workItem.implementationScopeId } : {},
+    ...workItem.executionBranch ? { executionBranch: workItem.executionBranch } : {},
+    ...workItem.executionWorktreeKey ? { executionWorktreeKey: workItem.executionWorktreeKey } : {},
+    ...workItem.isolationMode ? { isolationMode: workItem.isolationMode } : {},
+    ...workItem.repositoryLockId ? { repositoryLockId: workItem.repositoryLockId } : {}
+  });
+}
+function recoveredHandoffWorkStatus(handoff) {
+  return handoff.status === "prReady" || handoff.status === "noChanges" ? "completed" : "blocked";
+}
+function handoffStatusMessage(handoff) {
+  if (handoff.status === "prReady") return "GitHub pull request is ready for review.";
+  if (handoff.status === "noChanges") return "No repository changes were found.";
+  return "Implementation handoff remains blocked.";
+}
+function isCleanupHandoffRecoveryAction(action) {
+  return action === "retryCleanup" || action === "cleanNoChangeWorktree";
+}
 async function restartCurrentRunner(context, options = {}) {
   if (currentRunnerMode() !== "background") {
     return { succeeded: false, message: "Foreground runners cannot be restarted remotely. Stop and start the local command manually." };
@@ -9722,6 +9990,7 @@ async function restartCurrentRunner(context, options = {}) {
 function runnerCommandLabel(commandKind) {
   if (commandKind === "update") return "update";
   if (commandKind === "restart") return "restart";
+  if (commandKind === "implementationHandoffRecovery") return "handoff recovery";
   return "remove";
 }
 async function replayPendingBrainGenerationFinalizations({ accountId, apiClient, projectId, repositoryLinkId, runnerId }) {