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
/** Server-observed checkout identity captured before a claim run completes.
* A branch name/path/head can all be reused; private Git filesystem identity
* distinguishes the completed checkout from a later manual checkout.
*/
import { lstat, realpath } from 'node:fs/promises';
import { join, resolve } from 'node:path';
import { execGit } from '../lib/execGit.js';
import { isTruthyMeta } from '../lib/metadataFlags.js';
import { z } from 'zod';
const shortBranch = branch => branch?.replace(/^refs\/heads\//, '');
const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
export const hasClaimCheckoutBindings = meta => meta?.isWorktree !== true
&& (isTruthyMeta(meta?.claimPicksOwnBranch) || Array.isArray(meta?.claimBranches));
const physicalIdentitySchema = z.object({ dev: z.string(), ino: z.string(), birthtimeNs: z.string() });
export const checkoutSeedSchema = z.object({ version: z.literal(1), agentId: z.string(), startedAt: z.string().datetime(),
seededAt: z.string().datetime(), repoPath: z.string(), branch: z.string(), path: z.string(),
repository: physicalIdentitySchema, checkout: physicalIdentitySchema,
incarnation: z.object({ pointer: physicalIdentitySchema,
gitdir: z.object({ path: z.string(), dev: z.string(), ino: z.string(), birthtimeNs: z.string() }) }) });
const repoCommonByRepo = new Map();
async function resolveRepoCommon(repository) {
let cached = repoCommonByRepo.get(repository);
if (!cached) {
cached = execGit(['rev-parse', '--git-common-dir'], repository)
.then(r => r.stdout.trim())
.catch(() => null);
repoCommonByRepo.set(repository, cached);
}
return cached;
}
async function filesystemIdentity(path, type) {
const stat = await lstat(path, { bigint: true });
if (!(type === 'file' ? stat.isFile() : stat.isDirectory()) || typeof stat.dev !== 'bigint'
|| typeof stat.ino !== 'bigint' || stat.ino <= 0n || typeof stat.birthtimeNs !== 'bigint' || stat.birthtimeNs <= 0n) {
throw new Error('checkout-incarnation-unavailable');
}
return { dev: String(stat.dev), ino: String(stat.ino), birthtimeNs: String(stat.birthtimeNs) };
}
export async function readCompletedCheckoutIdentity({ repoPath, branch, path, head, worktrees = null, repoCommon = null, allowLocked = false }) {
const { listWorktrees } = await import('./worktreeManager.js');
const repository = await realpath(repoPath);
const checkout = await realpath(path);
if (checkout === repository || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(head || '')) return null;
const trees = worktrees || await listWorktrees(repository);
const holders = trees.filter(tree => shortBranch(tree.branch) === branch);
if (holders.length !== 1 || (!allowLocked && holders[0].locked === true) || await realpath(holders[0].path) !== checkout || holders[0].head !== head) return null;
const pointer = await filesystemIdentity(join(checkout, '.git'), 'file');
const gitdir = await realpath((await execGit(['rev-parse', '--absolute-git-dir'], checkout)).stdout.trim());
const administration = await filesystemIdentity(gitdir, 'directory');
const [currentHead, currentBranch, common, resolvedRepoCommon] = await Promise.all([
execGit(['rev-parse', '--verify', 'HEAD^{commit}'], checkout),
execGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], checkout),
execGit(['rev-parse', '--git-common-dir'], checkout),
repoCommon ?? resolveRepoCommon(repository),
]);
if (!resolvedRepoCommon) return null;
if (currentHead.stdout.trim() !== head || currentBranch.stdout.trim() !== branch
|| await realpath(resolve(checkout, common.stdout.trim())) !== await realpath(resolve(repository, resolvedRepoCommon))) return null;
if (!same(pointer, await filesystemIdentity(join(checkout, '.git'), 'file'))
|| !same(administration, await filesystemIdentity(gitdir, 'directory'))) return null;
return { repoPath: repository, branch, path: checkout, head, incarnation: { pointer, gitdir: { path: gitdir, ...administration } } };
}
/** The repository a run's checkouts belong to. A claim run that picks its own
* branch runs in the source checkout itself, so its workspace is the
* repository and it records no separate sourceWorkspace.
*/
function runRepository(meta) {
if (typeof meta?.sourceWorkspace === 'string' && meta.sourceWorkspace) return meta.sourceWorkspace;
return hasClaimCheckoutBindings(meta) && meta.isWorktree !== true
&& typeof meta.workspacePath === 'string' && meta.workspacePath ? meta.workspacePath : null;
}
/** Invoked only at server-controlled registration/binding while the owner is
* active. Bind before creation reserves the branch; binding again afterward
* records its physical generation before work starts. A changed seed refuses.
*/
export async function captureCheckoutSeeds(agent) {
const prior = agent.metadata?.checkoutSeeds || [];
const rows = await captureCompletedCheckouts(agent, { success: true, strict: true, allowUncreated: true });
const seeds = [...prior];
for (const row of rows) {
const seed = checkoutSeedSchema.parse({ version: 1, agentId: agent.id, startedAt: agent.startedAt,
seededAt: new Date().toISOString(), repoPath: row.repoPath, branch: row.branch, path: row.path,
repository: await filesystemIdentity(row.repoPath, 'directory'), checkout: await filesystemIdentity(row.path, 'directory'),
incarnation: row.incarnation });
const existing = prior.find(value => value.branch === seed.branch);
if (existing) {
if (!same({ ...existing, seededAt: seed.seededAt }, seed)) throw new Error('checkout-seed-generation-changed');
} else seeds.push(seed);
}
return seeds;
}
/** A late capture has an actual late timestamp and a separately bound early
* physical generation; legacy v1 evidence retains its original time contract.
*/
export function completedCheckoutReceiptValid(agent, receipt) {
if (!receipt || receipt.agentId !== agent.id || receipt.startedAt !== agent.startedAt
|| !Number.isFinite(Date.parse(receipt.capturedAt)) || Date.parse(receipt.capturedAt) < Date.parse(agent.startedAt)) return false;
if (receipt.version === 1) return Date.parse(receipt.capturedAt) <= Date.parse(agent.completedAt);
if (receipt.version !== 2 || Date.parse(receipt.capturedAt) > Date.now()) return false;
return agent.metadata?.checkoutSeeds?.some(seed => checkoutSeedSchema.safeParse(seed).success
&& seed.agentId === agent.id && seed.startedAt === agent.startedAt && seed.seededAt === receipt.seededAt
&& Date.parse(seed.seededAt) >= Date.parse(agent.startedAt) && Date.parse(seed.seededAt) <= Date.parse(agent.completedAt) && seed.repoPath === receipt.repoPath
&& seed.branch === receipt.branch && seed.path === receipt.path && same(seed.incarnation, receipt.incarnation)) === true;
}
/** Read the final head only inside the pre-existing physical binding. No fetch
* or branch-name discovery is allowed after terminal ingestion.
*/
export async function captureSeededCompletionCheckouts(agent, { preterminal = false } = {}) {
if (preterminal && !['running', 'paused'].includes(agent.status)) return null;
const terminalAt = preterminal ? Date.now() : Date.parse(agent.completedAt);
const bound = hasClaimCheckoutBindings(agent.metadata) ? agent.metadata.claimBranches : [agent.metadata?.worktreeBranch];
const seeds = agent.metadata?.checkoutSeeds?.filter(seed => Array.isArray(bound) && bound.includes(seed.branch));
if (!Array.isArray(seeds) || !seeds.length) return null;
const receipts = [];
for (const seed of seeds) {
if (!checkoutSeedSchema.safeParse(seed).success || seed.agentId !== agent.id || seed.startedAt !== agent.startedAt
|| Date.parse(seed.seededAt) < Date.parse(agent.startedAt) || Date.parse(seed.seededAt) > terminalAt
|| !same(seed.repository, await filesystemIdentity(seed.repoPath, 'directory'))
|| !same(seed.checkout, await filesystemIdentity(seed.path, 'directory'))) return null;
const head = (await execGit(['rev-parse', '--verify', 'HEAD^{commit}'], seed.path, {
env: { ...process.env, GIT_NO_LAZY_FETCH: '1', GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' }, timeout: 5000,
})).stdout.trim();
// A physical seed survives later commits in the same checkout. Only a head
// observed while this execution still owned it may authorize late capture.
const terminal = agent.metadata?.checkoutCapture?.targets?.find(row => row.agentId === agent.id
&& row.startedAt === agent.startedAt && row.repoPath === seed.repoPath && row.branch === seed.branch
&& row.path === seed.path && same(row.incarnation, seed.incarnation)
&& Number.isFinite(Date.parse(row.capturedAt)) && Date.parse(row.capturedAt) >= Date.parse(agent.startedAt)
&& Date.parse(row.capturedAt) <= terminalAt);
if (!preterminal && (!terminal || terminal.head !== head)) return null;
const target = { repoPath: seed.repoPath, branch: seed.branch, path: seed.path, head };
const current = await readCompletedCheckoutIdentity(target);
if (!current || !same(current.incarnation, seed.incarnation)) return null;
receipts.push({ version: 2, agentId: agent.id, startedAt: agent.startedAt, seededAt: seed.seededAt,
capturedAt: new Date().toISOString(), ...current });
}
return receipts;
}
/** Called under the agent-state lock while the run still owns its current
* bindings. The caller's success flag enables identity capture, as at initial
* registration; it never changes the provider's execution/delivery verdict.
* Never manufacture evidence for historical releases.
* Capture errors withhold cleanup authority without breaking completion.
*/
export async function captureCompletedCheckouts(agent, { success, strict = false, allowUncreated = false } = {}) {
const meta = agent?.metadata;
if (success !== true || !['running', 'paused'].includes(agent?.status) || !agent.id
|| !Number.isFinite(Date.parse(agent.startedAt))) return [];
const repoPath = runRepository(meta);
if (!repoPath) return [];
const claim = hasClaimCheckoutBindings(meta);
const branches = claim ? meta.claimBranches : meta.isWorktree === true && meta.worktreeBranch ? [meta.worktreeBranch] : null;
if (!Array.isArray(branches)) return [];
const { listWorktrees } = await import('./worktreeManager.js');
const trees = await listWorktrees(repoPath).catch(error => {
if (strict) throw Object.assign(error, { checkoutCapture: { targets: [], unknown: true } });
return null;
});
if (!trees) return [];
const receipts = [];
const targets = [];
let incomplete = false;
let unknown = false;
for (const branch of new Set(branches)) {
if (typeof branch !== 'string' || !branch) continue;
const holders = trees.filter(tree => shortBranch(tree.branch) === branch);
if (holders.length !== 1) {
if (!allowUncreated || holders.length > 1) { incomplete = true; unknown = true; }
continue;
}
if (!claim) {
const recordedPath = typeof meta.workspacePath === 'string' ? await realpath(meta.workspacePath).catch(() => null) : null;
if (!recordedPath || await realpath(holders[0].path).catch(() => null) !== recordedPath) { incomplete = true; unknown = true; continue; }
}
const target = { repoPath, branch, path: holders[0].path, head: holders[0].head, worktrees: trees };
const first = await readCompletedCheckoutIdentity(target).catch(() => null);
if (!first) { incomplete = true; unknown = true; continue; }
// The original preterminal generation is retained even if the independent
// final read fails. Replay may compare this exact target, never infer one.
const snapshot = { version: 1, agentId: agent.id, startedAt: agent.startedAt, capturedAt: new Date().toISOString(), ...first };
targets.push(snapshot);
if (!same(first, await readCompletedCheckoutIdentity(target).catch(() => null))) { incomplete = true; continue; }
receipts.push(snapshot);
}
if (strict && incomplete) throw Object.assign(new Error('checkout-incarnation-unverified'), { checkoutCapture: { targets, unknown } });
return receipts;
}
/** Revalidate immediately before retirement as well as before archival. Older
* completed records, failures and reused checkout incarnations grant nothing.
*/
export async function hasCompletedCheckoutEvidence(records, target) {
if (!Array.isArray(records)) return false;
const current = await readCompletedCheckoutIdentity(target).catch(() => null);
if (!current) return false;
const scoped = (await Promise.all(records.map(async agent => {
const meta = agent?.metadata;
const branches = [meta?.worktreeBranch,
...(Array.isArray(meta?.claimBranches) ? meta.claimBranches : []),
...(Array.isArray(meta?.claimReleasedBranches) ? meta.claimReleasedBranches : [])];
const repoPath = runRepository(meta);
if (!branches.includes(current.branch) || !repoPath) return null;
return await realpath(repoPath).catch(() => null) === current.repoPath ? agent : null;
}))).filter(Boolean);
return scoped.some(agent => agent?.status === 'completed' && agent.result?.success === true
// A later run can reuse an existing checkout without changing its inode or
// head. Its failure/missing receipt supersedes the older success. Unknown
// ordering is also a hold; only an unambiguous newest owner can grant this.
&& scoped.every(other => other === agent || Date.parse(other.startedAt) < Date.parse(agent.startedAt))
&& hasClaimCheckoutBindings(agent.metadata) && Array.isArray(agent.metadata?.completedCheckouts)
&& agent.metadata.completedCheckouts.some(receipt => completedCheckoutReceiptValid(agent, receipt)
&& same(current, { repoPath: receipt.repoPath, branch: receipt.branch, path: receipt.path, head: receipt.head, incarnation: receipt.incarnation })));
}
/** A manual /claim session records no receipt (#12849). Its proof is the forge:
* a PR merged into the default branch whose head is exactly this checkout's head.
* Returns that PR and its merge time, or null — any read failure grants nothing.
*/
export async function readMergedClaimEvidence({ repoPath, branch, head, forgeAccount = null }) {
const { findMergedPullRequest, readRetirementForgeEvidence } = await import('./heldCheckoutReview.js');
const pr = await findMergedPullRequest(repoPath, branch, head, { forgeAccount }).catch(() => null);
if (!pr || !Number.isFinite(Date.parse(pr.mergedAt))) return null;
const forge = await readRetirementForgeEvidence(repoPath, branch, pr.url, { forgeAccount }).catch(() => null);
return forge?.prHead === head ? { prUrl: pr.url, mergedAt: pr.mergedAt } : null;
}