@moretea-labs/forge 1.7.2 → 1.8.1

package/src/cli/controller/execution-policy.ts

@@ -7,22 +7,13 @@ export type TaskExecutionClass =
   | 'high_risk_change'
   | 'destructive_change';
 
-export type ApprovalRequirement = 'auto' | 'confirm' | 'manual-only';
+export type ApprovalRequirement = 'auto' | 'manual-only';
 
 export interface TaskExecutionPolicy {
   risk: TaskRisk;
   executionClass: TaskExecutionClass;
   approval: ApprovalRequirement;
-  requiresScopedPaths: boolean;
-  requiresDiffEvidence: boolean;
-  requiresAnyVerificationEvidence: boolean;
-  requiresAcceptanceEvidence: boolean;
-  requiresHumanAcceptance: boolean;
-  autoRunDeclaredChecks: boolean;
-  autoCompleteAfterSuccessfulRun: boolean;
   warnings: string[];
-  sensitivePaths: string[];
-  destructiveSignals: string[];
 }
 
 export interface CompletionReceiptExpectation {
@@ -140,139 +131,39 @@ export function completionEvidenceComplete(
     && cleanup.noDirtyDiff);
 }
 
-const READ_ONLY_INTENT = /\b(read|inspect|analy[sz]e|audit|review|summari[sz]e|explain|diagnose|investigate|search|find|report|compare|trace)\b|只读|分析|审计|检查|排查|调查|搜索|查找|报告|对比|梳理/i;
-const CHANGE_INTENT = /\b(edit|change|modify|implement|fix|refactor|write|create|update|migrate|replace|delete|remove)\b|修改|实现|修复|重构|写入|创建|更新|迁移|替换|删除/i;
-const DESTRUCTIVE_INTENT = /\b(rm\s+-rf|reset\s+--hard|force[- ]?push|rewrite\s+history|drop\s+(table|database)|truncate\s+table|delete\s+all|purge|destroy|irreversible|production\s+data|prod\s+data)\b|强制推送|重写历史|清空数据库|删除全部|不可逆|生产数据/i;
-const SENSITIVE_PATH_PATTERNS: Array<[RegExp, string]> = [
-  [/(^|\/)\.github\/workflows(\/|$)/i, 'CI workflow'],
-  [/(^|\/)(deploy|infra|terraform|k8s|helm)(\/|$)/i, 'deployment or infrastructure'],
-  [/(^|\/)(migrations?|schema|database|db)(\/|$)/i, 'database or migration'],
-  [/(^|\/)(auth|security|permissions?|billing|payments?)(\/|$)/i, 'security or billing'],
-  [/(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lock)$/i, 'dependency lockfile'],
-];
-
 function normalizeRisk(value: TaskRisk | undefined): TaskRisk {
   return value ?? 'medium';
 }
 
