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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: reconcile legacy retirement records after archive removal (#13537)
picodot9498483527e8
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.mdindex 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, everycapture and unfinished sibling checkout; it does not reset or resume exhaustedretry 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 preservationFor a reviewed checkout that exceeds the ordinary archive byte bounds, thediff --git a/scripts/migrations/443-legacy-retirement-record-transition.js b/scripts/migrations/443-legacy-retirement-record-transition.jsnew file mode 100644index 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.mdindex 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.jsindex 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.jsnew file mode 100644index 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.jsindex 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 (rconst { 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.jsindex 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.jsindex d051804401..dcd7017d45 100644--- a/server/services/cosTaskPreStepBlocks.js+++ b/server/services/cosTaskPreStepBlocks.js@@ -531,7 +531,9 @@ export async function resolveBranchReconcileBlock(app, taskType, metadata, taskSconst 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.jsindex 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.jsindex 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 ordiff --git a/server/services/legacyRetirementReconciliation.js b/server/services/legacyRetirementReconciliation.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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, remaconst 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, remaconst 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, remaif (!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.jsindex 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.jsindex 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 || {},