Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: reconcile legacy retirement records after archive removal (#13537)

picodot9498483527e8
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index 6af70d5de7..de138dd943 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -492,6 +492,22 @@ delivery remain held. Cleanup preserves the batch's incomplete result, every
capture and unfinished sibling checkout; it does not reset or resume exhausted
retry budgets.
+## Archive-era bookkeeping transition
+
+Migration 443 freezes existing retirement observations for reconciliation. A
+supported inventory refresh settles those observations only when no checkout,
+local branch, registered holder or active/human owner remains and a unique
+service receipt or verified merged delivery explains the old work. Squash and
+rebased deliveries use exact merged-head lineage or stable patch equivalence;
+an old SHA need not itself be an ancestor of main. Changed or unreadable
+evidence stays unresolved. New missing-checkout incidents are outside this
+frozen upgrade scope.
+
+The original observation and proof remain in `legacyRetirementTransition`
+audit history. Delivery-only settlement explicitly does not claim a verified
+deletion and creates no retirement receipt. Agent results, retry budgets and
+current worktrees are unchanged. A new sweep still establishes convergence.
+
## Whole-checkout preservation
For a reviewed checkout that exceeds the ordinary archive byte bounds, the
diff --git a/scripts/migrations/443-legacy-retirement-record-transition.js b/scripts/migrations/443-legacy-retirement-record-transition.js
new file mode 100644
index 0000000000..d7c7ab363c
--- /dev/null
+++ b/scripts/migrations/443-legacy-retirement-record-transition.js
@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { readJSONFile } from "../../server/lib/jsonIo.js";
+import { markLegacyRetirements } from "../../server/lib/legacyRetirementTransition.js";
+import { writeJsonAtomic } from "./_lib.js";
+
+/** Mark existing bookkeeping for evidence-based transition; erase no work or history. */
+export default {
+ async up({ rootDir }) {
+ const path = join(rootDir, "data/cos/task-schedule.json");
+ const schedule = await readJSONFile(path, null, { strict: true });
+ if (!schedule) return { marked: 0 };
+ const policyChanged = schedule.retirementPolicyVersion !== 2;
+ schedule.retirementPolicyVersion = 2;
+ let marked = 0;
+ const execution = schedule.executions?.["task:branch-reconcile"];
+ for (const record of [
+ execution,
+ ...Object.values(execution?.perApp || {}),
+ ]) {
+ if (markLegacyRetirements(record?.branchReconcileOutcome)) marked++;
+ }
+ if (marked || policyChanged) await writeJsonAtomic(path, schedule);
+ return { marked };
+ },
+};
diff --git a/server/lib/README.md b/server/lib/README.md
index 7c229198c0..b7e84c61a7 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -29,6 +29,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `checkoutRetirementAdmission.js` | Durable common-repository publication/cut admission for explicit initialized-checkout quarantine; pending reservations survive restart and block managed checkout mutations until verified recovery. |
| `branchRetirementArchive.js` | `preserveBranchRetirement` remains for direct callers and historical tests. Production branch deletion does not call it and does not write `data/cos/branch-retirement-archives`. Deletion still uses Git's receiver lease and holder guards, then removes the local branch section after the ref is actually gone. |
| `reconcileRetirementEvidence.js` | Matches exact checkout receipts and recovered-preservation receipts, preserves observation identity across delayed scans, and retains each unresolved checkout incarnation. Legacy observations keep their original generation timestamps. A recreated checkout at the same branch, path and head starts after every older receipt; verified historical preservation does not assert branch deletion. |
+| `legacyRetirementTransition.js` | Freezes archive-era observations for evidence-based reconciliation and retains their original diagnoses and delivery/receipt proofs as audit history, without manufacturing deletion receipts or changing task outcomes. |
| `retirementCheckoutObservation.js` | Reads a checkout's filesystem identity and verifies its live branch/head before the schedule writer admits a recreated checkout's obligation. |
| `backupSharedAdmission.js` | Durable cross-process backup cuts and publication leases, with fail-closed owner recovery. |
| `runtimeFilePublication.js` | Admitted runtime recording updates with rollback of the prior file pair on failure. |
diff --git a/server/lib/index.js b/server/lib/index.js
index 4570870d52..88dce78a64 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -960,6 +960,7 @@ export * from './brainLinkLocalFields.js';
export * from './branchRetirementArchive.js';
export * from './reconcileRetirementEvidence.js';
+export * from './legacyRetirementTransition.js';
export * from './retirementCheckoutObservation.js';
export * from './checkoutRetirementAdmission.js';
diff --git a/server/lib/legacyRetirementTransition.js b/server/lib/legacyRetirementTransition.js
new file mode 100644
index 0000000000..26700c1a5e
--- /dev/null
+++ b/server/lib/legacyRetirementTransition.js
@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto';
+
+/** Frozen upgrade observations distinguish archive-era bookkeeping from new incidents. */
+export const legacyRetirementKey = row => createHash('sha256').update(JSON.stringify([
+ row.branch ?? null, row.path ?? null, row.head ?? null, row.checkoutIdentity ?? null, row.createdAt ?? null,
+])).digest('hex');
+
+export function markLegacyRetirements(outcome) {
+ if (!outcome || outcome.legacyRetirementTransition) return false;
+ const rows = [...(outcome.retirementObligations || []), ...(outcome.remaining || [])]
+ .filter(row => ['retirement-review-pending', 'retirement-receipt-unverified', 'retirement-provenance-unverified'].includes(row.reason));
+ outcome.legacyRetirementTransition = { version: 1, observations: [...new Set(rows.map(legacyRetirementKey))], resolutions: [] };
+ if (outcome.reason === 'historical-preservation-unresolved') {
+ outcome.reason = 'legacy-retirement-records-pending';
+ outcome.nextAction = 'Reconcile historical delivery and retirement evidence. Checkout archives are no longer required.';
+ }
+ return true;
+}
+
+/** Retain the original diagnosis and actual proof; never manufacture a deletion receipt. */
+export function applyLegacyRetirementResolutions(outcome, resolutions, now) {
+ const transition = outcome?.legacyRetirementTransition;
+ if (transition?.version !== 1) return outcome;
+ const accepted = resolutions.filter(row => transition.observations.includes(row.key));
+ if (!accepted.length) return outcome;
+ const keys = new Set(accepted.map(row => row.key));
+ const history = [...transition.resolutions];
+ for (const row of accepted) if (!history.some(entry => entry.key === row.key)) history.push({ ...row, resolvedAt: now });
+ const remaining = (outcome.remaining || []).filter(row => !keys.has(legacyRetirementKey(row)));
+ const retirementObligations = (outcome.retirementObligations || []).filter(row => !keys.has(legacyRetirementKey(row)));
+ return { ...outcome, remaining, retirementObligations, updatedAt: now,
+ legacyRetirementTransition: { ...transition, resolutions: history },
+ // A new sweep, rather than historical delivery, establishes repository convergence.
+ reason: remaining.length ? 'remaining-holds' : 'legacy-retirement-records-reconciled',
+ status: 'incomplete', nextAction: 'Run branch reconciliation to verify the current local repository state.' };
+}
diff --git a/server/routes/cosScheduleRoutes.js b/server/routes/cosScheduleRoutes.js
index 0da6e50018..234aff4222 100644
--- a/server/routes/cosScheduleRoutes.js
+++ b/server/routes/cosScheduleRoutes.js
@@ -301,6 +301,9 @@ router.post('/schedule/branch-reconcile/checkouts/review', asyncHandler(async (r
const { appId, prUrl, kind, ...release } = validateRequest(heldCheckoutReviewBodySchema, req.body);
const { prepareInventoriedCheckoutRetirement } = await import('../services/heldCheckoutRecovery.js');
const result = await prepareInventoriedCheckoutRetirement({ appId, release, prUrl, ...(kind && { kind }) });
+ if (!result.ok && result.reason === 'retirement-submodule-not-uninitialized' && !result.nextAction) {
+ result.nextAction = 'This checkout has initialized Git submodules. Request its exact review through /api/cos/schedule/branch-reconcile/initialized-checkouts/review; do not deinitialize or remove modules to bypass this refusal.';
+ }
if (!result.ok) throw new ServerError(`Checkout review refused: ${result.reason}`, {
status: 409, code: 'CHECKOUT_REVIEW_REFUSED', context: { reason: result.reason, ...(result.archiveLimit && { archiveLimit: result.archiveLimit }), ...(result.nextAction && { nextAction: result.nextAction }) },
});
diff --git a/server/routes/cosScheduleRoutes.test.js b/server/routes/cosScheduleRoutes.test.js
index c37515ca0a..ff911b2594 100644
--- a/server/routes/cosScheduleRoutes.test.js
+++ b/server/routes/cosScheduleRoutes.test.js
@@ -78,6 +78,18 @@ describe('CoS Schedule Routes', () => {
expect((await request(app).post('/api/cos/schedule/branch-reconcile/checkouts/review').send({ appId: 'app-1', ...tuple, prUrl, kind: 'force' })).status).toBe(400);
});
+ it('explains the supported initialized-submodule workflow without weakening the ordinary refusal', async () => {
+ recovery.prepareInventoriedCheckoutRetirement.mockResolvedValue({ ok: false, reason: 'retirement-submodule-not-uninitialized' });
+ const response = await request(app).post('/api/cos/schedule/branch-reconcile/checkouts/review').send({
+ appId: 'app-1', path: '/synthetic/checkout', head: 'a'.repeat(40), branch: 'feature/example',
+ locked: false, lockReason: null, prUrl: 'https://github.com/example/repo/pull/42',
+ });
+ expect(response.status).toBe(409);
+ expect(response.body.context).toMatchObject({ reason: 'retirement-submodule-not-uninitialized',
+ nextAction: expect.stringContaining('/initialized-checkouts/review') });
+ expect(response.body.context.nextAction).toContain('do not deinitialize');
+ });
+
it.each([false, true])('validates retirement review evidence with optional observation identity: %s', async withObservation => {
const tuple = { path: '/synthetic/checkout', head: 'a'.repeat(40), branch: 'claim/42', locked: false, lockReason: null };
if (withObservation) Object.assign(tuple, { checkoutIdentity: 'c'.repeat(64), observedAt: '2026-10-23T00:00:00Z' });
diff --git a/server/services/cosTaskPreStepBlocks.js b/server/services/cosTaskPreStepBlocks.js
index d051804401..dcd7017d45 100644
--- a/server/services/cosTaskPreStepBlocks.js
+++ b/server/services/cosTaskPreStepBlocks.js
@@ -531,7 +531,9 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskS
const detachedSuffix = countSuffix(result.detachedWorktrees, 'detached worktree(s) held back', (d) => d.reason);
// Publish the exact release rows before preparing the live preview. Proof
// objects may be fetched, but only a reviewed digest authorizes retirement.
- const previousOutcome = await taskSchedule.getBranchReconcileOutcome(app.id);
+ const observedOutcome = await taskSchedule.getBranchReconcileOutcome(app.id);
+ const { reconcileLegacyRetirementRecords } = await import('./legacyRetirementReconciliation.js');
+ const previousOutcome = await reconcileLegacyRetirementRecords(app.id, observedOutcome).catch(() => observedOutcome);
const unresolved = unresolvedRetirements(previousOutcome);
const absentObligations = unresolved.filter(release => !result.worktreeInventory?.some(tree => sameRetirementCheckout(tree, release)));
let retirementReviews = { candidates: [], held: [] };
diff --git a/server/services/heldCheckoutRecovery.test.js b/server/services/heldCheckoutRecovery.test.js
index f59630228f..fc9529a950 100644
--- a/server/services/heldCheckoutRecovery.test.js
+++ b/server/services/heldCheckoutRecovery.test.js
@@ -1159,6 +1159,37 @@ describe.skipIf(SKIP_HEAVY_INTEGRATION)('held checkout recovery (real git)', ()
return { path, release, admin, opts, forge, prepare, confirm };
}
+ it.each(['unrelated-upstream', 'changed-delivery'])('uses exact merged PR file scope after inherited upstream history: %s', async scenario => {
+ const c = await reviewedCheckout(`scope-${scenario}`, { normalMerge: true });
+ await writeFile(join(repo, 'upstream.txt'), 'inherited upstream\n');
+ await execGit(['add', 'upstream.txt'], repo);
+ await execGit(['commit', '-m', 'upstream work already delivered elsewhere'], repo);
+ await execGit(['merge', '--ff-only', 'main'], c.path);
+ await writeFile(join(c.path, 'feature.txt'), 'current PR delivery\n');
+ await execGit(['commit', '-am', 'current PR'], c.path);
+ c.release.head = (await execGit(['rev-parse', 'HEAD'], c.path)).stdout.trim();
+ await execGit(['merge', '--ff-only', c.release.branch], repo);
+ c.forge.prHead = c.release.head;
+ c.forge.mergeCommit = c.release.head;
+ await writeFile(join(repo, scenario === 'changed-delivery' ? 'feature.txt' : 'upstream.txt'), 'later upstream change\n');
+ await execGit(['commit', '-am', 'advance default after delivery'], repo);
+ c.forge.defaultHead = (await execGit(['rev-parse', 'HEAD'], repo)).stdout.trim();
+ await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [{ ...c.release, reason: 'pr-completion-review-required' }] });
+ const prepared = await c.prepare();
+ expect(prepared).toMatchObject({ ok: true, review: { comparison: { paths: ['feature.txt'],
+ disposition: scenario === 'changed-delivery' ? 'review-supersession' : 'integrated' } } });
+ const result = await c.confirm(prepared.review);
+ if (scenario === 'changed-delivery') {
+ expect(result).toMatchObject({ ok: false, reason: 'retirement-supersession-not-accepted' });
+ expect(await registered(c.path)).toBe(true);
+ } else {
+ expect(result).toMatchObject({ ok: true, branchDeleted: true });
+ expect(await registered(c.path)).toBe(false);
+ expect(await archives()).toEqual([]);
+ }
+ expect(await readFile(join(repo, scenario === 'changed-delivery' ? 'feature.txt' : 'upstream.txt'), 'utf8')).toBe('later upstream change\n');
+ });
+
async function receiptCheckout(name, options) {
const checkout = await reviewedCheckout(name, options);
await execGit(['worktree', 'unlock', checkout.path], repo);
diff --git a/server/services/heldCheckoutReview.js b/server/services/heldCheckoutReview.js
index 51f6e23667..b1e376e843 100644
--- a/server/services/heldCheckoutReview.js
+++ b/server/services/heldCheckoutReview.js
@@ -161,7 +161,12 @@ export async function buildCheckoutRetirementReview({ repoPath, release, prUrl,
git(['diff', '--binary', '--no-ext-diff', '--no-textconv', base, release.head], repoPath),
]);
const localPaths = localPathsOut.split('\0').filter(Boolean);
- const paths = [...new Set([...forge.changedPaths, ...localPaths])].sort();
+ // An exact merged PR head can carry previously merged/squashed history and
+ // upstream merges before its first listed commit. Those inherited files are
+ // not this PR's change scope. Older/replacement source heads still need the
+ // complete local patch comparison so unpublished work cannot disappear.
+ const paths = [...new Set(release.head === forge.prHead && !kind
+ ? forge.changedPaths : [...forge.changedPaths, ...localPaths])].sort();
const difference = paths.length ? await git(['--literal-pathspecs', 'diff', '--binary', '--no-ext-diff', '--no-textconv', release.head, forge.defaultHead, '--', ...paths], repoPath) : '';
// Historical ancestry/cherry equivalence does not establish that current
// code still implements the original work (it may have been strengthened or
diff --git a/server/services/legacyRetirementReconciliation.js b/server/services/legacyRetirementReconciliation.js
new file mode 100644
index 0000000000..7d77d5a6ed
--- /dev/null
+++ b/server/services/legacyRetirementReconciliation.js
@@ -0,0 +1,157 @@
+/** Upgrade bookkeeping only: this module never removes a checkout/ref or asserts
+ * an unrecorded deletion succeeded. Fresh local work always stays actionable. */
+import { devNull } from 'node:os';
+import { resolve } from 'node:path';
+import { spawn } from '../lib/childProcess.js';
+import { execGit } from '../lib/execGit.js';
+import { withSpawnCwdEnv } from '../lib/spawnCwd.js';
+import { readGitCommonDirectory } from '../lib/gitRepositoryIdentity.js';
+import { explicitPrCompletion, PR_COMPLETIONS } from '../lib/prDisposition.js';
+import { legacyRetirementKey } from '../lib/legacyRetirementTransition.js';
+import { readCheckoutPathPresence, readLocalBranchPresence } from './repoCleanupObservation.js';
+import { completedCheckoutReceiptValid } from './completedCheckoutEvidence.js';
+
+const oid = value => typeof value === 'string' && /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(value);
+const samePath = (a, b) => typeof a === 'string' && typeof b === 'string'
+ && (process.platform === 'win32' ? resolve(a).toLowerCase() === resolve(b).toLowerCase() : resolve(a) === resolve(b));
+const branches = agent => {
+ const m = agent.metadata || {};
+ return [m.worktreeBranch, m.claimBranch, m.jiraBranch, m.branchCompletionPolicy?.branch,
+ ...(m.claimBranches || []), ...(m.claimReleasedBranches || [])];
+};
+async function protectedOwner(agents, row, repoPath, identities) {
+ const identity = path => {
+ if (!identities.has(path)) identities.set(path, readGitCommonDirectory(path));
+ return identities.get(path);
+ };
+ for (const agent of agents) {
+ const m = agent.metadata || {};
+ const completion = (m.branchCompletionPolicy?.branch === row.branch ? m.branchCompletionPolicy.completion : null)
+ || m.prCompletionPolicy || explicitPrCompletion({ type: m.taskType, metadata: { ...m, analysisType: m.taskAnalysisType } });
+ const handoff = completion && ![PR_COMPLETIONS.REVIEW_THEN_MERGE, PR_COMPLETIONS.MERGE_ON_GREEN].includes(completion);
+ if (!(branches(agent).includes(row.branch) || samePath(m.workspacePath, row.path))
+ || !(agent.status !== 'completed' || handoff)) continue;
+ const source = m.sourceWorkspace || m.primaryCheckoutBaseline?.path;
+ if (source && !samePath(source, repoPath)) {
+ const [local, owner] = await Promise.all([identity(repoPath), identity(source)]);
+ if (local && owner && local !== owner) continue;
+ }
+ return true;
+ }
+ return false;
+}
+const proofEnv = () => ({ ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith('GIT_'))), GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1',
+ GIT_NO_LAZY_FETCH: '1', GIT_GRAFT_FILE: devNull });
+const git = (repo, args) => execGit(['--no-replace-objects', '-c', 'core.commitGraph=false', ...args], repo,
+ { env: proofEnv(), timeout: 10000, maxBuffer: 8 * 1024 * 1024 });
+const ancestor = (repo, a, b) => oid(a) && oid(b)
+ ? git(repo, ['merge-base', '--is-ancestor', a, b]).then(() => true, () => false) : false;
+
+/** Stable patch identity handles a reviewed squash without requiring its old SHAs on main. */
+async function patchId(repo, from, to) {
+ const patch = (await git(repo, ['diff', '--binary', '--no-ext-diff', '--no-textconv', from, to])).stdout;
+ if (!patch) return null;
+ return new Promise((done, reject) => {
+ const child = spawn('git', ['patch-id', '--stable'], { cwd: repo, env: withSpawnCwdEnv(proofEnv(), repo), shell: false });
+ let output = '';
+ const timer = setTimeout(() => child.kill('SIGTERM'), 5000);
+ child.stdout.on('data', chunk => { output += chunk; if (output.length > 4096) child.kill('SIGTERM'); });
+ child.stdin.on('error', () => {});
+ child.on('error', error => { clearTimeout(timer); reject(error); });
+ child.on('close', code => { clearTimeout(timer); done(code === 0 && /^[a-f0-9]{40,64} /.test(output) ? output.split(' ')[0] : null); });
+ child.stdin.end(patch);
+ });
+}
+
+async function absent(repoPath, row, trees, agents, identities = new Map()) {
+ if (!row.branch || await protectedOwner(agents, row, repoPath, identities)
+ || trees.some(tree => tree.branch === `refs/heads/${row.branch}` || samePath(tree.path, row.path))) return false;
+ if (row.path && await readCheckoutPathPresence(row.path) !== false) return false;
+ return await readLocalBranchPresence(repoPath, row.branch) === false;
+}
+
+function targetFor(outcome, row, repoPath, agents) {
+ const knownReceipts = [...(outcome.retired || []), ...Object.values(outcome.retirementReceiptEvidence || {})];
+ const receipts = knownReceipts
+ .filter(receipt => receipt.branchDeleted === true && receipt.branch === row.branch && oid(receipt.head)
+ && receipt.path && Number.isFinite(Date.parse(receipt.retiredAt))
+ && (!row.path || samePath(row.path, receipt.path))
+ && (!oid(row.head) || row.head === receipt.head || (row.checkoutIdentity && row.checkoutIdentity === receipt.checkoutIdentity
+ && Number.isFinite(Date.parse(row.observedAt || row.createdAt))
+ && Date.parse(receipt.retiredAt) >= Date.parse(row.observedAt || row.createdAt)))
+ && (!row.checkoutIdentity || row.checkoutIdentity === receipt.checkoutIdentity));
+ const unique = [...new Map(receipts.map(receipt => [JSON.stringify([receipt.path, receipt.head, receipt.checkoutIdentity]), receipt])).values()];
+ if (unique.length === 1) return { target: { ...row, ...unique[0] }, receipt: unique[0] };
+ if (unique.length > 1) return null;
+ if (row.checkoutIdentity && knownReceipts.some(receipt => receipt.branch === row.branch
+ && samePath(receipt.path, row.path) && receipt.checkoutIdentity && receipt.checkoutIdentity !== row.checkoutIdentity)) return null;
+ if (oid(row.head) && row.path) return { target: row };
+ const captures = agents.flatMap(agent => (agent.metadata?.completedCheckouts || [])
+ .filter(capture => samePath(capture.repoPath, repoPath) && capture.branch === row.branch
+ && (!row.path || samePath(row.path, capture.path)) && (!oid(row.head) || row.head === capture.head)
+ && !row.checkoutIdentity && completedCheckoutReceiptValid(agent, capture)));
+ return captures.length === 1 ? { target: { ...row, ...captures[0] } } : null;
+}
+
+export async function _planLegacyRetirementReconciliation({ repoPath, outcome, agents, trees, defaultHead }, options = {}) {
+ const transition = outcome?.legacyRetirementTransition;
+ if (transition?.version !== 1 || !Array.isArray(agents) || !Array.isArray(trees) || !oid(defaultHead)) return [];
+ const rows = [...new Map([...(outcome.retirementObligations || []), ...(outcome.remaining || [])]
+ .filter(row => transition.observations.includes(legacyRetirementKey(row)))
+ .map(row => [legacyRetirementKey(row), row])).values()];
+ const resolutions = [];
+ const identities = new Map();
+ let forgeReads = 0;
+ for (const observation of rows) {
+ const bound = targetFor(outcome, observation, repoPath, agents);
+ if (!bound || !await absent(repoPath, bound.target, trees, agents, identities)) continue;
+ const { target, receipt } = bound;
+ let evidence = receipt ? { kind: 'existing-service-receipt', receipt } : null;
+ if (!evidence && await ancestor(repoPath, target.head, defaultHead)) evidence = { kind: 'merged-ancestry', head: target.head, defaultHead };
+ if (!evidence && forgeReads < 8 && options.readMergedDelivery) {
+ forgeReads++;
+ const forge = await options.readMergedDelivery(target).catch(() => null);
+ if (forge?.prHead && forge.publishedBranch === target.branch && await ancestor(repoPath, forge.mergeCommit, defaultHead)) {
+ if (await ancestor(repoPath, target.head, forge.prHead)) evidence = { kind: 'reviewed-merged-continuation', head: target.head, prHead: forge.prHead, mergeCommit: forge.mergeCommit, prUrl: forge.prUrl };
+ else {
+ const base = await git(repoPath, ['merge-base', target.head, `${forge.mergeCommit}^`]).then(r => r.stdout.trim(), () => null);
+ if (oid(base)) {
+ const [source, delivered] = await Promise.all([patchId(repoPath, base, target.head), patchId(repoPath, `${forge.mergeCommit}^`, forge.mergeCommit)]).catch(() => []);
+ if (source && source === delivered) evidence = { kind: 'merged-patch-equivalence', head: target.head, mergeCommit: forge.mergeCommit, prUrl: forge.prUrl, patchId: source };
+ }
+ }
+ }
+ }
+ if (evidence) resolutions.push({ key: legacyRetirementKey(observation), observation, target, evidence,
+ disposition: 'legacy-bookkeeping-resolved', removalVerified: Boolean(receipt) });
+ }
+ return resolutions;
+}
+
+export async function reconcileLegacyRetirementRecords(appId, outcome) {
+ if (outcome?.legacyRetirementTransition?.version !== 1 || !outcome.legacyRetirementTransition.observations?.length) return outcome;
+ const [{ getAppById }, { readClaimOwnershipAgents, withClaimOwnershipLock }, { listWorktrees },
+ { getDefaultBranch }, { findMergedPullRequest, readRetirementForgeEvidence }, store] = await Promise.all([
+ import('./apps.js'), import('./cosClaimOwnership.js'), import('./worktreeManager.js'), import('./git.js'),
+ import('./heldCheckoutReview.js'), import('./taskSchedule.js'),
+ ]);
+ const app = await getAppById(appId);
+ if (!app?.repoPath) return outcome;
+ const repoPath = app.repoPath;
+ const [agents, trees, branch] = await Promise.all([readClaimOwnershipAgents(), listWorktrees(repoPath), getDefaultBranch(repoPath, { allowRemote: false, strict: true })]);
+ const defaultHead = (await git(repoPath, ['rev-parse', `refs/remotes/origin/${branch}^{commit}`])).stdout.trim();
+ const resolutions = await _planLegacyRetirementReconciliation({ repoPath, outcome, agents, trees, defaultHead }, {
+ readMergedDelivery: async target => {
+ const selected = await findMergedPullRequest(repoPath, target.branch, target.head, { forgeAccount: app.forgeAccount });
+ const facts = await readRetirementForgeEvidence(repoPath, target.branch, selected.url, { forgeAccount: app.forgeAccount });
+ return { ...facts, publishedBranch: facts.publishedBranch ?? target.branch };
+ },
+ });
+ if (!resolutions.length) return outcome;
+ return withClaimOwnershipLock(async () => {
+ const [currentAgents, currentTrees] = await Promise.all([readClaimOwnershipAgents(), listWorktrees(repoPath)]);
+ if (!Array.isArray(currentAgents)) return outcome;
+ return store.recordLegacyRetirementResolutions(appId, outcome, resolutions,
+ async () => (await Promise.all(resolutions.map(row => absent(repoPath, row.target, currentTrees, currentAgents)))).every(Boolean));
+ });
+}
diff --git a/server/services/legacyRetirementReconciliation.test.js b/server/services/legacyRetirementReconciliation.test.js
new file mode 100644
index 0000000000..4184e95312
--- /dev/null
+++ b/server/services/legacyRetirementReconciliation.test.js
@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execGit } from '../lib/execGit.js';
+import { markLegacyRetirements, applyLegacyRetirementResolutions } from '../lib/legacyRetirementTransition.js';
+import { _planLegacyRetirementReconciliation } from './legacyRetirementReconciliation.js';
+import migration from '../../scripts/migrations/443-legacy-retirement-record-transition.js';
+
+let root, repo;
+const git = async (...args) => (await execGit(args, repo)).stdout.trim();
+const save = async (path, value) => writeFile(path, `${JSON.stringify(value)}\n`);
+beforeEach(async () => {
+ root = await mkdtemp(join(tmpdir(), 'portos-legacy-retirement-'));
+ repo = join(root, 'repo');
+ await mkdir(repo);
+ await git('init', '-b', 'main');
+ await git('config', 'user.email', '[email protected]');
+ await git('config', 'user.name', 'Fixture');
+ await writeFile(join(repo, 'initial.txt'), 'base\n');
+ await git('add', '.'); await git('commit', '-m', 'base');
+});
+afterEach(async () => { await rm(root, { recursive: true, force: true }); });
+
+async function delivered({ rebased = false, changed = false } = {}) {
+ const branch = 'feature/delivered';
+ await git('checkout', '-b', branch);
+ await writeFile(join(repo, 'feature.txt'), 'delivered feature\n');
+ await git('add', '.'); await git('commit', '-m', 'feature');
+ const head = await git('rev-parse', 'HEAD');
+ await git('checkout', 'main');
+ if (rebased) {
+ await writeFile(join(repo, 'unrelated.txt'), 'new base\n');
+ await git('add', '.'); await git('commit', '-m', 'advance base');
+ await git('checkout', '-b', 'feature/reviewed');
+ await writeFile(join(repo, 'feature.txt'), changed ? 'different work\n' : 'delivered feature\n');
+ await git('add', '.'); await git('commit', '-m', 'reviewed delivery');
+ await git('checkout', 'main');
+ }
+ const prHead = await git('rev-parse', rebased ? 'feature/reviewed' : branch);
+ await git('merge', '--squash', rebased ? 'feature/reviewed' : branch);
+ await git('commit', '-m', 'merged reviewed feature');
+ const mergeCommit = await git('rev-parse', 'HEAD');
+ await git('update-ref', '-d', `refs/heads/${branch}`, head);
+ if (rebased) await git('update-ref', '-d', 'refs/heads/feature/reviewed', prHead);
+ return { row: { path: join(root, 'old-checkout'), branch, head, reason: 'retirement-provenance-unverified',
+ createdAt: '2026-01-02T00:00:00.000Z' }, forge: { publishedBranch: branch, prHead, mergeCommit,
+ prUrl: 'https://github.com/example/project/pull/42' } };
+}
+
+describe('legacy retirement transition at the persisted reconciliation boundary', () => {
+ it.each(['squash', 'rebased', 'changed-patch', 'active-owner', 'human-handoff', 'foreign-owner', 'live-checkout', 'new-incident'])(
+ 'reconciles historical delivery without asserting unrecorded removal: %s', async scenario => {
+ const { row, forge } = await delivered({ rebased: ['rebased', 'changed-patch'].includes(scenario), changed: scenario === 'changed-patch' });
+ const outcome = { status: 'incomplete', retirementObligations: [row], remaining: [row], retired: [] };
+ if (scenario !== 'new-incident') markLegacyRetirements(outcome);
+ const owners = scenario === 'active-owner' ? [{ id: 'current-owner', status: 'running', metadata: { claimBranches: [row.branch] } }] : [];
+ if (scenario === 'human-handoff') owners.push({ id: 'human-owner', status: 'completed', metadata: {
+ branchCompletionPolicy: { branch: row.branch, completion: 'leave-open' },
+ } });
+ if (scenario === 'foreign-owner') {
+ const other = join(root, 'independent-clone');
+ await mkdir(other); await execGit(['init'], other);
+ owners.push({ id: 'foreign-owner', status: 'running', metadata: { sourceWorkspace: other, claimBranches: [row.branch] } });
+ }
+ if (scenario === 'live-checkout') { await mkdir(row.path); await writeFile(join(row.path, 'unfinished.txt'), 'new owner work\n'); }
+ const input = { repoPath: repo, outcome, agents: owners, trees: [], defaultHead: forge.mergeCommit };
+ const plans = await _planLegacyRetirementReconciliation(input, { readMergedDelivery: async () => forge });
+ const expected = ['squash', 'rebased', 'foreign-owner'].includes(scenario);
+ expect(plans).toHaveLength(expected ? 1 : 0);
+ if (!expected) return;
+ expect(plans[0].removalVerified).toBe(false);
+ expect(plans[0].evidence.kind).toBe(scenario === 'rebased' ? 'merged-patch-equivalence' : 'reviewed-merged-continuation');
+ const path = join(root, 'outcome.json');
+ await save(path, applyLegacyRetirementResolutions(outcome, plans, '2026-01-03T00:00:00.000Z'));
+ const restarted = JSON.parse(await readFile(path, 'utf8'));
+ expect(restarted.retirementObligations).toEqual([]);
+ expect(restarted.remaining).toEqual([]);
+ expect(restarted.retired).toEqual([]); // No manufactured service receipt.
+ expect(restarted.legacyRetirementTransition.resolutions[0].observation).toEqual(row);
+ expect(await _planLegacyRetirementReconciliation({ ...input, outcome: restarted })).toEqual([]);
+ expect(await git('rev-parse', 'main')).toBe(forge.mergeCommit);
+ });
+
+ it('uses a unique real receipt to identify a malformed late row, retaining audit history', async () => {
+ const { row, forge } = await delivered();
+ const malformed = { branch: row.branch, head: row.branch, reason: row.reason, createdAt: row.createdAt };
+ const receipt = { ...row, checkoutIdentity: 'a'.repeat(64), branchDeleted: true, archiveDir: null, retiredAt: '2026-01-01T00:00:00.000Z' };
+ const outcome = { retirementObligations: [malformed], remaining: [malformed], retired: [receipt] };
+ markLegacyRetirements(outcome);
+ const plans = await _planLegacyRetirementReconciliation({ repoPath: repo, outcome, agents: [], trees: [], defaultHead: forge.mergeCommit });
+ expect(plans).toHaveLength(1);
+ expect(plans[0]).toMatchObject({ removalVerified: true, evidence: { kind: 'existing-service-receipt', receipt } });
+ // A newer reviewed head retired the same physical checkout after this
+ // observation. Old intermediate heads are not separate lost checkouts.
+ const intermediate = { ...row, head: 'c'.repeat(40), checkoutIdentity: receipt.checkoutIdentity,
+ createdAt: '2025-12-31T00:00:00.000Z' };
+ const progressed = { retirementObligations: [intermediate], remaining: [intermediate], retired: [receipt] };
+ markLegacyRetirements(progressed);
+ expect(await _planLegacyRetirementReconciliation({ repoPath: repo, outcome: progressed, agents: [], trees: [], defaultHead: forge.mergeCommit }))
+ .toMatchObject([{ removalVerified: true, target: { head: receipt.head }, observation: intermediate }]);
+ const changed = { ...malformed, checkoutIdentity: 'b'.repeat(64) };
+ const different = { retirementObligations: [changed], remaining: [changed], retired: [receipt] };
+ markLegacyRetirements(different);
+ expect(await _planLegacyRetirementReconciliation({ repoPath: repo, outcome: different, agents: [], trees: [], defaultHead: forge.mergeCommit })).toEqual([]);
+ });
+
+ it('migration freezes only existing records, survives replay, and changes no task policy or worktree', async () => {
+ const { row } = await delivered();
+ const path = join(root, 'data/cos/task-schedule.json');
+ await mkdir(join(root, 'data/cos'), { recursive: true });
+ const schedule = { tasks: { 'claim-issue': { enabled: true, failureCount: 3 } }, executions: {
+ 'task:branch-reconcile': { perApp: { example: { branchReconcileOutcome: { retirementObligations: [row], remaining: [row] } } } },
+ } };
+ await save(path, schedule);
+ expect(await migration.up({ rootDir: root })).toEqual({ marked: 1 });
+ const first = await readFile(path, 'utf8');
+ expect(await migration.up({ rootDir: root })).toEqual({ marked: 0 });
+ expect(await readFile(path, 'utf8')).toBe(first);
+ const current = JSON.parse(first);
+ expect(current.tasks).toEqual(schedule.tasks);
+ expect(current.executions['task:branch-reconcile'].perApp.example.branchReconcileOutcome.remaining).toEqual([row]);
+ expect(await git('status', '--porcelain')).toBe('');
+ });
+});
diff --git a/server/services/taskSchedule.js b/server/services/taskSchedule.js
index ef0a8e5b60..f193ffb11d 100644
--- a/server/services/taskSchedule.js
+++ b/server/services/taskSchedule.js
@@ -21,6 +21,8 @@
import { scheduleExecutionFieldsSchema } from '../lib/scheduleExecutionFieldsValidation.js';
import { unresolvedRetirements, retainRetirementObligations, sameRetirementCheckout, sameRetirementObservation, matchingRetirementReceipts, hasRetirementReceipt } from '../lib/reconcileRetirementEvidence.js';
+import { applyLegacyRetirementResolutions } from '../lib/legacyRetirementTransition.js';
+import { readCheckoutPathPresence, readLocalBranchPresence } from './repoCleanupObservation.js';
import { isCurrentRetirementCheckout } from '../lib/retirementCheckoutObservation.js';
import { findGoneInventoryRows, isObligationRow } from './branchReconcileInventoryPrune.js';
import { createHash, randomUUID } from 'node:crypto';
@@ -775,12 +777,24 @@ export async function recordBranchReconcileOutcome(appId, { status, reason, rema
const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
const now = new Date().toISOString();
const previous = record.branchReconcileOutcome;
+ const transition = schedule.retirementPolicyVersion === 2 && !previous?.legacyRetirementTransition
+ ? { version: 1, observations: [], resolutions: [] } : previous?.legacyRetirementTransition;
const existing = unresolvedRetirements(previous);
const admitted = [];
const rejected = [];
for (const row of [...(remaining || []), ...additionalObligations]) {
if (!isObligationRow(row)) continue;
if (existing.some(entry => sameRetirementObservation(entry, row))) continue;
+ const resolved = previous?.legacyRetirementTransition?.resolutions?.some(entry => sameRetirementObservation(entry.observation, row)
+ && (!row.createdAt || row.createdAt === entry.observation.createdAt));
+ if (resolved) {
+ const app = await getAppById(appId);
+ if (app?.repoPath && (!row.path || await readCheckoutPathPresence(row.path) === false)
+ && row.branch && await readLocalBranchPresence(app.repoPath, row.branch) === false) {
+ rejected.push(row);
+ continue;
+ }
+ }
const previousIncarnation = existing.some(entry => sameRetirementCheckout(entry, row));
const receipts = matchingRetirementReceipts(previous, row);
// Legacy rows without observation identity cannot claim to be recreations.
@@ -809,6 +823,7 @@ export async function recordBranchReconcileOutcome(appId, { status, reason, rema
const retained = retirementObligations.filter(obligation => !current?.some(row => sameRetirementObservation(row, obligation)));
record.branchReconcileOutcome = {
...previous, status, reason, nextAction, updatedAt: now, retirementObligations,
+ ...(transition && { legacyRetirementTransition: transition }),
...(remoteInventory !== undefined && { remoteInventory }),
remaining: retained.length ? [...(current || []), ...retained] : current,
observedAt: remaining === undefined ? record.branchReconcileOutcome?.observedAt ?? null : now,
@@ -819,11 +834,29 @@ export async function recordBranchReconcileOutcome(appId, { status, reason, rema
if (!appId || !unresolvedRetirements(outcome).length) return outcome;
const app = await getAppById(appId).catch(() => null);
if (!app?.repoPath) return outcome;
- // Keep the expensive archive verifier off ordinary live-checkout writes.
- const missing = await findGoneInventoryRows(app.repoPath, unresolvedRetirements(outcome), { includeObligations: true }).catch(() => []);
- if (!missing.length) return outcome;
- const { recoverMissingCheckoutPreservations } = await import('./heldCheckoutRecovery.js');
- return recoverMissingCheckoutPreservations({ appId, repoPath: app.repoPath, outcome });
+ // Compatibility for stores that have not yet run migration 443. Upgraded and
+ // fresh stores always have the transition marker and never require archives.
+ if (!outcome.legacyRetirementTransition) {
+ const missing = await findGoneInventoryRows(app.repoPath, unresolvedRetirements(outcome), { includeObligations: true }).catch(() => []);
+ if (!missing.length) return outcome;
+ const { recoverMissingCheckoutPreservations } = await import('./heldCheckoutRecovery.js');
+ return recoverMissingCheckoutPreservations({ appId, repoPath: app.repoPath, outcome });
+ }
+ // Writers are also called while a checkout retirement owns the claim lock.
+ // The scan entry points run historical proof work after that lock is released.
+ return outcome;
+}
+
+export async function recordLegacyRetirementResolutions(appId, expected, resolutions, stillAbsent) {
+ return updateSchedule(async schedule => {
+ const record = ensureExecutionRecord(schedule, 'branch-reconcile', appId);
+ if (JSON.stringify(record.branchReconcileOutcome) !== JSON.stringify(expected) || !await stillAbsent()) {
+ return { result: record.branchReconcileOutcome, changed: false };
+ }
+ const outcome = applyLegacyRetirementResolutions(expected, resolutions, new Date().toISOString());
+ record.branchReconcileOutcome = outcome;
+ return { result: outcome, changed: outcome !== expected };
+ });
}
/** Compare the whole observed inventory and its generation inside the schedule
@@ -896,7 +929,10 @@ export async function getBranchReconcileOutcome(appId) {
}
export async function getBranchReconcileInventory(appId) {
- return reconcileMissingInventory(appId, await getBranchReconcileOutcome(appId));
+ const outcome = await getBranchReconcileOutcome(appId);
+ const { reconcileLegacyRetirementRecords } = await import('./legacyRetirementReconciliation.js');
+ const current = await reconcileLegacyRetirementRecords(appId, outcome).catch(() => outcome);
+ return reconcileMissingInventory(appId, current);
}
const missingPreservationObligation = row => ({ ...row, reason: 'retirement-provenance-unverified' });
diff --git a/server/services/taskSchedule.test.js b/server/services/taskSchedule.test.js
index 65af7a87b8..861ed6eda4 100644
--- a/server/services/taskSchedule.test.js
+++ b/server/services/taskSchedule.test.js
@@ -150,6 +150,7 @@ import {
getPerpetualDrainState,
recordPerpetualDispatch,
recordBranchReconcileOutcome,
+ recordLegacyRetirementResolutions,
getBranchReconcileOutcome,
recordInitializedRetirementRecovery,
recordHeldCheckoutRetirement,
@@ -3299,6 +3300,38 @@ describe('taskSchedule', () => {
expect(await shouldRunTask('branch-reconcile', 'app-1')).toEqual({ shouldRun: false, reason: 'disabled' });
});
+ it('does not adopt new missing-checkout incidents into the frozen upgrade scope', async () => {
+ let saved = { version: 2, retirementPolicyVersion: 2, tasks: {}, executions: {}, templates: [] };
+ readJSONFile.mockImplementation(async () => structuredClone(saved));
+ writeFile.mockImplementation(async (_path, contents) => { saved = JSON.parse(contents); });
+ const row = { branch: 'fix/new-incident', path: '/example/new', head: 'a'.repeat(40), reason: 'retirement-provenance-unverified' };
+ const result = await recordBranchReconcileOutcome('app-1', { status: 'incomplete', remaining: [row] });
+ expect(result.legacyRetirementTransition).toEqual({ version: 1, observations: [], resolutions: [] });
+ expect(result.retirementObligations).toEqual([expect.objectContaining(row)]);
+ });
+
+ it('persists legacy audit settlement only against unchanged inventory and absent originals', async () => {
+ const { markLegacyRetirements, legacyRetirementKey } = await import('../lib/legacyRetirementTransition.js');
+ const row = { branch: 'fix/delivered', path: '/example/old', head: 'a'.repeat(40),
+ reason: 'retirement-provenance-unverified', createdAt: '2026-01-01T00:00:00.000Z' };
+ const original = { status: 'incomplete', remaining: [row], retirementObligations: [row], retired: [] };
+ markLegacyRetirements(original);
+ let saved = { version: 2, tasks: {}, executions: { 'task:branch-reconcile': {
+ perApp: { 'app-1': { branchReconcileOutcome: original } },
+ } }, templates: [] };
+ readJSONFile.mockImplementation(async () => structuredClone(saved));
+ writeFile.mockImplementation(async (_path, contents) => { saved = JSON.parse(contents); });
+ const plans = [{ key: legacyRetirementKey(row), observation: row, removalVerified: false,
+ evidence: { kind: 'merged-ancestry', head: row.head, defaultHead: 'b'.repeat(40) } }];
+ expect(await recordLegacyRetirementResolutions('app-1', { ...original, updatedAt: 'changed' }, plans, async () => true)).toEqual(original);
+ expect(await recordLegacyRetirementResolutions('app-1', original, plans, async () => false)).toEqual(original);
+ const result = await recordLegacyRetirementResolutions('app-1', original, plans, async () => true);
+ expect(result).toMatchObject({ retirementObligations: [], remaining: [], retired: [],
+ legacyRetirementTransition: { resolutions: [{ observation: row, removalVerified: false }] } });
+ expect(await recordLegacyRetirementResolutions('app-1', original, plans, async () => true)).toEqual(result);
+ expect(await getBranchReconcileOutcome('app-1')).toEqual(result);
+ });
+
it('persists incomplete sweep evidence and exposes it when recurring dispatch is off', async () => {
let saved = { version: 2, tasks: { 'branch-reconcile': { enabled: true, type: 'on-demand', perpetual: false } }, executions: {}, templates: [] };
readJSONFile.mockImplementation(async () => structuredClone(saved));
diff --git a/server/services/taskScheduleStore.js b/server/services/taskScheduleStore.js
index fa8d5654e2..41fc417613 100644
--- a/server/services/taskScheduleStore.js
+++ b/server/services/taskScheduleStore.js
@@ -29,6 +29,7 @@ const queueScheduleWrite = createFileWriteQueue();
*/
const DEFAULT_SCHEDULE = {
version: 2,
+ retirementPolicyVersion: 2,
lastUpdated: null,
// Unified task intervals (applies to all apps including PortOS)
@@ -57,6 +58,7 @@ function migrateScheduleV1toV2(schedule) {
const migrated = {
version: 2,
+ retirementPolicyVersion: schedule.retirementPolicyVersion ?? 1,
lastUpdated: new Date().toISOString(),
tasks: structuredClone(DEFAULT_TASK_INTERVALS),
executions: {},
@@ -228,6 +230,9 @@ async function readSchedule() {
const schedule = {
...DEFAULT_SCHEDULE,
+ // Pre-transition stores retain their compatibility semantics until migration
+ // 443 freezes their historical observations. Fresh installs start at v2.
+ retirementPolicyVersion: loaded.retirementPolicyVersion ?? 1,
...loaded,
tasks: mergedTasks,
executions: loaded.executions || {},