@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/standalone-recovery/release.ts

@@ -0,0 +1,241 @@
+import { createHash } from 'crypto';
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join, relative, resolve, sep } from 'path';
+import { writeJsonAtomic } from '../shared/json-files';
+
+export const RECOVERY_RELEASE_BINARIES = [
+  'forge-recovery',
+  'forge-recovery-gateway',
+  'forge-recovery-watchdog',
+] as const;
+
+export const RECOVERY_RELEASE_ROLE_CANARY_ARG = '--forge-release-role-canary';
+
+export type RecoveryReleaseBinary = (typeof RECOVERY_RELEASE_BINARIES)[number];
+export type RecoveryRuntimeRole = 'gateway' | 'watchdog';
+export interface RecoveryReleaseManifest {
+  schemaVersion: 1;
+  releaseRevision: string;
+  sourceCommit: string;
+  sourceRoot: string;
+  cleanWorkspace: boolean;
+  builtAt: string;
+  legacy?: boolean;
+  artifacts: Record<RecoveryReleaseBinary, { sha256: string }>;
+}
+
+export interface RecoveryReleaseDescriptor {
+  releasePath: string;
+  releaseRevision: string;
+  sourceCommit: string;
+  sourceRoot: string;
+  cleanWorkspace: boolean;
+  manifestSha256: string;
+  artifacts: RecoveryReleaseManifest['artifacts'];
+  legacy: boolean;
+}
+
+export interface RecoveryRuntimeIdentity {
+  schemaVersion: 1;
+  role: RecoveryRuntimeRole;
+  pid: number;
+  startedAt: string;
+  releasePath: string;
+  releaseRevision: string;
+  sourceCommit: string;
+  manifestSha256: string;
+}
+
+export function recoveryRoot(controllerHome: string): string {
+  const resolved = resolve(controllerHome);
+  let canonical = resolved;
+  try { canonical = realpathSync(resolved); } catch { /* fresh controller home */ }
+  return join(canonical, 'recovery');
+}
+
+export function recoveryReleasesRoot(controllerHome: string): string {
+  return join(recoveryRoot(controllerHome), 'releases');
+}
+
+export function recoveryCurrentPath(controllerHome: string): string {
+  return join(recoveryRoot(controllerHome), 'current');
+}
+
+export function recoveryPreviousPath(controllerHome: string): string {
+  return join(recoveryRoot(controllerHome), 'previous');
+}
+
+export function recoveryRuntimeStatePath(controllerHome: string, role: RecoveryRuntimeRole): string {
+  return join(recoveryRoot(controllerHome), 'state', `${role}-runtime.json`);
+}
+
+function fileSha256(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function manifestPath(releasePath: string): string {
+  return join(resolve(releasePath), 'manifest.json');
+}
+
+function releaseLink(path: string): string | undefined {
+  try {
+    if (!lstatSync(path).isSymbolicLink()) return undefined;
+    return resolve(dirname(path), readlinkSync(path));
+  } catch {
+    return undefined;
+  }
+}
+
+export function readRecoveryRelease(path: string | undefined): RecoveryReleaseDescriptor | undefined {
+  if (!path) return undefined;
+  try {
+    const releasePath = realpathSync(path);
+    const bytes = readFileSync(manifestPath(releasePath));
+    const parsed = JSON.parse(bytes.toString('utf8')) as Partial<RecoveryReleaseManifest>;
+    if (parsed.schemaVersion !== 1) return undefined;
+    if (typeof parsed.releaseRevision !== 'string' || !parsed.releaseRevision.trim()) return undefined;
+    if (typeof parsed.sourceCommit !== 'string' || !parsed.sourceCommit.trim()) return undefined;
+    if (typeof parsed.sourceRoot !== 'string' || !parsed.sourceRoot.trim()) return undefined;
+    if (typeof parsed.cleanWorkspace !== 'boolean') return undefined;
+    if (!parsed.artifacts || typeof parsed.artifacts !== 'object') return undefined;
+    const artifacts = {} as RecoveryReleaseManifest['artifacts'];
+    for (const binary of RECOVERY_RELEASE_BINARIES) {
+      const expected = parsed.artifacts[binary]?.sha256;
+      const binaryPath = join(releasePath, binary);
+      if (typeof expected !== 'string' || !existsSync(binaryPath) || fileSha256(binaryPath) !== expected) return undefined;
+      artifacts[binary] = { sha256: expected };
+    }
+    return {
+      releasePath,
+      releaseRevision: parsed.releaseRevision,
+      sourceCommit: parsed.sourceCommit,
+      sourceRoot: resolve(parsed.sourceRoot),
+      cleanWorkspace: parsed.cleanWorkspace,
+      manifestSha256: createHash('sha256').update(bytes).digest('hex'),
+      artifacts,
+      legacy: parsed.legacy === true,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readCurrentRecoveryRelease(controllerHome: string): RecoveryReleaseDescriptor | undefined {
+  return readRecoveryRelease(releaseLink(recoveryCurrentPath(controllerHome)));
+}
+
+export function readPreviousRecoveryRelease(controllerHome: string): RecoveryReleaseDescriptor | undefined {
+  return readRecoveryRelease(releaseLink(recoveryPreviousPath(controllerHome)));
+}
+
+function atomicReleaseLink(linkPath: string, releasePath: string): void {
+  mkdirSync(dirname(linkPath), { recursive: true, mode: 0o700 });
+  const temporary = `${linkPath}.${process.pid}.tmp`;
+  rmSync(temporary, { force: true });
+  symlinkSync(relative(dirname(linkPath), resolve(releasePath)), temporary, 'dir');
+  renameSync(temporary, linkPath);
+}
+
+function assertRecoveryReleaseContained(controllerHome: string, release: RecoveryReleaseDescriptor): void {
+  const releasesRoot = resolve(recoveryReleasesRoot(controllerHome));
+  if (!release.releasePath.startsWith(`${releasesRoot}${sep}`)) {
+    throw new Error(`RECOVERY_RELEASE_OUTSIDE_AUTHORITY: ${release.releasePath}`);
+  }
+}
+
+export function publishRecoveryRelease(
+  controllerHome: string,
+  releasePath: string,
+  previousPath?: string,
+): RecoveryReleaseDescriptor {
+  const release = readRecoveryRelease(releasePath);
+  if (!release) throw new Error('RECOVERY_RELEASE_INVALID');
+  assertRecoveryReleaseContained(controllerHome, release);
+  if (previousPath && resolve(previousPath) !== release.releasePath) {
+    const previous = readRecoveryRelease(previousPath);
+    if (!previous) throw new Error('RECOVERY_PREVIOUS_RELEASE_INVALID');
+    assertRecoveryReleaseContained(controllerHome, previous);
+    atomicReleaseLink(recoveryPreviousPath(controllerHome), previous.releasePath);
+  }
+  atomicReleaseLink(recoveryCurrentPath(controllerHome), release.releasePath);
+  return release;
+}
+
+export function publishRecoveryCompatibilityLinks(controllerHome: string): void {
+  const current = readCurrentRecoveryRelease(controllerHome);
+  if (!current) throw new Error('RECOVERY_CURRENT_RELEASE_INVALID');
+  assertRecoveryReleaseContained(controllerHome, current);
+  const binRoot = join(recoveryRoot(controllerHome), 'bin');
+  mkdirSync(binRoot, { recursive: true, mode: 0o700 });
+  for (const binary of RECOVERY_RELEASE_BINARIES) {
+    const destination = join(binRoot, binary);
+    const temporary = `${destination}.${process.pid}.tmp`;
+    rmSync(temporary, { force: true });
+    symlinkSync(join('..', 'current', binary), temporary);
+    renameSync(temporary, destination);
+  }
+}
+
+export function writeRecoveryReleaseManifest(releasePath: string, manifest: RecoveryReleaseManifest): void {
+  mkdirSync(releasePath, { recursive: true, mode: 0o700 });
+  const path = manifestPath(releasePath);
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  try { chmodSync(temporary, 0o600); } catch { /* best effort */ }
+  renameSync(temporary, path);
+}
+
+export function recoveryIdentityFromExecutable(executable = process.execPath): Omit<RecoveryRuntimeIdentity, 'role' | 'pid' | 'startedAt'> | undefined {
+  try {
+    const release = readRecoveryRelease(dirname(realpathSync(executable)));
+    if (!release) return undefined;
+    return {
+      schemaVersion: 1,
+      releasePath: release.releasePath,
+      releaseRevision: release.releaseRevision,
+      sourceCommit: release.sourceCommit,
+      manifestSha256: release.manifestSha256,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeRecoveryRuntimeIdentity(
+  controllerHome: string,
+  role: RecoveryRuntimeRole,
+  executable = process.execPath,
+): RecoveryRuntimeIdentity | undefined {
+  const release = recoveryIdentityFromExecutable(executable);
+  if (!release) return undefined;
+  const state: RecoveryRuntimeIdentity = {
+    ...release,
+    role,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  };
+  writeJsonAtomic(recoveryRuntimeStatePath(controllerHome, role), state);
+  return state;
+}
+
+export function readRecoveryRuntimeIdentity(controllerHome: string, role: RecoveryRuntimeRole): RecoveryRuntimeIdentity | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(recoveryRuntimeStatePath(controllerHome, role), 'utf8')) as RecoveryRuntimeIdentity;
+    if (parsed.schemaVersion !== 1 || parsed.role !== role || !Number.isInteger(parsed.pid)) return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/runtime/watchdog/workflow-watchdog.ts

@@ -0,0 +1,118 @@
+import { listActiveAgentJobSnapshots } from '../../cli/agent-jobs/job-manager';
+import { getLocalBridgeJobEventsSnapshot, listLocalBridgeJobSnapshots } from '../../cli/local-bridge/job-store';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { listExecutionJobs } from '../execution/jobs/store';
+import { collectRuntimePerformanceDiagnostics, type RuntimePerformanceDiagnostics } from '../diagnostics/performance';
+import { listSchedules } from '../workflow/schedules/store';
+
+const ACTIVE_AGENT_STATUSES = new Set(['queued', 'starting', 'running']);
+
+export interface WorkflowWatchdogFinding {
+  severity: 'info' | 'warning' | 'critical';
+  code: string;
+  message: string;
+  evidence?: Record<string, unknown>;
+  next: string;
+}
+
+export interface WorkflowWatchdogReport {
+  repoId: string;
+  generatedAt: string;
+  status: 'normal' | 'warning' | 'critical';
+  findings: WorkflowWatchdogFinding[];
+  performance: RuntimePerformanceDiagnostics;
+  queues: {
+    executionJobs: Record<string, number>;
+    localBridgeJobs: Record<string, number>;
+    agentJobs: Record<string, number>;
+    schedules: { total: number; enabled: number; disabled: number };
+  };
+  staleWork: Array<{ kind: 'execution' | 'local_bridge' | 'agent'; id: string; status: string; updatedAt?: string; ageMinutes?: number; summary?: string }>;
+  recoveryPlan: Array<{ action: string; risk: 'readonly' | 'workspace_write' | 'destructive'; reason: string; command?: string }>;
+  next: string[];
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function countBy<T extends { status?: string }>(items: T[]): Record<string, number> {
+  return items.reduce<Record<string, number>>((counts, item) => {
+    const status = item.status ?? 'unknown';
+    counts[status] = (counts[status] ?? 0) + 1;
+    return counts;
+  }, {});
+}
+
+function ageMinutes(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const ms = Date.now() - Date.parse(value);
+  if (!Number.isFinite(ms) || ms < 0) return undefined;
+  return Math.round(ms / 60000);
+}
+
+function maxSeverity(findings: WorkflowWatchdogFinding[]): WorkflowWatchdogReport['status'] {
+  if (findings.some((finding) => finding.severity === 'critical')) return 'critical';
+  if (findings.some((finding) => finding.severity === 'warning')) return 'warning';
+  return 'normal';
+}
+
+export function buildWorkflowWatchdogReport(controllerHome: string, repository: RepositoryRecord, input: { staleMinutes?: unknown; includeProcesses?: unknown } = {}): WorkflowWatchdogReport {
+  const staleThreshold = Math.max(10, Math.min(typeof input.staleMinutes === 'number' ? Math.trunc(input.staleMinutes) : 45, 24 * 60));
+  const executionJobs = listExecutionJobs(controllerHome, repository.repoId, 200);
+  const localJobs = listLocalBridgeJobSnapshots(repository.canonicalRoot, 200);
+  const agentJobs = listActiveAgentJobSnapshots(repository.canonicalRoot, 200);
+  const schedules = listSchedules(controllerHome, repository.repoId);
+  const activeJobIds = executionJobs.filter((job) => ['queued', 'running', 'dispatched'].includes(job.status)).map((job) => job.jobId);
+  const performance = collectRuntimePerformanceDiagnostics({
+    repoId: repository.repoId,
+    repoRoot: repository.canonicalRoot,
+    activeJobIds,
+    queueDepth: executionJobs.filter((job) => job.status === 'queued').length,
+    runningWorkers: executionJobs.filter((job) => job.status === 'running' || job.status === 'dispatched').length,
+    includeProcesses: input.includeProcesses !== false,
+    includeTempDirs: true,
+    cleanupPreview: true,
+  });
+  const staleWork = [
+    ...executionJobs.filter((job) => ['queued', 'running', 'dispatched'].includes(job.status) && (ageMinutes(job.updatedAt) ?? 0) >= staleThreshold)
+      .map((job) => ({ kind: 'execution' as const, id: job.jobId, status: job.status, updatedAt: job.updatedAt, ageMinutes: ageMinutes(job.updatedAt), summary: job.payload.operation })),
+    ...localJobs.filter((job) => ['approved', 'running', 'dispatched'].includes(job.status) && (ageMinutes(job.updatedAt) ?? 0) >= staleThreshold)
+      .map((job) => ({ kind: 'local_bridge' as const, id: job.jobId, status: job.status, updatedAt: job.updatedAt, ageMinutes: ageMinutes(job.updatedAt), summary: job.action })),
+    ...agentJobs.filter((job) => ACTIVE_AGENT_STATUSES.has(job.status) && (ageMinutes(job.progress?.lastActivityAt ?? job.lastHeartbeatAt ?? job.startedAt ?? job.createdAt) ?? 0) >= staleThreshold)
+      .map((job) => {
+        const updatedAt = job.progress?.lastActivityAt ?? job.lastHeartbeatAt ?? job.startedAt ?? job.createdAt;
+        return { kind: 'agent' as const, id: job.runId, status: job.status, updatedAt, ageMinutes: ageMinutes(updatedAt), summary: job.progress?.currentActivity ?? job.taskId ?? job.issueId };
+      }),
+  ];
+  const findings: WorkflowWatchdogFinding[] = [
+    ...performance.findings.map((finding) => ({ ...finding, next: finding.severity === 'critical' ? 'Run runtime_cleanup_preview, then decide whether to apply cleanup.' : 'Watch the next monitor tick before mutating runtime state.' })),
+    ...(staleWork.length > 0 ? [{ severity: 'warning' as const, code: 'STALE_WORK_ITEMS', message: `${staleWork.length} active work item(s) have not updated for ${staleThreshold}+ minutes.`, evidence: { staleWork }, next: 'Inspect get_job/get_local_job output and cancel or retry only after confirming the work is stale.' }] : []),
+    ...(schedules.filter((schedule) => schedule.enabled).length > 20 ? [{ severity: 'warning' as const, code: 'SCHEDULE_VOLUME_HIGH', message: 'Many enabled schedules can repeatedly wake the runtime.', evidence: { enabled: schedules.filter((schedule) => schedule.enabled).length }, next: 'Run schedule_dedupe_report and pause duplicate or obsolete schedules.' }] : []),
+  ];
+  const recoveryPlan = [
+    ...(staleWork.length > 0 ? [{ action: 'inspect_stale_work', risk: 'readonly' as const, reason: 'Read stalled job details before deciding to cancel.' }] : []),
+    ...(performance.cleanupPreview && (performance.cleanupPreview.safeToTerminate.length > 0 || performance.cleanupPreview.safeToRemoveTempEntries.length > 0) ? [{ action: 'runtime_cleanup_preview', risk: 'readonly' as const, reason: 'Cleanup candidates exist, but apply requires explicit authorization.' }] : []),
+    ...(schedules.length > 0 ? [{ action: 'schedule_dedupe_report', risk: 'readonly' as const, reason: 'Detect duplicate schedules before they generate repeated work.' }] : []),
+  ];
+  const localEventEvidence = staleWork.filter((entry) => entry.kind === 'local_bridge').slice(0, 3).flatMap((entry) => getLocalBridgeJobEventsSnapshot(repository.canonicalRoot, entry.id).slice(-3));
+  if (localEventEvidence.length > 0) {
+    findings.push({ severity: 'info', code: 'LOCAL_JOB_EVENT_EVIDENCE', message: 'Recent local bridge events were attached for stale-work inspection.', evidence: { events: localEventEvidence }, next: 'Use event timestamps to decide whether work is genuinely stuck.' });
+  }
+  return {
+    repoId: repository.repoId,
+    generatedAt: now(),
+    status: maxSeverity(findings),
+    findings,
+    performance,
+    queues: {
+      executionJobs: countBy(executionJobs),
+      localBridgeJobs: countBy(localJobs),
+      agentJobs: countBy(agentJobs),
+      schedules: { total: schedules.length, enabled: schedules.filter((schedule) => schedule.enabled).length, disabled: schedules.filter((schedule) => !schedule.enabled).length },
+    },
+    staleWork,
+    recoveryPlan,
+    next: [...new Set(findings.map((finding) => finding.next))],
+  };
+}

package/src/runtime/workflow/campaigns/cleanup.ts

@@ -0,0 +1,263 @@
+import { existsSync, realpathSync } from 'fs';
+import { resolve } from 'path';
+import { branchRef, validateBranchName } from '../../../cli/repositories/branch-name-policy';
+import { getRepository, setRepositoryCheckoutLifecycle } from '../../../cli/repositories/registry';
+import { runProcess } from '../../../effects/process-runner';
+import { cancelExecutionJob, findExecutionJob } from '../../execution/jobs/store';
+import type { Campaign, CampaignCleanupReport, CampaignCleanupResource } from './types';
+import { getCampaign, updateCampaign } from './store';
+
+type CleanupOptions = { targetBranch?: string };
+
+function now(): string { return new Date().toISOString(); }
+
+function git(root: string, args: string[]): { ok: boolean; stdout: string; stderr: string } {
+  const result = runProcess('git', ['-C', root, ...args], {
+    timeoutMs: 120_000,
+    maxOutputBytes: 256 * 1024,
+  });
+  return { ok: result.ok, stdout: result.stdout.trim(), stderr: result.stderr || result.error || '' };
+}
+
+function samePath(left: string, right: string): boolean {
+  try { return realpathSync(left) === realpathSync(right); }
+  catch { return resolve(left) === resolve(right); }
+}
+
+function cleanupManagedWorkspace(
+  controllerHome: string,
+  campaign: Campaign,
+  options?: CleanupOptions,
+): { resources: CampaignCleanupResource[]; leaks: string[] } {
+  const resources: CampaignCleanupResource[] = [];
+  const leaks: string[] = [];
+  const workspace = campaign.workspace;
+  if (!workspace.managed || workspace.mode !== 'isolated' || !workspace.root) return { resources, leaks };
+
+  const repository = getRepository(campaign.repoId, controllerHome);
+  const sourceRoot = repository.canonicalRoot;
+  const worktree = workspace.root;
+  const branch = workspace.branch ?? undefined;
+  let safeBranch: string | undefined;
+  if (branch) {
+    try {
+      safeBranch = validateBranchName(branch, { purpose: 'CAMPAIGN_WORKSPACE_BRANCH' });
+    } catch (error) {
+      const message = `Managed Campaign workspace has invalid branch metadata; preserved ${branch}.`;
+      resources.push({ kind: 'branch', id: branch, status: 'preserved', message });
+      leaks.push(message);
+      return { resources, leaks };
+    }
+  }
+  const baseRevision = workspace.baseRevision ?? undefined;
+
+  if (samePath(sourceRoot, worktree)) {
+    const message = 'Managed Campaign workspace resolved to the repository root; refusing cleanup.';
+    resources.push({ kind: 'worktree', id: worktree, status: 'preserved', message });
+    leaks.push(message);
+    return { resources, leaks };
+  }
+
+  if (existsSync(worktree)) {
+    const top = git(worktree, ['rev-parse', '--show-toplevel']);
+    const currentBranch = git(worktree, ['branch', '--show-current']);
+    const status = git(worktree, ['status', '--porcelain=v1', '--untracked-files=all']);
+    if (!top.ok || !samePath(top.stdout, worktree) || (safeBranch && currentBranch.stdout !== safeBranch)) {
+      const message = `Workspace ownership mismatch; preserved ${worktree}.`;
+      resources.push({ kind: 'worktree', id: worktree, status: 'preserved', message });
+      leaks.push(message);
+      return { resources, leaks };
+    }
+    if (!status.ok || status.stdout.trim()) {
+      const message = `Workspace contains unintegrated or unreadable changes; preserved ${worktree}.`;
+      resources.push({ kind: 'worktree', id: worktree, status: 'preserved', message });
+      leaks.push(message);
+      return { resources, leaks };
+    }
+    const removed = git(sourceRoot, ['worktree', 'remove', '--force', worktree]);
+    if (!removed.ok) {
+      const message = `Failed to remove managed worktree: ${removed.stderr}`;
+      resources.push({ kind: 'worktree', id: worktree, status: 'failed', message });
+      leaks.push(message);
+      return { resources, leaks };
+    }
+    resources.push({ kind: 'worktree', id: worktree, status: 'cleaned' });
+  } else {
+    resources.push({ kind: 'worktree', id: worktree, status: 'missing' });
+    git(sourceRoot, ['worktree', 'prune', '--expire', 'now']);
+  }
+
+  const checkoutId = workspace.checkoutId;
+  if (!checkoutId) {
+    const message = `Managed Campaign ${campaign.campaignId} workspace has no checkout identity.`;
+    resources.push({ kind: 'checkout', id: worktree, status: 'failed', message });
+    leaks.push(message);
+  } else {
+    try {
+      setRepositoryCheckoutLifecycle({
+        repoId: campaign.repoId,
+        checkoutId,
+        lifecycle: 'removed',
+        reason: `Campaign ${campaign.campaignId} workspace cleanup completed.`,
+        controllerHome,
+      });
+      resources.push({ kind: 'checkout', id: checkoutId, status: 'cleaned' });
+    } catch (error) {
+      const message = `Failed to update checkout lifecycle: ${error instanceof Error ? error.message : String(error)}`;
+      resources.push({ kind: 'checkout', id: checkoutId, status: 'failed', message });
+      leaks.push(message);
+    }
+  }
+
+  if (safeBranch) {
+    const branchRevision = git(sourceRoot, ['rev-parse', '--verify', branchRef(safeBranch, { purpose: 'CAMPAIGN_WORKSPACE_BRANCH' })]);
+    if (!branchRevision.ok) {
+      resources.push({ kind: 'branch', id: safeBranch, status: 'missing' });
+    } else {
+      const safe = options?.targetBranch
+        ? git(sourceRoot, ['branch', '--merged', options.targetBranch, '--list', safeBranch]).stdout.includes(safeBranch)
+        : !baseRevision || branchRevision.stdout === baseRevision;
+      if (!safe) {
+        const message = options?.targetBranch
+          ? `Campaign branch has unmerged commits into ${options.targetBranch}; preserved ${safeBranch}.`
+          : `Campaign branch has commits beyond its base revision; preserved ${safeBranch}.`;
+        resources.push({ kind: 'branch', id: safeBranch, status: 'preserved', message });
+        leaks.push(message);
+      } else {
+        const deleted = git(sourceRoot, ['branch', '-D', safeBranch]);
+        if (deleted.ok) resources.push({ kind: 'branch', id: safeBranch, status: 'cleaned' });
+        else {
+          const message = `Failed to delete managed branch: ${deleted.stderr}`;
+          resources.push({ kind: 'branch', id: safeBranch, status: 'failed', message });
+          leaks.push(message);
+        }
+      }
+    }
+  }
+  return { resources, leaks };
+}
+
+/**
+ * Two-phase, idempotent Campaign cancellation. A Campaign is not terminal
+ * until child Jobs and managed workspace resources have been reconciled.
+ */
+export async function cancelCampaign(
+  controllerHome: string,
+  repoId: string,
+  campaignId: string,
+  requestId: string,
+  reason = 'Cancelled by user',
+  expectedRevision?: number,
+): Promise<Campaign> {
+  const initial = getCampaign(controllerHome, repoId, campaignId);
+  if (initial.status === 'completed') throw new Error('CAMPAIGN_ALREADY_COMPLETED');
+  if (initial.status === 'cancelled') return initial;
+
+  const startedAt = now();
+  let campaign = updateCampaign(controllerHome, repoId, campaignId, `${requestId}:begin`, (current) => {
+    current.status = 'cancelling';
+    current.pauseReason = reason;
+    current.nextReconcileAt = undefined;
+    current.cleanup = { schemaVersion: 1, startedAt, resources: [], leaks: [] };
+    for (const checkpoint of current.checkpoints) {
+      if (checkpoint.status === 'open') checkpoint.status = 'superseded';
+    }
+    for (const task of current.tasks) {
+      if (!['succeeded', 'succeeded_no_change', 'skipped', 'failed', 'failed_no_effect', 'blocked', 'cancelled'].includes(task.status)) {
+        task.status = 'cancelled';
+        task.completedAt = startedAt;
+      }
+    }
+    return current;
+  }, {
+    expectedRevision,
+    eventType: 'campaign_cancelling',
+    eventData: { reason },
+    requestFingerprint: reason,
+  });
+
+  const report: CampaignCleanupReport = { schemaVersion: 1, startedAt, resources: [], leaks: [] };
+  const childJobIds = new Set([
+    ...campaign.tasks.map((task) => task.jobId),
+    ...campaign.checkpoints.map((checkpoint) => checkpoint.triggerJobId),
+  ].filter((jobId): jobId is string => Boolean(jobId)));
+  for (const jobId of childJobIds) {
+    const job = findExecutionJob(controllerHome, jobId);
+    if (!job) {
+      report.resources.push({ kind: 'job', id: jobId, status: 'missing' });
+      continue;
+    }
+    try {
+      const cancelled = await cancelExecutionJob(controllerHome, repoId, jobId, `Campaign ${campaignId}: ${reason}`);
+      report.resources.push({
+        kind: 'job',
+        id: jobId,
+        status: ['cancelled', 'succeeded', 'failed', 'timed_out', 'orphaned', 'stale', 'human_attention_required'].includes(cancelled.status)
+          ? 'cleaned'
+          : 'failed',
+        message: `Execution Job ended as ${cancelled.status}.`,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      report.resources.push({ kind: 'job', id: jobId, status: 'failed', message });
+      report.leaks.push(`job ${jobId}: ${message}`);
+    }
+  }
+
+  for (const checkpoint of campaign.checkpoints) {
+    report.resources.push({
+      kind: 'checkpoint', id: checkpoint.checkpointId,
+      status: checkpoint.status === 'superseded' || checkpoint.status === 'submitted' ? 'cleaned' : 'preserved',
+    });
+  }
+
+  const workspace = cleanupManagedWorkspace(controllerHome, campaign);
+  report.resources.push(...workspace.resources);
+  report.leaks.push(...workspace.leaks);
+  report.finishedAt = now();
+
+  campaign = updateCampaign(controllerHome, repoId, campaignId, `${requestId}:finalize`, (current) => {
+    current.cleanup = report;
+    current.status = report.leaks.length > 0 ? 'cancelled_with_leaks' : 'cancelled';
+    current.completedAt = report.finishedAt;
+    current.nextReconcileAt = undefined;
+    return current;
+  }, {
+    eventType: report.leaks.length > 0 ? 'campaign_cancelled_with_leaks' : 'campaign_cancelled',
+    eventData: { reason, cleanup: report },
+    requestFingerprint: JSON.stringify({ reason, leaks: report.leaks }),
+  });
+  return campaign;
+}
+
+/**
+ * After a campaign is accepted/completed, clean up its managed workspace using
+ * `git branch --merged <targetBranch>` as the safety gate rather than the
+ * cancel-path's base-revision check. Merged branches and their worktrees are
+ * removed; unmerged ones are preserved and recorded as leaks.
+ */
+export function completeCampaignWorkspace(
+  controllerHome: string,
+  repoId: string,
+  campaignId: string,
+  requestId: string,
+): Campaign {
+  const campaign = getCampaign(controllerHome, repoId, campaignId);
+  const repository = getRepository(repoId, controllerHome);
+  const targetBranch = repository.defaultBranch ?? 'main';
+
+  const startedAt = now();
+  const report: CampaignCleanupReport = { schemaVersion: 1, startedAt, resources: [], leaks: [] };
+  const workspace = cleanupManagedWorkspace(controllerHome, campaign, { targetBranch });
+  report.resources.push(...workspace.resources);
+  report.leaks.push(...workspace.leaks);
+  report.finishedAt = now();
+
+  return updateCampaign(controllerHome, repoId, campaignId, `${requestId}:workspace-cleanup`, (current) => {
+    current.cleanup = report;
+    return current;
+  }, {
+    eventType: report.leaks.length > 0 ? 'campaign_workspace_cleanup_leaks' : 'campaign_workspace_cleaned',
+    eventData: { cleanup: report },
+  });
+}