@marcoscale98/piewf-cli 5.14.1-fork.1

package/dist/src/doctor-cleanup.js

@@ -0,0 +1,659 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { AGENT_STATES as CORE_AGENT_STATES, BUDGET_DIMENSIONS as CORE_BUDGET_DIMENSIONS, BUDGET_EVENT_TYPES as CORE_BUDGET_EVENT_TYPES, HARD_TERMINAL_RUN_STATES, RUN_STATES, errorText, isNodeError, isThinkingLevel, jsonValue, object, validateBudget, validateModelAliases, validateSchema } from "@marcoscale98/pi-extensible-workflows";
+import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, RunStore } from "@marcoscale98/pi-extensible-workflows/persistence";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REQUIRED_RUN_FILES = ["workflow.js", "state.json", "snapshot.json", "journal.json", "ownership.json", "worktrees.json", "borrowed-worktrees.json", "system-prompts.json"];
+const OPTIONAL_RUN_FILES = new Set(["result.json", "summary.json"]);
+const RUN_DIRECTORIES = new Set(["worktrees", ".system-prompts"]);
+const RUN_FILES = new Set([...REQUIRED_RUN_FILES, ...OPTIONAL_RUN_FILES]);
+// String-keyed views of the core vocabularies: persisted files are read as unknown, so membership is checked on plain strings.
+const AGENT_STATES = new Set(CORE_AGENT_STATES);
+const BUDGET_DIMENSIONS = new Set(CORE_BUDGET_DIMENSIONS);
+const BUDGET_EVENT_TYPES = new Set(CORE_BUDGET_EVENT_TYPES);
+function isList(value) { return Array.isArray(value); }
+function isRunState(value) { return RUN_STATES.some((candidate) => candidate === value); }
+function isAgentState(value) { return typeof value === "string" && AGENT_STATES.has(value); }
+function isToolCallState(value) { return ["running", "completed", "failed"].some((candidate) => candidate === value); }
+function isActivityKind(value) { return ["reasoning", "tool", "text"].some((candidate) => candidate === value); }
+function positiveDays(value) { if (!Number.isSafeInteger(value) || value < 1 || !Number.isFinite(value * DAY_MS))
+    throw new Error("older-than-days must be a positive integer"); return value; }
+function runItem(entry, action, reason) { return { sessionId: entry.sessionId, runId: entry.runId, action, state: entry.run.state, stateMtimeMs: entry.stateMtimeMs, path: entry.store.directory, ...(reason ? { reason } : {}) }; }
+function sameNames(left, right) { return left.length === right.length && left.every((value, index) => value === right[index]); }
+async function jsonFile(path) { return JSON.parse(await readFile(path, "utf8")); }
+async function requiredFile(path) { const info = await lstat(path); if (!info.isFile())
+    throw new Error(`Required artifact is not a regular file: ${path}`); }
+function stringList(value, label, nonEmpty = false) { if (!isList(value) || value.some((item) => typeof item !== "string" || (nonEmpty && !item)))
+    throw new Error(`${label} is invalid`); }
+function optionalString(value, label) { if (value !== undefined && typeof value !== "string")
+    throw new Error(`${label} is invalid`); }
+function nonNegativeInteger(value, label) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    throw new Error(`${label} is invalid`); }
+function positiveInteger(value, label) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+    throw new Error(`${label} is invalid`); }
+function finiteNumber(value, label) { if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+    throw new Error(`${label} is invalid`); }
+function model(value, label) { if (!object(value) || typeof value.provider !== "string" || !value.provider || typeof value.model !== "string" || !value.model || (value.thinking !== undefined && !isThinkingLevel(value.thinking)))
+    throw new Error(`${label} is invalid`); }
+function accounting(value, label) { if (!object(value))
+    throw new Error(`${label} is invalid`); for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost"])
+    finiteNumber(value[key], `${label}.${key}`); }
+function resourceSelectors(value, label) { if (value === undefined)
+    return; if (!object(value))
+    throw new Error(`${label} is invalid`); if (value.skills !== undefined)
+    stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined)
+    stringList(value.extensions, `${label}.extensions`); if (value.tools !== undefined)
+    stringList(value.tools, `${label}.tools`); }
+function agentDefinition(value, label) { if (!object(value))
+    throw new Error(`${label} is invalid`); optionalString(value.prompt, `${label}.prompt`); optionalString(value.description, `${label}.description`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !isThinkingLevel(value.thinking))
+    throw new Error(`${label}.thinking is invalid`); if (value.tools !== undefined)
+    stringList(value.tools, `${label}.tools`); if (value.skills !== undefined)
+    stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined)
+    stringList(value.extensions, `${label}.extensions`); }
+function optionalRole(value, label) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${label} is invalid`);
+}
+function validateScheduledOptions(value, label) { if (!object(value) || typeof value.label !== "string" || !value.label || typeof value.cwd !== "string" || !value.cwd)
+    throw new Error(`${label} is invalid`); optionalString(value.requestedLabel, `${label}.requestedLabel`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); stringList(value.tools, `${label}.tools`); if (value.skills !== undefined)
+    stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined)
+    stringList(value.extensions, `${label}.extensions`); if (value.contextFiles !== undefined)
+    stringList(value.contextFiles, `${label}.contextFiles`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !isThinkingLevel(value.thinking))
+    throw new Error(`${label}.thinking is invalid`); optionalRole(value.role, `${label}.role`); if (value.schema !== undefined)
+    validateSchema(value.schema, `${label}.schema`); if (value.retries !== undefined)
+    nonNegativeInteger(value.retries, `${label}.retries`); if (value.timeoutMs !== undefined && value.timeoutMs !== null)
+    positiveInteger(value.timeoutMs, `${label}.timeoutMs`); if (value.agentOptions !== undefined && (!object(value.agentOptions) || !jsonValue(value.agentOptions)))
+    throw new Error(`${label}.agentOptions is invalid`); if (value.agentIdentity !== undefined) {
+    if (!object(value.agentIdentity) || !isList(value.agentIdentity.structuralPath) || value.agentIdentity.structuralPath.some((part) => typeof part !== "string") || typeof value.agentIdentity.callSite !== "string")
+        throw new Error(`${label}.agentIdentity is invalid`);
+    positiveInteger(value.agentIdentity.occurrence, `${label}.agentIdentity.occurrence`);
+    optionalString(value.agentIdentity.parentBreadcrumb, `${label}.agentIdentity.parentBreadcrumb`);
+    optionalString(value.agentIdentity.worktreeOwner, `${label}.agentIdentity.worktreeOwner`);
+} }
+function validateSessionReference(value, label) { if (!object(value) || typeof value.transport !== "string" || !value.transport || typeof value.sessionId !== "string" || !value.sessionId || (value.locator !== undefined && !jsonValue(value.locator)))
+    throw new Error(`${label} is invalid`); }
+function validateAgentSetup(value, label) {
+    if (!object(value))
+        throw new Error(`${label} is invalid`);
+    stringList(value.hookNames, `${label}.hookNames`);
+    model(value.model, `${label}.model`);
+    stringList(value.tools, `${label}.tools`);
+    if (typeof value.cwd !== "string" || !value.cwd)
+        throw new Error(`${label}.cwd is invalid`);
+    if (value.resourceSelectors !== undefined)
+        resourceSelectors(value.resourceSelectors, `${label}.resourceSelectors`);
+}
+function validateAgent(value, label) {
+    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || !isAgentState(value.state))
+        throw new Error(`${label} is invalid`);
+    optionalString(value.systemPrompt, `${label}.systemPrompt`);
+    optionalString(value.prompt, `${label}.prompt`);
+    optionalString(value.label, `${label}.label`);
+    optionalString(value.parentId, `${label}.parentId`);
+    if (value.structuralPath !== undefined)
+        stringList(value.structuralPath, `${label}.structuralPath`);
+    optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`);
+    optionalString(value.worktreeOwner, `${label}.worktreeOwner`);
+    optionalString(value.role, `${label}.role`);
+    optionalString(value.requestedModel, `${label}.requestedModel`);
+    model(value.model, `${label}.model`);
+    stringList(value.tools, `${label}.tools`);
+    nonNegativeInteger(value.attempts, `${label}.attempts`);
+    if (value.attemptDetails !== undefined) {
+        if (!isList(value.attemptDetails))
+            throw new Error(`${label}.attemptDetails is invalid`);
+        for (const [index, attempt] of value.attemptDetails.entries()) {
+            const at = `${label}.attemptDetails[${String(index)}]`;
+            if (!object(attempt) || !Number.isSafeInteger(attempt.attempt) || Number(attempt.attempt) < 1 || typeof attempt.transport !== "string" || !attempt.transport || Object.hasOwn(attempt, "sessionId") || Object.hasOwn(attempt, "sessionFile"))
+                throw new Error(`${at} is invalid`);
+            validateAgentSetup(attempt.setup, `${at}.setup`);
+            if (attempt.session !== undefined) {
+                const session = attempt.session;
+                validateSessionReference(session, `${at}.session`);
+                if (session.transport !== attempt.transport)
+                    throw new Error(`${at}.session transport does not match attempt transport`);
+            }
+            accounting(attempt.accounting, `${at}.accounting`);
+            if (attempt.error !== undefined && (!object(attempt.error) || typeof attempt.error.code !== "string" || typeof attempt.error.message !== "string"))
+                throw new Error(`${at}.error is invalid`);
+        }
+    }
+    if (value.accounting !== undefined)
+        accounting(value.accounting, `${label}.accounting`);
+    if (value.toolCalls !== undefined) {
+        if (!isList(value.toolCalls))
+            throw new Error(`${label}.toolCalls is invalid`);
+        for (const [index, call] of value.toolCalls.entries())
+            if (!object(call) || typeof call.id !== "string" || !call.id || typeof call.name !== "string" || !call.name || !isToolCallState(call.state))
+                throw new Error(`${label}.toolCalls[${String(index)}] is invalid`);
+    }
+    if (value.activity !== undefined) {
+        if (!object(value.activity) || !isActivityKind(value.activity.kind) || typeof value.activity.text !== "string")
+            throw new Error(`${label}.activity is invalid`);
+    }
+    if (value.lastEventAt !== undefined)
+        finiteNumber(value.lastEventAt, `${label}.lastEventAt`);
+}
+function validateUsage(value, label) { if (!object(value))
+    throw new Error(`${label} is invalid`); for (const key of BUDGET_DIMENSIONS)
+    finiteNumber(value[key], `${label}.${key}`); }
+function validateBudgetEvents(value) { if (value === undefined)
+    return; if (!isList(value))
+    throw new Error("Persisted budget events are invalid"); for (const [index, event] of value.entries()) {
+    const label = `budgetEvents[${String(index)}]`;
+    if (!object(event) || typeof event.type !== "string" || !BUDGET_EVENT_TYPES.has(event.type) || !Number.isSafeInteger(event.budgetVersion) || Number(event.budgetVersion) < 1 || !isList(event.dimensions) || event.dimensions.some((dimension) => typeof dimension !== "string" || !BUDGET_DIMENSIONS.has(dimension)) || typeof event.at !== "number" || !Number.isFinite(event.at) || event.limits === undefined)
+        throw new Error(`${label} is invalid`);
+    validateUsage(event.usage, `${label}.usage`);
+    validateBudget(event.limits);
+} }
+function validateRunRecord(value) {
+    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !isRunState(value.state) || !isList(value.agents) || !isList(value.agentSessions) || Object.hasOwn(value, "nativeSessions"))
+        throw new Error("Persisted run state is invalid");
+    const agents = value.agents.map((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); return agent; });
+    const agentIds = new Set();
+    for (const agent of agents) {
+        const id = agent.id;
+        if (agentIds.has(id))
+            throw new Error(`Duplicate persisted agent ${id}`);
+        agentIds.add(id);
+    }
+    for (const agent of agents) {
+        const parentId = agent.parentId;
+        if (parentId !== undefined && !agentIds.has(parentId))
+            throw new Error("Persisted agent has a missing parent");
+        const seen = new Set();
+        let parent = parentId;
+        while (parent) {
+            if (seen.has(parent))
+                throw new Error("Persisted agent parent cycle");
+            seen.add(parent);
+            const parentAgent = agents.find((candidate) => candidate.id === parent);
+            parent = parentAgent?.parentId;
+        }
+    }
+    for (const [index, session] of value.agentSessions.entries())
+        validateSessionReference(session, `agentSessions[${String(index)}]`);
+    optionalString(value.parentRunId, "Persisted parent run");
+    optionalString(value.failedAt, "Persisted failed path");
+    const retry = value.retry;
+    if (retry !== undefined) {
+        if (!object(retry) || typeof retry.sourceRunId !== "string" || !retry.sourceRunId || typeof retry.lineageRootRunId !== "string" || !retry.lineageRootRunId)
+            throw new Error("Persisted retry provenance is invalid");
+        const sourceRunId = retry.sourceRunId;
+        stringList(retry.completedPaths, "Persisted retry completed paths");
+        stringList(retry.incompletePaths, "Persisted retry incomplete paths");
+        stringList(retry.namedWorktrees, "Persisted retry named worktrees");
+        if (value.parentRunId !== sourceRunId)
+            throw new Error("Persisted retry parent does not match its source");
+    }
+    optionalString(value.phase, "Persisted phase");
+    if (value.phaseHistory !== undefined) {
+        if (!isList(value.phaseHistory))
+            throw new Error("Persisted phase history is invalid");
+        for (const phase of value.phaseHistory) {
+            if (!object(phase) || typeof phase.phase !== "string" || !phase.phase)
+                throw new Error("Persisted phase history is invalid");
+            nonNegativeInteger(phase.afterAgent, "Persisted phase history afterAgent");
+        }
+    }
+    if (value.phaseHistoryIndex !== undefined)
+        nonNegativeInteger(value.phaseHistoryIndex, "Persisted phase history index");
+    if (value.activeShellsByPhase !== undefined) {
+        if (!isList(value.activeShellsByPhase))
+            throw new Error("Persisted phase shell activity is invalid");
+        for (const activity of value.activeShellsByPhase) {
+            if (!object(activity) || !Number.isSafeInteger(activity.phaseIndex) || Number(activity.phaseIndex) < -1)
+                throw new Error("Persisted phase shell activity is invalid");
+            positiveInteger(activity.active, "Persisted phase shell activity count");
+            finiteNumber(activity.startedAt, "Persisted phase shell activity start");
+        }
+    }
+    if (value.error !== undefined && (!object(value.error) || typeof value.error.code !== "string" || typeof value.error.message !== "string"))
+        throw new Error("Persisted run error is invalid");
+    validateBudget(value.budget);
+    if (value.budgetVersion !== undefined)
+        positiveInteger(value.budgetVersion, "Persisted budget version");
+    if (value.usage !== undefined)
+        validateUsage(value.usage, "Persisted usage");
+    validateBudgetEvents(value.budgetEvents);
+    if (value.events !== undefined) {
+        if (!isList(value.events))
+            throw new Error("Persisted run events are invalid");
+        for (const event of value.events)
+            if (!object(event) || typeof event.type !== "string" || typeof event.message !== "string")
+                throw new Error("Persisted run event is invalid");
+    }
+}
+function validateSnapshot(snapshot) {
+    if (!object(snapshot) || typeof snapshot.script !== "string" || !snapshot.script || !jsonValue(snapshot.args) || !object(snapshot.metadata) || typeof snapshot.metadata.name !== "string" || !snapshot.metadata.name || (snapshot.metadata.description !== undefined && typeof snapshot.metadata.description !== "string") || !object(snapshot.settings) || !Number.isSafeInteger(snapshot.settings.concurrency) || Number(snapshot.settings.concurrency) < 1 || Number(snapshot.settings.concurrency) > 16 || snapshot.settings.backgroundWidget !== undefined && typeof snapshot.settings.backgroundWidget !== "boolean" || snapshot.settings.worktreePostCreateCommand !== undefined && (!isList(snapshot.settings.worktreePostCreateCommand) || snapshot.settings.worktreePostCreateCommand.length === 0 || snapshot.settings.worktreePostCreateCommand.some((argument) => typeof argument !== "string" || !argument.trim())) || !isList(snapshot.models) || snapshot.models.some((modelName) => typeof modelName !== "string") || !isList(snapshot.tools) || snapshot.tools.some((tool) => typeof tool !== "string") || !isList(snapshot.agentTypes) || snapshot.agentTypes.some((agentType) => typeof agentType !== "string") || !isList(snapshot.schemas))
+        throw new Error("Persisted launch snapshot is invalid");
+    if (snapshot.identityVersion !== undefined)
+        positiveInteger(snapshot.identityVersion, "Persisted snapshot identity version");
+    optionalString(snapshot.settingsPath, "Persisted snapshot settings path");
+    if (snapshot.settingsSources !== undefined) {
+        if (!object(snapshot.settingsSources) || typeof snapshot.settingsSources.concurrency !== "string" || typeof snapshot.settingsSources.modelAliases !== "string" || snapshot.settingsSources.skills !== undefined && typeof snapshot.settingsSources.skills !== "string" || snapshot.settingsSources.extensions !== undefined && typeof snapshot.settingsSources.extensions !== "string" || snapshot.settingsSources.tools !== undefined && typeof snapshot.settingsSources.tools !== "string" || snapshot.settingsSources.worktreePostCreateCommand !== undefined && typeof snapshot.settingsSources.worktreePostCreateCommand !== "string")
+            throw new Error("Persisted snapshot settings sources are invalid");
+    }
+    const settingsRecord = snapshot.settings;
+    resourceSelectors({ skills: settingsRecord.skills, extensions: settingsRecord.extensions, tools: settingsRecord.tools }, "Persisted snapshot selectors");
+    validateBudget(snapshot.budget);
+    if (snapshot.modelAliases !== undefined)
+        validateModelAliases(snapshot.modelAliases);
+    if (settingsRecord.modelAliases !== undefined)
+        validateModelAliases(settingsRecord.modelAliases);
+    if (snapshot.phases !== undefined)
+        stringList(snapshot.phases, "Persisted snapshot phases");
+    if (snapshot.roles !== undefined) {
+        if (!object(snapshot.roles))
+            throw new Error("Persisted snapshot roles are invalid");
+        for (const [name, definition] of Object.entries(snapshot.roles))
+            agentDefinition(definition, `Persisted snapshot role ${name}`);
+    }
+    if (snapshot.projectRoles !== undefined)
+        stringList(snapshot.projectRoles, "Persisted snapshot project roles");
+    for (const [index, schema] of snapshot.schemas.entries())
+        validateSchema(schema, `Persisted snapshot schema[${String(index)}]`);
+}
+function validateJournal(value) { if (!object(value) || !object(value.completed) || (value.awaiting !== undefined && !object(value.awaiting)) || (value.decisions !== undefined && !object(value.decisions)))
+    throw new Error("Persisted workflow journal is invalid"); for (const operation of Object.values(value.completed))
+    if (!object(operation) || typeof operation.path !== "string" || !operation.path || !jsonValue(operation.value))
+        throw new Error("Persisted completed operation is invalid"); for (const checkpoint of Object.values(value.awaiting ?? {}))
+    if (!object(checkpoint) || typeof checkpoint.path !== "string" || !checkpoint.path || typeof checkpoint.name !== "string" || !checkpoint.name || typeof checkpoint.prompt !== "string" || !jsonValue(checkpoint.context))
+        throw new Error("Persisted awaiting checkpoint is invalid"); for (const decision of Object.values(value.decisions ?? {})) {
+    if (!object(decision) || decision.kind !== "budget" || typeof decision.proposalId !== "string" || !decision.proposalId || typeof decision.runId !== "string" || !decision.runId || !object(decision.previous) || !object(decision.proposed) || !Number.isSafeInteger(decision.budgetVersion) || Number(decision.budgetVersion) < 1)
+        throw new Error("Persisted budget decision is invalid");
+    validateUsage(decision.consumed, "Persisted budget decision usage");
+    validateBudget(decision.previous);
+    validateBudget(decision.proposed);
+} }
+async function validateSystemPrompts(store) {
+    const value = await jsonFile(store.systemPromptPath());
+    if (object(value) && value.version === 2) {
+        await store.systemPrompts();
+        return;
+    }
+    if (!object(value) || value.version !== 1 || !isList(value.entries))
+        throw new Error("Persisted system prompts are invalid");
+    for (const [index, entry] of value.entries.entries()) {
+        const label = `system-prompts.entries[${String(index)}]`;
+        if (!object(entry) || typeof entry.sessionId !== "string" || !entry.sessionId || !Number.isSafeInteger(entry.attempt) || Number(entry.attempt) < 1 || !Number.isSafeInteger(entry.turn) || Number(entry.turn) < 1 || typeof entry.prompt !== "string" || typeof entry.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(entry.sha256) || createHash("sha256").update(entry.prompt).digest("hex") !== entry.sha256)
+            throw new Error(`${label} is invalid`);
+    }
+}
+async function validateRunDirectory(store) {
+    const entries = await readdir(store.directory, { withFileTypes: true });
+    for (const entry of entries) {
+        if (RUN_DIRECTORIES.has(entry.name)) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error(`Run artifact is not a regular directory: ${join(store.directory, entry.name)}`);
+            continue;
+        }
+        if (!RUN_FILES.has(entry.name))
+            throw new Error(`Run inventory contains an unrecognized artifact: ${join(store.directory, entry.name)}`);
+        if (!entry.isFile() || entry.isSymbolicLink())
+            throw new Error(`Run artifact is not a regular file: ${join(store.directory, entry.name)}`);
+    }
+}
+function validateOwnershipRecord(value, label, ownershipIds) {
+    if (!object(value) || typeof value.id !== "string" || !value.id || ownershipIds.has(value.id) || typeof value.label !== "string" || !value.label || !isAgentState(value.state))
+        throw new Error(`${label} is invalid`);
+    optionalString(value.parentId, `${label}.parentId`);
+    optionalString(value.prompt, `${label}.prompt`);
+    validateScheduledOptions(value.options, `${label}.options`);
+}
+async function validateRunArtifacts(store, workflowScript, state) {
+    await validateRunDirectory(store);
+    for (const name of REQUIRED_RUN_FILES)
+        await requiredFile(join(store.directory, name));
+    if (await readFile(join(store.directory, "workflow.js"), "utf8") !== workflowScript)
+        throw new Error("Persisted workflow source does not match its launch snapshot");
+    await validateSystemPrompts(store);
+    const result = await jsonFile(join(store.directory, "result.json")).catch((error) => { if (isNodeError(error, "ENOENT"))
+        return undefined; throw error; });
+    if (result === undefined && state === "completed")
+        throw new Error("Completed run result is missing");
+    if (result !== undefined && !jsonValue(result))
+        throw new Error("Persisted workflow result is invalid");
+    validateJournal(await jsonFile(join(store.directory, "journal.json")));
+    const rawOwnership = await jsonFile(join(store.directory, "ownership.json"));
+    if (!isList(rawOwnership))
+        throw new Error("Persisted ownership records are invalid");
+    const ownershipIds = new Set();
+    const ownership = rawOwnership.map((record, index) => {
+        const label = `ownership[${String(index)}]`;
+        validateOwnershipRecord(record, label, ownershipIds);
+        ownershipIds.add(record.id);
+        return record;
+    });
+    for (const record of ownership)
+        if (record.parentId !== undefined && !ownershipIds.has(record.parentId))
+            throw new Error("Persisted ownership parent is missing");
+    await store.validateDeletionWorktrees();
+    const borrowed = await store.borrowedWorktrees();
+    await store.validateBorrowedWorktrees();
+    return borrowed.map(({ sourceRunId }) => ({ sourceRunId }));
+}
+async function sessionEntries(path) {
+    const info = await lstat(path);
+    if (!info.isDirectory())
+        throw new Error(`Session inventory is not a directory: ${path}`);
+    return readdir(path, { withFileTypes: true });
+}
+async function scanSession(cwd, sessionId, home, expectedLease) {
+    const path = join(projectSessionsDirectory(cwd, home), sessionId);
+    const rootEntries = await sessionEntries(path);
+    const runsEntry = rootEntries.find((entry) => entry.name === "runs");
+    if (!runsEntry || !runsEntry.isDirectory() || runsEntry.isSymbolicLink())
+        throw new Error(`Session inventory has no regular runs directory: ${path}`);
+    if (rootEntries.some((entry) => entry.name !== "runs"))
+        throw new Error(`Session inventory contains an unrecognized entry: ${path}`);
+    const runsPath = join(path, "runs");
+    const before = await sessionEntries(runsPath);
+    const runEntries = before.filter((entry) => entry.name !== "owner.json");
+    if (before.some((entry) => entry.name === "owner.json" && entry.isSymbolicLink()))
+        throw new Error(`Session ownership lease is not a regular file: ${runsPath}`);
+    for (const entry of runEntries)
+        if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith("."))
+            throw new Error(`Session inventory contains an unrecognized entry: ${join(runsPath, entry.name)}`);
+    const ownerPath = join(runsPath, "owner.json");
+    let liveLease = false;
+    if (expectedLease && expectedLease.path === ownerPath) {
+        const owned = await jsonFile(ownerPath);
+        if (!object(owned) || owned.token !== expectedLease.token)
+            throw new Error("Session ownership lease changed before deletion");
+    }
+    else
+        liveLease = await hasLiveSessionLease(cwd, sessionId, home);
+    const runs = [];
+    for (const entry of runEntries) {
+        const runId = entry.name;
+        const store = new RunStore(cwd, sessionId, runId, home);
+        try {
+            const beforeState = await stat(join(store.directory, "state.json"));
+            const loaded = await store.load();
+            validateRunRecord(loaded.run);
+            validateSnapshot(loaded.snapshot);
+            if (loaded.run.parentRunId !== undefined)
+                await store.validateParentRun(loaded.run.parentRunId);
+            if (loaded.run.retry)
+                await store.validateRetrySource();
+            const borrowed = await validateRunArtifacts(store, loaded.snapshot.script, loaded.run.state);
+            const afterState = await stat(join(store.directory, "state.json"));
+            if (beforeState.mtimeMs !== afterState.mtimeMs)
+                throw new Error("Persisted state changed while scanning");
+            const dependencies = new Set();
+            if (loaded.run.parentRunId !== undefined)
+                dependencies.add(loaded.run.parentRunId);
+            if (loaded.run.retry) {
+                dependencies.add(loaded.run.retry.sourceRunId);
+                dependencies.add(loaded.run.retry.lineageRootRunId);
+            }
+            for (const binding of borrowed)
+                dependencies.add(binding.sourceRunId);
+            if (dependencies.has(runId))
+                throw new Error("Persisted run depends on itself");
+            runs.push({ sessionId, runId, store, run: loaded.run, stateMtimeMs: afterState.mtimeMs, dependencies: [...dependencies] });
+        }
+        catch (error) {
+            throw new Error(`Run ${runId} is corrupt or incomplete: ${errorText(error)}`, { cause: error });
+        }
+    }
+    const after = await sessionEntries(runsPath);
+    const beforeNames = before.map(({ name }) => name).sort();
+    const afterNames = after.map(({ name }) => name).sort();
+    if (!sameNames(beforeNames, afterNames))
+        throw new Error("Session inventory changed while scanning");
+    const known = new Set(runs.map(({ runId }) => runId));
+    for (const run of runs)
+        for (const dependency of run.dependencies)
+            if (!known.has(dependency))
+                throw new Error(`Run ${run.runId} depends on missing run ${dependency}`);
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (runId) => {
+        if (visiting.has(runId))
+            throw new Error("Persisted run dependency cycle prevents safe cleanup");
+        if (visited.has(runId))
+            return;
+        visiting.add(runId);
+        const run = runs.find(({ runId: current }) => current === runId);
+        for (const dependency of run?.dependencies ?? [])
+            visit(dependency);
+        visiting.delete(runId);
+        visited.add(runId);
+    };
+    for (const run of runs)
+        visit(run.runId);
+    return { sessionId, path, runs, liveLease };
+}
+async function recheckCandidate(entry, cutoffMs) {
+    const before = await stat(join(entry.store.directory, "state.json")).catch(() => undefined);
+    if (!before)
+        return "State record disappeared before deletion";
+    const loaded = await entry.store.load().catch((error) => { throw new Error(`Candidate could not be reloaded: ${errorText(error)}`); });
+    validateRunRecord(loaded.run);
+    if (loaded.run.id !== entry.runId || loaded.run.state !== entry.run.state || !HARD_TERMINAL_RUN_STATES.has(loaded.run.state))
+        return "Candidate state changed before deletion";
+    const after = await stat(join(entry.store.directory, "state.json"));
+    if (before.mtimeMs !== after.mtimeMs || after.mtimeMs !== entry.stateMtimeMs)
+        return "Candidate state record changed before deletion";
+    if (after.mtimeMs >= cutoffMs)
+        return "Candidate is no longer older than the cutoff";
+    return undefined;
+}
+function planSession(scan, cutoffMs) {
+    if (scan.liveLease)
+        return { candidates: [], skipped: scan.runs.map((entry) => runItem(entry, "skipped", "Session has a live ownership lease")) };
+    const oldTerminal = new Set(scan.runs.filter(({ run, stateMtimeMs }) => HARD_TERMINAL_RUN_STATES.has(run.state) && stateMtimeMs < cutoffMs).map(({ runId }) => runId));
+    const protectedRuns = new Set();
+    const visit = (runId) => { if (protectedRuns.has(runId))
+        return; protectedRuns.add(runId); const entry = scan.runs.find(({ runId: current }) => current === runId); for (const dependency of entry?.dependencies ?? [])
+        visit(dependency); };
+    for (const entry of scan.runs)
+        if (!oldTerminal.has(entry.runId))
+            for (const dependency of entry.dependencies)
+                visit(dependency);
+    const skipped = [];
+    for (const entry of scan.runs) {
+        if (!HARD_TERMINAL_RUN_STATES.has(entry.run.state))
+            skipped.push(runItem(entry, "skipped", `Run state ${entry.run.state} is active or resumable`));
+        else if (entry.stateMtimeMs >= cutoffMs)
+            skipped.push(runItem(entry, "skipped", "State record is not older than the cutoff"));
+        else if (protectedRuns.has(entry.runId))
+            skipped.push(runItem(entry, "skipped", "A retained run depends on this run"));
+    }
+    return { candidates: scan.runs.filter(({ runId }) => oldTerminal.has(runId) && !protectedRuns.has(runId)), skipped };
+}
+function deletionOrder(_scan, candidates) {
+    const candidateIds = new Set(candidates.map(({ runId }) => runId));
+    const remaining = new Set(candidateIds);
+    const ordered = [];
+    while (remaining.size) {
+        const next = candidates.find((entry) => remaining.has(entry.runId) && !candidates.some((child) => remaining.has(child.runId) && child.dependencies.includes(entry.runId)));
+        if (!next)
+            throw new Error("Dependency cycle prevents safe cleanup");
+        ordered.push(next);
+        remaining.delete(next.runId);
+    }
+    return ordered;
+}
+async function storedSessionIds(cwd, home) {
+    const path = projectSessionsDirectory(cwd, home);
+    let entries;
+    try {
+        entries = await sessionEntries(path);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return [];
+        throw error;
+    }
+    if (entries.some((entry) => entry.isSymbolicLink()))
+        throw new Error(`Project session inventory contains a symbolic link: ${path}`);
+    const invalid = entries.find((entry) => !entry.isDirectory());
+    if (invalid)
+        throw new Error(`Project session inventory contains an unrecognized entry: ${join(path, invalid.name)}`);
+    return entries.filter((entry) => entry.isDirectory()).map(({ name }) => name).sort();
+}
+function addUnique(items, item) { if (!items.some((current) => current.sessionId === item.sessionId && current.runId === item.runId && current.action === item.action))
+    items.push(item); }
+function addFailure(items, sessionId, message, runId) { items.push({ sessionId, ...(runId ? { runId } : {}), message }); }
+export async function doctorCleanup(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const home = resolve(options.home ?? homedir());
+    const olderThanDays = positiveDays(options.olderThanDays ?? 90);
+    const yes = options.yes === true;
+    const now = options.now ?? Date.now();
+    if (!Number.isFinite(now))
+        throw new Error("Cleanup command start time is invalid");
+    const cutoffMs = now - olderThanDays * DAY_MS;
+    if (!Number.isFinite(cutoffMs) || !Number.isFinite(new Date(cutoffMs).getTime()))
+        throw new Error("older-than-days produces an unrepresentable cutoff");
+    const sessions = [];
+    const candidates = [];
+    const skipped = [];
+    const deleted = [];
+    const failures = [];
+    let sessionIds;
+    try {
+        sessionIds = await storedSessionIds(cwd, home);
+    }
+    catch (error) {
+        addFailure(failures, "(project)", errorText(error));
+        return { cwd, cutoffMs, olderThanDays, yes, sessions, candidates, skipped, deleted, failures };
+    }
+    for (const sessionId of sessionIds) {
+        let initial;
+        try {
+            initial = await scanSession(cwd, sessionId, home);
+        }
+        catch (error) {
+            sessions.push({ sessionId, path: join(projectSessionsDirectory(cwd, home), sessionId), status: "failed", reason: errorText(error) });
+            addFailure(failures, sessionId, errorText(error));
+            continue;
+        }
+        const initialPlan = planSession(initial, cutoffMs);
+        for (const item of initialPlan.candidates)
+            addUnique(candidates, runItem(item, "candidate"));
+        for (const item of initialPlan.skipped)
+            addUnique(skipped, item);
+        if (!yes || initial.liveLease) {
+            sessions.push({ sessionId, path: initial.path, status: initial.liveLease ? "skipped" : "preview", ...(initial.liveLease ? { reason: "Session has a live ownership lease" } : {}) });
+            continue;
+        }
+        let lease;
+        try {
+            lease = await acquireSessionLease(cwd, sessionId, home);
+        }
+        catch (error) {
+            const message = errorText(error);
+            if (/already owned|active ownership|RUN_OWNED/i.test(message)) {
+                sessions.push({ sessionId, path: initial.path, status: "skipped", reason: "Session has a live ownership lease" });
+                continue;
+            }
+            sessions.push({ sessionId, path: initial.path, status: "failed", reason: message });
+            addFailure(failures, sessionId, message);
+            continue;
+        }
+        try {
+            let current;
+            try {
+                current = await scanSession(cwd, sessionId, home, lease);
+            }
+            catch (error) {
+                const message = errorText(error);
+                sessions.push({ sessionId, path: initial.path, status: "failed", reason: message });
+                addFailure(failures, sessionId, message);
+                continue;
+            }
+            let freshPlan = planSession(current, cutoffMs);
+            for (const item of freshPlan.candidates)
+                addUnique(candidates, runItem(item, "candidate"));
+            const freshIds = new Set(freshPlan.candidates.map(({ runId }) => runId));
+            for (const item of initialPlan.candidates)
+                if (!freshIds.has(item.runId))
+                    addUnique(skipped, runItem(item, "skipped", "Candidate changed or is no longer independently eligible"));
+            let clean = true;
+            while (freshPlan.candidates.length) {
+                try {
+                    current = await scanSession(cwd, sessionId, home, lease);
+                    freshPlan = planSession(current, cutoffMs);
+                    for (const item of freshPlan.skipped)
+                        addUnique(skipped, item);
+                }
+                catch (error) {
+                    const message = errorText(error);
+                    addFailure(failures, sessionId, message);
+                    clean = false;
+                    break;
+                }
+                if (!freshPlan.candidates.length)
+                    break;
+                let ordered;
+                try {
+                    ordered = deletionOrder(current, freshPlan.candidates);
+                }
+                catch (error) {
+                    const message = errorText(error);
+                    addFailure(failures, sessionId, message);
+                    clean = false;
+                    break;
+                }
+                const target = ordered[0];
+                if (!target)
+                    break;
+                let changed;
+                try {
+                    changed = await recheckCandidate(target, cutoffMs);
+                }
+                catch (error) {
+                    const message = errorText(error);
+                    addFailure(failures, sessionId, message, target.runId);
+                    clean = false;
+                    break;
+                }
+                if (changed) {
+                    addUnique(skipped, runItem(target, "skipped", changed));
+                    clean = false;
+                    break;
+                }
+                try {
+                    await target.store.delete(true);
+                    deleted.push(runItem(target, "deleted"));
+                }
+                catch (error) {
+                    const message = errorText(error);
+                    addUnique(skipped, runItem(target, "failed", message));
+                    addFailure(failures, sessionId, message, target.runId);
+                    clean = false;
+                    break;
+                }
+            }
+            if (clean)
+                sessions.push({ sessionId, path: initial.path, status: "cleaned" });
+            else if (!sessions.some(({ sessionId: currentId }) => currentId === sessionId))
+                sessions.push({ sessionId, path: initial.path, status: "failed", reason: "Cleanup stopped after a safety recheck or deletion failure" });
+        }
+        finally {
+            try {
+                await lease.release();
+            }
+            catch (error) {
+                addFailure(failures, sessionId, errorText(error));
+            }
+        }
+    }
+    return { cwd, cutoffMs, olderThanDays, yes, sessions, candidates, skipped, deleted, failures };
+}
+export function doctorCleanupExitCode(report) { return report.failures.length ? 1 : 0; }
+function runLine(item) { return `- [${item.action}] session=${item.sessionId} run=${item.runId} state=${item.state} state-mtime=${new Date(item.stateMtimeMs).toISOString()} path=\`${item.path}\`${item.reason ? `: ${item.reason}` : ""}`; }
+export function formatDoctorCleanupReport(report) {
+    const lines = ["# pi-extensible-workflows doctor cleanup", "", "## Cleanup", `- Project: \`${report.cwd}\``, `- Cutoff: \`${new Date(report.cutoffMs).toISOString()}\` (strictly older than ${String(report.olderThanDays)} day(s))`, `- Mode: ${report.yes ? "confirmed deletion" : "preview only"}`, "", "## Candidates", ...(report.candidates.length ? report.candidates.map(runLine) : ["- None"]), "", "## Skipped", ...(report.skipped.length ? report.skipped.map(runLine) : ["- None"]), "", "## Deleted", ...(report.deleted.length ? report.deleted.map(runLine) : ["- None"]), "", "## Session safety", ...(report.sessions.length ? report.sessions.map((session) => `- [${session.status}] session=${session.sessionId} path=\`${session.path}\`${session.reason ? `: ${session.reason}` : ""}`) : ["- None stored"]), "", "## Failures", ...(report.failures.length ? report.failures.map((failure) => `- session=${failure.sessionId}${failure.runId ? ` run=${failure.runId}` : ""}: ${failure.message}`) : ["- None"]), "", "## Summary", `- ${String(report.candidates.length)} candidate(s), ${String(report.deleted.length)} deleted, ${String(report.skipped.length)} skipped, ${String(report.failures.length)} failure(s)`];
+    if (!report.yes)
+        lines.push("", "No files were changed. Re-run with --yes to confirm deletion.");
+    return `${lines.join("\n")}\n`;
+}