-function sensitivePathLabels(paths: readonly string[]): string[] {
-  const labels = new Set<string>();
-  for (const path of paths) {
-    for (const [pattern, label] of SENSITIVE_PATH_PATTERNS) {
-      if (pattern.test(path)) labels.add(label);
-    }
-  }
-  return [...labels];
-}
-
-export function classifyTaskExecution(task: Pick<ControllerTask, 'objective' | 'title' | 'risk' | 'allowedPaths' | 'forbiddenPaths'>): {
+/**
+ * Legacy Task risk is explicit model-authored metadata only. Forge does not infer
+ * risk or destructive authority from objective text, path names, or keywords.
+ */
+export function classifyTaskExecution(task: Pick<ControllerTask, 'risk'>): {
   risk: TaskRisk;
   executionClass: TaskExecutionClass;
-  sensitivePaths: string[];
-  destructiveSignals: string[];
 } {
-  const text = `${task.title}\n${task.objective}`;
-  const paths = [...task.allowedPaths, ...task.forbiddenPaths];
-  const sensitivePaths = sensitivePathLabels(paths);
-  const destructiveSignals: string[] = [];
-  if (DESTRUCTIVE_INTENT.test(text)) destructiveSignals.push('destructive intent');
-  if (paths.some((path) => /(^|\/)(migrations?|database|db|prod|production)(\/|$)/i.test(path)) && /delete|drop|truncate|purge|清空|删除/i.test(text)) {
-    destructiveSignals.push('high-risk data mutation');
-  }
-
-  let risk = normalizeRisk(task.risk);
-  if (destructiveSignals.length > 0) risk = 'destructive';
-  else if (risk !== 'destructive' && sensitivePaths.length > 0 && (risk === 'readonly' || risk === 'low')) risk = 'medium';
-
-  if (risk === 'readonly') return { risk, executionClass: 'read_only', sensitivePaths, destructiveSignals };
-  if (risk === 'destructive') return { risk, executionClass: 'destructive_change', sensitivePaths, destructiveSignals };
-  if (risk === 'high') return { risk, executionClass: 'high_risk_change', sensitivePaths, destructiveSignals };
-  if (risk === 'medium') return { risk, executionClass: 'medium_risk_change', sensitivePaths, destructiveSignals };
-
-  const inferredReadOnly = READ_ONLY_INTENT.test(text) && !CHANGE_INTENT.test(text) && task.allowedPaths.length === 0;
-  return {
-    risk: inferredReadOnly ? 'readonly' : risk,
-    executionClass: inferredReadOnly ? 'read_only' : 'low_risk_change',
-    sensitivePaths,
-    destructiveSignals,
-  };
+  const risk = normalizeRisk(task.risk);
+  if (risk === 'readonly') return { risk, executionClass: 'read_only' };
+  if (risk === 'destructive') return { risk, executionClass: 'destructive_change' };
+  if (risk === 'high') return { risk, executionClass: 'high_risk_change' };
+  if (risk === 'medium') return { risk, executionClass: 'medium_risk_change' };
+  return { risk, executionClass: 'low_risk_change' };
 }
 
-export function taskExecutionPolicy(task: Pick<ControllerTask, 'objective' | 'title' | 'risk' | 'allowedPaths' | 'forbiddenPaths' | 'checks' | 'acceptanceCriteria'>): TaskExecutionPolicy {
+export function taskExecutionPolicy(task: Pick<ControllerTask, 'risk' | 'allowedPaths' | 'checks' | 'acceptanceCriteria'>): TaskExecutionPolicy {
   const classification = classifyTaskExecution(task);
   const warnings: string[] = [];
-  if (task.checks.length === 0) warnings.push('No named checks are declared; launch remains allowed and completion will rely on Run or reported command evidence.');
+  if (task.checks.length === 0) warnings.push('No named checks are declared; completion relies on concrete execution or delivery evidence when present.');
   if (task.acceptanceCriteria.length === 0) warnings.push('No Task-level acceptance criteria are declared.');
-  if (task.allowedPaths.length === 0 && classification.executionClass !== 'read_only') warnings.push('No allowed path scope is declared; runtime path and conflict guards remain authoritative.');
-
-  switch (classification.executionClass) {
-    case 'read_only':
-      return {
-        ...classification,
-        approval: 'auto',
-        requiresScopedPaths: false,
-        requiresDiffEvidence: false,
-        requiresAnyVerificationEvidence: false,
-        requiresAcceptanceEvidence: false,
-        requiresHumanAcceptance: false,
-        autoRunDeclaredChecks: false,
-        autoCompleteAfterSuccessfulRun: true,
-        warnings,
-      };
-    case 'low_risk_change':
-      return {
-        ...classification,
-        approval: 'auto',
-        requiresScopedPaths: false,
-        requiresDiffEvidence: false,
-        requiresAnyVerificationEvidence: false,
-        requiresAcceptanceEvidence: false,
-        requiresHumanAcceptance: false,
-        autoRunDeclaredChecks: task.checks.length > 0,
-        autoCompleteAfterSuccessfulRun: true,
-        warnings,
-      };
-    case 'medium_risk_change':
-      return {
-        ...classification,
-        approval: 'auto',
-        requiresScopedPaths: false,
-        requiresDiffEvidence: false,
-        requiresAnyVerificationEvidence: task.checks.length > 0,
-        requiresAcceptanceEvidence: task.acceptanceCriteria.length > 0,
-        requiresHumanAcceptance: false,
-        autoRunDeclaredChecks: task.checks.length > 0,
-        autoCompleteAfterSuccessfulRun: true,
-        warnings,
-      };
-    case 'high_risk_change':
-      return {
-        ...classification,
-        // V8 treats risk as execution metadata, not as a local approval gate.
-        approval: 'auto',
-        requiresScopedPaths: false,
-        requiresDiffEvidence: true,
-        requiresAnyVerificationEvidence: task.checks.length > 0,
-        requiresAcceptanceEvidence: task.acceptanceCriteria.length > 0,
-        requiresHumanAcceptance: true,
-        autoRunDeclaredChecks: task.checks.length > 0,
-        autoCompleteAfterSuccessfulRun: false,
-        warnings,
-      };
-    case 'destructive_change':
-      return {
-        ...classification,
-        approval: 'manual-only',
-        requiresScopedPaths: true,
-        requiresDiffEvidence: true,
-        requiresAnyVerificationEvidence: true,
-        requiresAcceptanceEvidence: true,
-        requiresHumanAcceptance: true,
-        autoRunDeclaredChecks: task.checks.length > 0,
-        autoCompleteAfterSuccessfulRun: false,
-        warnings,
-      };
-  }
+  if (task.allowedPaths.length === 0 && classification.executionClass !== 'read_only') warnings.push('No allowed path scope is declared; concrete runtime path and conflict guards remain authoritative.');
+  return {
+    ...classification,
+    // Only an explicitly authored destructive risk retains a legacy Task-level
+    // authorization boundary. Ordinary risk classes are descriptive metadata.
+    approval: classification.risk === 'destructive' ? 'manual-only' : 'auto',
+    warnings,
+  };
 }
 
 
@@ -336,7 +227,7 @@ export function taskAcceptanceOutcome(result: TaskAcceptanceResult | undefined):
   return result.ok ? 'passed' : 'failed';
 }
 
-export function verificationEvidencePassed(task: Pick<ControllerTask, 'checks' | 'acceptanceCriteria'>, verification: TaskVerification | undefined, policy: TaskExecutionPolicy): {
+export function verificationEvidencePassed(task: Pick<ControllerTask, 'checks' | 'acceptanceCriteria'>, verification: TaskVerification | undefined): {
   status: 'passed' | 'failed' | 'incomplete';
   ok: boolean;
   checksOk: boolean;
@@ -344,49 +235,41 @@ export function verificationEvidencePassed(task: Pick<ControllerTask, 'checks' |
   hasEvidence: boolean;
   reasons: string[];
 } {
+  const checksRequired = task.checks.length > 0;
+  const acceptanceRequired = task.acceptanceCriteria.length > 0;
   if (!verification) {
-    const ok = !policy.requiresAnyVerificationEvidence && !policy.requiresAcceptanceEvidence && !policy.requiresDiffEvidence;
+    const ok = !checksRequired && !acceptanceRequired;
     return {
       status: ok ? 'passed' : 'incomplete',
       ok,
-      checksOk: !policy.requiresAnyVerificationEvidence,
-      acceptanceOk: !policy.requiresAcceptanceEvidence,
+      checksOk: !checksRequired,
+      acceptanceOk: !acceptanceRequired,
       hasEvidence: false,
-      reasons: ok ? [] : ['No persisted verification evidence.'],
+      reasons: ok ? [] : ['Explicitly declared check or acceptance evidence is missing.'],
     };
   }
   const reportedCommands = verification.commandEvidence ?? [];
   const hasEvidence = verification.checkResults.length > 0 || reportedCommands.length > 0 || Boolean(verification.runId);
   const evidenceFailed = verification.checkResults.some((entry) => !entry.ok)
     || reportedCommands.some((entry) => !entry.ok);
-  const namedChecksComplete = task.checks.length === 0 || task.checks.every((checkId) =>
+  const namedChecksComplete = !checksRequired || task.checks.every((checkId) =>
     verification.checkResults.some((entry) => entry.checkId === checkId && entry.ok),
   );
-  const declaredChecksRequired = policy.autoRunDeclaredChecks && task.checks.length > 0;
-  const checksOk = !evidenceFailed && (declaredChecksRequired
-    ? namedChecksComplete
-    : policy.requiresAnyVerificationEvidence
-      ? hasEvidence
-      : true);
+  const checksOk = !evidenceFailed && namedChecksComplete;
 
   const acceptanceOutcomes = task.acceptanceCriteria.map((criterion) => taskAcceptanceOutcome(
     verification.acceptanceResults.find((entry) => entry.criterion === criterion),
   ));
-  const acceptanceFailed = policy.requiresAcceptanceEvidence && acceptanceOutcomes.some((outcome) => outcome === 'failed');
-  const acceptanceComplete = !policy.requiresAcceptanceEvidence
-    || task.acceptanceCriteria.length === 0
-    || acceptanceOutcomes.every((outcome) => outcome === 'passed');
+  const acceptanceFailed = acceptanceOutcomes.some((outcome) => outcome === 'failed');
+  const acceptanceComplete = !acceptanceRequired || acceptanceOutcomes.every((outcome) => outcome === 'passed');
   const acceptanceOk = acceptanceComplete && !acceptanceFailed;
-  const diffOk = !policy.requiresDiffEvidence || Boolean(verification.reviewedDiffHash || verification.integratedRevision);
   const failed = evidenceFailed || acceptanceFailed;
-  const complete = checksOk && acceptanceOk && diffOk;
+  const complete = checksOk && acceptanceOk;
   const status = failed ? 'failed' : complete ? 'passed' : 'incomplete';
   const reasons: string[] = [];
   if (evidenceFailed) reasons.push('One or more executed checks or reported commands failed.');
-  else if (!checksOk) reasons.push('Required named checks or equivalent command evidence are missing.');
+  else if (!checksOk) reasons.push('One or more explicitly declared checks are missing.');
   if (acceptanceFailed) reasons.push('One or more acceptance criteria explicitly failed.');
-  else if (!acceptanceOk) reasons.push('One or more acceptance criteria are missing or not evaluated.');
-  if (policy.requiresAnyVerificationEvidence && !hasEvidence) reasons.push('This risk class requires persisted verification evidence.');
-  if (!diffOk) reasons.push('This risk class requires reviewed Diff or integrated revision evidence.');
+  else if (!acceptanceOk) reasons.push('One or more explicitly declared acceptance criteria are missing or not evaluated.');
   return { status, ok: status === 'passed', checksOk, acceptanceOk, hasEvidence, reasons };
 }

package/src/cli/controller/governance.ts

@@ -11,7 +11,7 @@ import {
 } from "./issue-store";
 import { clearCurrentIssue, loadControllerProjectState, saveControllerProjectState } from "./project-state";
 import type { ControllerIssue, ControllerTask } from "./types";
-import { completionEvidenceComplete, taskExecutionPolicy } from "./execution-policy";
+import { completionEvidenceComplete } from "./execution-policy";
 import { resolveCompletionTargetBranch } from "./completion-target";
 import { readIssueRunEvidence } from "./run-evidence";
 import { resolveEffectiveTaskState, resolveIssueTaskStates, resolveTaskDependencies, type EffectiveTaskState } from "./task-status-resolver";
@@ -200,8 +200,7 @@ function shouldAutoAcceptVerifiedTask(repoRoot: string, issue: ControllerIssue,
     taskId: task.id,
     targetBranch: resolveCompletionTargetBranch(repoRoot),
   })) return false;
-  const policy = taskExecutionPolicy(task);
-  return policy.autoCompleteAfterSuccessfulRun && !policy.requiresHumanAcceptance;
+  return task.acceptanceCriteria.length === 0;
 }
 
 function taskQueueItem(issue: ControllerIssue, task: ControllerTask, state: EffectiveTaskState): ExecutionQueueItem | undefined {

package/src/cli/controller/issue-store.ts

@@ -30,9 +30,6 @@ import { completionEvidenceComplete, executionScopesConflict, taskExecutionPolic
 import { resolveCompletionTargetBranch } from './completion-target';
 import { listControllerChecks } from './check-runner';
 import { normalizeCheckIds } from '../../runtime/control-plane/facade/check-normalization';
-import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
-import { projectControllerTaskFromWork } from '../../runtime/control-plane/facade/work-task-projection';
-import type { WorkContract } from '../../runtime/control-plane/facade/types';
 import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
 import { markControllerContextProjectionDirty } from '../../runtime/projections/controller-context';
 import {
@@ -239,32 +236,8 @@ export function getIssue(repoRoot: string, id: string): ControllerIssue {
   return issue;
 }
 
-function projectIssueTasksFromWork(repoRoot: string, issue: ControllerIssue): ControllerTask[] {
-  const controllerHomes = [...new Set([
-    resolveRepoPreferredControllerHome(repoRoot),
-    join(repoRoot, '_ops', 'controller-home'),
-  ])];
-  return issue.tasks.map((task) => {
-    if (!task.workId) return task;
-    const repoId = task.repoId ?? issue.repoId;
-    if (!repoId) return task.status === 'done' ? task : { ...task, status: 'launch_blocked' };
-    for (const controllerHome of controllerHomes) {
-      try {
-        const work = getWorkContract({ controllerHome, repoId }, task.workId);
-        if (!work || (work.issueId && work.issueId !== issue.id) || (work.taskId && work.taskId !== task.id)) continue;
-        if (work.status === 'completed' && !work.completionReceipt) continue;
-        return projectControllerTaskFromWork(task, work);
-      } catch {
-        // A compatibility read never manufactures state from an unavailable
-        // Work authority. Try the bounded repo-local authority, then close.
-      }
-    }
-    return task.status === 'done' ? task : { ...task, status: 'launch_blocked' };
-  });
-}
-
 export function projectIssueEffectiveView(repoRoot: string, issue: ControllerIssue) {
-  const projectedIssue = { ...issue, tasks: projectIssueTasksFromWork(repoRoot, issue) };
+  const projectedIssue = issue;
   const states = resolveIssueTaskStates(projectedIssue, readIssueRunEvidence(repoRoot, projectedIssue));
   return {
     ...projectedIssue,
@@ -509,12 +482,6 @@ function buildTaskReadiness(
     add('SUPERSEDED_DEPENDENCY_MIGRATION', 'warning', `Dependency ${migration.dependencyTaskId} was superseded by ${migration.replacementTaskIds.join(', ')}; replacement states are authoritative.`);
   }
 
-  if (policy.requiresScopedPaths && task.allowedPaths.length === 0) {
-    add('TASK_SCOPE_REQUIRED', 'blocker', `${policy.executionClass} requires an explicit allowed path scope.`);
-  }
-  if (policy.approval === 'confirm' && !options.approveRisk) {
-    add('RISK_CONFIRMATION_ADVISORY', 'warning', `${policy.executionClass} is marked for extra review, but local execution is not approval-gated in V8.`);
-  }
   if (policy.approval === 'manual-only' && !options.approveDestructive) {
     add('DESTRUCTIVE_APPROVAL_REQUIRED', 'blocker', 'A destructive or irreversible operation requires explicit authorization.');
   }
@@ -585,7 +552,7 @@ function refreshReadiness(repoRoot: string, issue: ControllerIssue): void {
     );
     task.status = nonApprovalBlockers.length === 0
       ? 'ready'
-      : nonApprovalBlockers.some((entry) => ['CANCELLED_DEPENDENCY', 'MISSING_DEPENDENCY', 'TASK_SCOPE_REQUIRED'].includes(entry.code))
+      : nonApprovalBlockers.some((entry) => ['CANCELLED_DEPENDENCY', 'MISSING_DEPENDENCY'].includes(entry.code))
         ? 'launch_blocked'
         : 'planned';
   }
@@ -942,63 +909,6 @@ export function bindTaskToWork(
   return written;
 }
 
-/**
- * Pre-cutover compatibility writer retained only for an unmigrated repository.
- * Once the SQLite migration marker exists this function fails before reading or
- * mutating legacy Issue/Task files; Work remains the sole execution writer.
- */
-export function projectTaskFromWork(
-  repoRoot: string,
-  issueIdValue: string,
-  taskId: string,
-  work: WorkContract,
-  input: { verification?: TaskVerification; note?: string } = {},
-): ControllerIssue {
-  assertLegacyIssueWritesAllowed(repoRoot, { id: issueIdValue });
-  const issue = getIssue(repoRoot, issueIdValue);
-  const task = issue.tasks.find((entry) => entry.id === taskId);
-  if (!task) throw new Error(`task not found: ${issueIdValue}/${taskId}`);
-  if (!task.workId || task.workId !== work.workId) {
-    throw new Error(`TASK_WORK_PROJECTION_IDENTITY_MISMATCH: ${task.workId ?? 'unbound'} != ${work.workId}`);
-  }
-  if (task.repoId && task.repoId !== work.repoId) {
-    throw new Error(`TASK_WORK_PROJECTION_REPO_MISMATCH: ${task.repoId} != ${work.repoId}`);
-  }
-  if (work.issueId && work.issueId !== issue.id) throw new Error(`TASK_WORK_PROJECTION_ISSUE_MISMATCH: ${work.issueId} != ${issue.id}`);
-  if (work.taskId && work.taskId !== task.id) throw new Error(`TASK_WORK_PROJECTION_TASK_MISMATCH: ${work.taskId} != ${task.id}`);
-  if (input.verification?.completionReceipt && input.verification.completionReceipt.receiptId !== work.completionReceipt?.receiptId) {
-    throw new Error('TASK_WORK_PROJECTION_RECEIPT_MISMATCH');
-  }
-  const projected = projectControllerTaskFromWork(task, work);
-  if (projected.status === 'done' && !work.completionReceipt) {
-    throw new Error('TASK_WORK_PROJECTION_COMPLETION_RECEIPT_REQUIRED');
-  }
-  task.repoId = work.repoId;
-  task.objective = projected.objective;
-  task.status = projected.status;
-  task.allowedPaths = projected.allowedPaths;
-  task.forbiddenPaths = projected.forbiddenPaths;
-  task.checks = projected.checks;
-  task.acceptanceCriteria = projected.acceptanceCriteria;
-  task.risk = projected.risk;
-  task.verification = input.verification ?? projected.verification;
-  if (input.note?.trim()) task.notes.push(input.note.trim());
-  task.updatedAt = new Date().toISOString();
-  issue.updatedAt = task.updatedAt;
-  refreshReadiness(repoRoot, issue);
-  const written = writeIssue(repoRoot, issue);
-  tryAppendControllerWorklogEvent(repoRoot, {
-    category: 'task',
-    action: 'task_projected_from_work',
-    summary: `Projected ${task.id} from Work ${work.workId} (${work.phase}/${work.status}).`,
-    issueId: issue.id,
-    taskId: task.id,
-    statusTo: task.status,
-    details: { workId: work.workId, phase: work.phase, workStatus: work.status, receiptId: work.completionReceipt?.receiptId },
-  });
-  return written;
-}
-
 function finding(code: string, level: 'blocker' | 'warning', message: string, taskId?: string): IssueReadinessFinding {
   return { code, level, message, taskId };
 }
@@ -1142,8 +1052,7 @@ function historicalTaskCompletionReceipt(
   verification: TaskVerification | undefined = task.verification,
 ): CompletionReceipt | undefined {
   if (!verification || taskHasActiveRun(repoRoot, task)) return undefined;
-  const policy = taskExecutionPolicy(task);
-  const outcome = verificationEvidencePassed(task, verification, policy);
+  const outcome = verificationEvidencePassed(task, verification);
   if (!outcome.ok) return undefined;
   const currentBranch = gitText(repoRoot, ['branch', '--show-current']);
   const targetBranch = verification.integrationEvidence?.targetBranch ?? resolveCompletionTargetBranch(repoRoot);
@@ -1259,13 +1168,9 @@ export function recordTaskVerification(
   if ((verification.commandEvidence ?? []).some((entry) => entry.command.length === 0 || entry.command.some((part) => !part.trim()))) {
     throw new Error('reported command evidence must contain a non-empty argv');
   }
-  const policy = taskExecutionPolicy(task);
-  if (policy.requiresScopedPaths && task.allowedPaths.length === 0) {
-    throw new Error(`${policy.executionClass} cannot be verified without an explicit allowed path scope`);
-  }
   const normalizedDeclaredChecks = normalizeCheckIds(task.checks, listControllerChecks(repoRoot));
   const verificationTask = { ...task, checks: normalizedDeclaredChecks.validCheckIds };
-  const outcome = verificationEvidencePassed(verificationTask, verification, policy);
+  const outcome = verificationEvidencePassed(verificationTask, verification);
   const successful = outcome.status === 'passed';
   if (doneEvidenceBackfill) {
     if (!successful) {

package/src/cli/controller/launch-agents.ts

@@ -178,26 +178,17 @@ export async function safeLaunchdHandoff(
     portChecks: [],
   };
 
-  // Step 1: Bootout old service
+  // Step 1: Request bootout of the old service. launchctl is an effectful
+  // helper, so a non-zero/timeout result is not proof that the bootout did not
+  // happen. Reconcile the physical launchd state below before deciding whether
+  // this handoff may proceed.
   const target = `${options.domain}/${options.label}`;
   const bootoutResult = run(['bootout', target]);
   diagnostics.bootoutResult = bootoutResult;
 
-  const bootoutClean = bootoutResult.ok || isBootoutAlreadyGone(bootoutResult);
-  if (!bootoutClean) {
-    // Bootout failed with unexpected error — collect diagnostics but don't proceed
-    return {
-      bootstrapAttempts: 0,
-      bootoutClean: false,
-      pidWaitClean: true,
-      portWaitClean: true,
-      plistInstalled: false,
-      serviceRegistered: false,
-      diagnostics,
-    };
-  }
-
-  // Step 2: Wait for service to disappear from launchd
+  // Step 2: Reconcile the bootout effect by waiting for the exact service to
+  // disappear from launchd. This is authoritative even when the helper returned
+  // an error after dispatching the effect.
   const bootoutDeadline = Date.now() + maxBootoutWaitMs;
   let serviceGone = false;
   while (Date.now() < bootoutDeadline) {
@@ -347,6 +338,45 @@ export interface RetiredConflictingLaunchAgent {
   backupPath: string;
 }
 
+export interface ExactLaunchAgentRetirementResult {
+  label: string;
+  plistPath: string;
+  serviceWasPresent: boolean;
+  plistWasPresent: boolean;
+  absentAfter: boolean;
+}
+
+export async function retireLaunchAgentExact(
+  input: { label: string; accountHome?: string },
+  dependencies: {
+    run?: LaunchctlCommandRunner;
+    bootout?: typeof bootoutLaunchAgentWithRetryV2;
+  } = {},
+): Promise<ExactLaunchAgentRetirementResult> {
+  const label = input.label.trim();
+  if (!label) throw new Error('FORGE_LAUNCH_AGENT_RETIRE_LABEL_REQUIRED');
+  const plistPath = launchAgentPath(label, input.accountHome);
+  const plistWasPresent = existsSync(plistPath);
+  const domain = currentUserLaunchdDomain();
+  const runner = dependencies.run ?? defaultRunner;
+  const target = `${domain}/${label}`;
+  const serviceWasPresent = runner(['print', target]).ok;
+  if (serviceWasPresent) {
+    const stopped = await (dependencies.bootout ?? bootoutLaunchAgentWithRetryV2)({
+      label,
+      plistPath,
+      domain,
+    });
+    if (!stopped.ok) {
+      throw new Error(`FORGE_LAUNCH_AGENT_EXACT_RETIRE_FAILED: ${label}: ${stopped.diagnostics.join('; ')}`);
+    }
+  }
+  rmSync(plistPath, { force: true });
+  const absentAfter = !runner(['print', target]).ok && !existsSync(plistPath);
+  if (!absentAfter) throw new Error(`FORGE_LAUNCH_AGENT_EXACT_RETIRE_VERIFY_FAILED: ${label}`);
+  return { label, plistPath, serviceWasPresent, plistWasPresent, absentAfter };
+}
+
 function decodePlistString(value: string): string {
   return value
     .replaceAll('&lt;', '<')
@@ -439,9 +469,20 @@ export async function bootstrapLaunchAgentWithRetryV2(
     },
     dependencies,
   );
-  const diagnostics = result.diagnostics.bootstrapResults.map((entry, index) =>
+  const diagnostics: string[] = [];
+  const bootout = result.diagnostics.bootoutResult;
+  if (bootout && !bootout.ok && !isBootoutAlreadyGone(bootout)) {
+    diagnostics.push(`bootout: ${(bootout.stderr || bootout.stdout || `exit=${bootout.exitCode}`).trim()}`);
+    if (result.bootoutClean) diagnostics.push('bootout-reconciled: exact launchd service is absent despite helper failure');
+  }
+  if (!result.bootoutClean && result.diagnostics.serviceProbeResults.length > 0) {
+    diagnostics.push('bootout-reconcile: exact launchd service remained registered after bounded observation');
+  }
+  if (!result.pidWaitClean) diagnostics.push('bootout-reconcile: prior service PID remained live after bounded observation');
+  if (!result.portWaitClean) diagnostics.push('bootout-reconcile: prior service port remained occupied after bounded observation');
+  diagnostics.push(...result.diagnostics.bootstrapResults.map((entry, index) =>
     `bootstrap-${index + 1}: ${(entry.stderr || entry.stdout || `exit=${entry.exitCode}`).trim()}`,
-  );
+  ));
   return {
     ok: result.bootoutClean && result.pidWaitClean && result.portWaitClean && result.serviceRegistered,
     attempts: result.bootstrapAttempts,