@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/types/state-files.d.ts

@@ -30,8 +30,26 @@ export declare const STATE_FILES: {
     readonly scheduleExitLog: "schedule-exit.log";
     /** How the current instance was launched (recorded by the plugin at apply). */
     readonly instanceLaunch: "instance-launch.json";
+    /** The atomically selected full launch configuration (stable or in cutover). */
+    readonly launchSpec: "launch-spec.json";
+    /** Redacted durable receipt for the latest launch-configuration cutover. */
+    readonly launchCutover: "launch-cutover.json";
+    /** Legacy combined operator-control marker, retained for rolling upgrades. */
+    readonly cutoverControl: "launch-cutover-control.json";
+    /** Operator → watchdog: abort according to the pre-approved recovery policy. */
+    readonly cutoverAbort: "launch-cutover-abort.json";
+    /** Monotonic stronger operator action: explicitly restore the previous spec. */
+    readonly cutoverRestorePrevious: "launch-cutover-restore-previous.json";
+    /** Original browser-tab registry: per-tab capability hashes only; retained through terminal recovery. */
+    readonly browserHandoffRequest: "browser-handoff-request.json";
+    /** Browser → watchdog acknowledgement for one proven final process. */
+    readonly browserHandoffAck: "browser-handoff-ack.json";
     /** Whether the restart-protocol skill registered at apply (and why not). */
     readonly skillRegistration: "skill-registration.json";
+    /** Directory: the healthy-boot snapshot of the profile composition inputs. */
+    readonly lastGoodComposition: "last-good-composition";
+    /** Directory prefix: a failing composition backed up before rollback restores over it. */
+    readonly compositionBackup: "composition-backup-";
 };
 /** A STATE_FILES key. */
 export type StateFileRole = keyof typeof STATE_FILES;
@@ -46,4 +64,16 @@ export declare function stateFile(stateDir: string, role: StateFileRole): string
  * @returns the stamped revision, or undefined.
  */
 export declare function lastGoodBootRevision(stateDir: string): string | undefined;
+/**
+ * Whether the pid named by this raw pid/lock-file content is alive. Empty
+ * content reads as NO holder: Number('') is 0 and kill(0, 0) probes our own
+ * process group (always succeeds), which once read as "alive" and refused
+ * every restart forever — the bug that had to be fixed in two copies of this
+ * logic before it was consolidated here.
+ */
+export declare function pidAlive(raw: string): boolean;
+/** The live pid named by a pid/lock file (as the raw string), or null when absent/stale. */
+export declare function livePidIn(file: string): string | null;
+/** The live supervising watchdog's pid, or null when none is (pidfile + kill 0). */
+export declare function liveWatchdogPid(stateDir: string): number | null;
 //# sourceMappingURL=state-files.d.ts.map

package/lib/types/state-files.js

@@ -11,6 +11,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { appendTestLifecycleEvent } from "./test-seam.js";
 /** Every state-directory file name, keyed by role. */
 export const STATE_FILES = {
     /** The guard's credential/checkpoint/audit state (state.ts). */
@@ -43,8 +44,26 @@ export const STATE_FILES = {
     scheduleExitLog: 'schedule-exit.log',
     /** How the current instance was launched (recorded by the plugin at apply). */
     instanceLaunch: 'instance-launch.json',
+    /** The atomically selected full launch configuration (stable or in cutover). */
+    launchSpec: 'launch-spec.json',
+    /** Redacted durable receipt for the latest launch-configuration cutover. */
+    launchCutover: 'launch-cutover.json',
+    /** Legacy combined operator-control marker, retained for rolling upgrades. */
+    cutoverControl: 'launch-cutover-control.json',
+    /** Operator → watchdog: abort according to the pre-approved recovery policy. */
+    cutoverAbort: 'launch-cutover-abort.json',
+    /** Monotonic stronger operator action: explicitly restore the previous spec. */
+    cutoverRestorePrevious: 'launch-cutover-restore-previous.json',
+    /** Original browser-tab registry: per-tab capability hashes only; retained through terminal recovery. */
+    browserHandoffRequest: 'browser-handoff-request.json',
+    /** Browser → watchdog acknowledgement for one proven final process. */
+    browserHandoffAck: 'browser-handoff-ack.json',
     /** Whether the restart-protocol skill registered at apply (and why not). */
     skillRegistration: 'skill-registration.json',
+    /** Directory: the healthy-boot snapshot of the profile composition inputs. */
+    lastGoodComposition: 'last-good-composition',
+    /** Directory prefix: a failing composition backed up before rollback restores over it. */
+    compositionBackup: 'composition-backup-',
 };
 /** Absolute path of a state file inside a state directory. */
 export function stateFile(stateDir, role) {
@@ -67,3 +86,39 @@ export function lastGoodBootRevision(stateDir) {
         return undefined;
     }
 }
+/**
+ * Whether the pid named by this raw pid/lock-file content is alive. Empty
+ * content reads as NO holder: Number('') is 0 and kill(0, 0) probes our own
+ * process group (always succeeds), which once read as "alive" and refused
+ * every restart forever — the bug that had to be fixed in two copies of this
+ * logic before it was consolidated here.
+ */
+export function pidAlive(raw) {
+    const pid = Number(raw);
+    if (raw === '' || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The live pid named by a pid/lock file (as the raw string), or null when absent/stale. */
+export function livePidIn(file) {
+    try {
+        const raw = readFileSync(file, 'utf8').trim();
+        return pidAlive(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The live supervising watchdog's pid, or null when none is (pidfile + kill 0). */
+export function liveWatchdogPid(stateDir) {
+    const raw = livePidIn(stateFile(stateDir, 'watchdogPid'));
+    const pid = raw === null ? null : Number(raw);
+    appendTestLifecycleEvent('watchdog-liveness-probe', { pid: pid ?? 0, live: pid !== null }, 'parent-observer');
+    return pid;
+}

package/lib/types/state.d.ts

@@ -9,6 +9,29 @@ export interface GuardCredential {
     /** The exact command that produced the green state. */
     command: string;
 }
+/**
+ * Durable proof that one exact deployment passed restart readiness + canary.
+ * Digests contain no command, profile content, or credential values.
+ */
+export interface ProvenDeployment {
+    version: 1;
+    provenAt: number;
+    credential: {
+        revision: string;
+        recordedAt: number;
+        scope: string;
+        commandSha256: string;
+    };
+    fingerprint: {
+        version: 1;
+        credentialRevision: string;
+        harnessRevision: string;
+        launchSpecSha256: string;
+        profileSha256: string;
+        hostRuntimeSha256: string;
+    };
+    fingerprintSha256: string;
+}
 /** A pre-batch snapshot commit the guard can reset back to. */
 export interface GuardCheckpoint {
     /** Commit SHA of the checkpoint. */
@@ -20,13 +43,14 @@ export interface GuardCheckpoint {
 }
 /** Append-only audit trail of state mutations (capped; verify is read-only). */
 export interface GuardAuditEntry {
-    action: 'record' | 'clear' | 'checkpoint';
+    action: 'record' | 'clear' | 'checkpoint' | 'prove-deployment';
     ts: number;
     detail: string;
 }
 /** The whole persisted state file. */
 export interface GuardState {
     credential?: GuardCredential;
+    provenDeployment?: ProvenDeployment;
     checkpoint?: GuardCheckpoint;
     audit: readonly GuardAuditEntry[];
 }
@@ -69,6 +93,8 @@ export declare function recordCredential(stateDir: string, input: RecordInput, n
  * @returns the persisted state.
  */
 export declare function clearCredential(stateDir: string, now: number): GuardState;
+/** Persist a deployment proof after the watchdog has completed its canary. */
+export declare function setProvenDeployment(stateDir: string, proof: ProvenDeployment, now: number): GuardState;
 /**
  * Persist a pre-batch checkpoint commit reference.
  * @param stateDir - state directory.
@@ -87,7 +113,8 @@ export declare function setCheckpoint(stateDir: string, input: {
  * @param currentRevision - the git HEAD of the checkout, or null when unavailable.
  * @param now - epoch milliseconds (injected for deterministic tests).
  * @param maxAgeMinutes - freshness window.
+ * @param workingTreeClean - whether staged, unstaged, and untracked inputs are absent.
  * @returns ok plus a human reason either way.
  */
-export declare function verifyCredential(state: GuardState, currentRevision: string | null, now: number, maxAgeMinutes: number): VerifyResult;
+export declare function verifyCredential(state: GuardState, currentRevision: string | null, now: number, maxAgeMinutes: number, workingTreeClean?: boolean): VerifyResult;
 //# sourceMappingURL=state.d.ts.map

package/lib/types/state.js

@@ -3,10 +3,9 @@
  *
  * The guard records one "green build" credential — bound to the git HEAD it
  * was recorded on and to a freshness window — and answers `verify()` against
- * the CURRENT head and wall clock. A self-restart may only proceed while the
- * credential is valid; the binding to HEAD means any tree change after
- * recording invalidates it, so a stale or post-hoc credential can never
- * authorize a restart of unverified code. Framework-free: the cordis plugin,
+ * the CURRENT head and wall clock. A later fully gated boot may promote that
+ * credential into a deployment proof whose exact runtime fingerprint can be
+ * reused by the same-launch restart path. Framework-free: the cordis plugin,
  * the CLI, and the invariant companion all share this module.
  */
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
@@ -33,11 +32,34 @@ function isCheckpoint(value) {
     const c = value;
     return typeof c.revision === 'string' && typeof c.recordedAt === 'number' && typeof c.message === 'string';
 }
+function isSha256(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+}
+function isProvenDeployment(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proof = value;
+    const credential = proof.credential;
+    const fingerprint = proof.fingerprint;
+    return proof.version === 1 && typeof proof.provenAt === 'number'
+        && credential !== undefined
+        && typeof credential.revision === 'string' && credential.revision !== ''
+        && typeof credential.recordedAt === 'number'
+        && typeof credential.scope === 'string'
+        && isSha256(credential.commandSha256)
+        && fingerprint?.version === 1
+        && typeof fingerprint.credentialRevision === 'string' && fingerprint.credentialRevision !== ''
+        && typeof fingerprint.harnessRevision === 'string' && fingerprint.harnessRevision !== ''
+        && isSha256(fingerprint.launchSpecSha256)
+        && isSha256(fingerprint.profileSha256)
+        && isSha256(fingerprint.hostRuntimeSha256)
+        && isSha256(proof.fingerprintSha256);
+}
 function isAuditEntry(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const e = value;
-    return (e.action === 'record' || e.action === 'clear' || e.action === 'checkpoint')
+    return (e.action === 'record' || e.action === 'clear' || e.action === 'checkpoint' || e.action === 'prove-deployment')
         && typeof e.ts === 'number' && typeof e.detail === 'string';
 }
 /**
@@ -56,6 +78,8 @@ export function loadState(stateDir) {
         const state = { audit };
         if (isCredential(parsed.credential))
             state.credential = parsed.credential;
+        if (isProvenDeployment(parsed.provenDeployment))
+            state.provenDeployment = parsed.provenDeployment;
         if (isCheckpoint(parsed.checkpoint))
             state.checkpoint = parsed.checkpoint;
         return state;
@@ -91,7 +115,10 @@ export function recordCredential(stateDir, input, now) {
     const credential = { ...input, recordedAt: now };
     const state = loadState(stateDir);
     const next = withAudit(state, { action: 'record', ts: now, detail: `${input.scope} @ ${input.revision}` });
-    const updated = { ...next, credential };
+    // A new proof attempt invalidates the old deployed-runtime proof even when
+    // it happens to target the same HEAD: ignored build outputs may be changing.
+    const { provenDeployment: _oldProof, ...withoutOldProof } = next;
+    const updated = { ...withoutOldProof, credential };
     saveState(stateDir, updated);
     return updated;
 }
@@ -110,6 +137,17 @@ export function clearCredential(stateDir, now) {
     saveState(stateDir, updated);
     return updated;
 }
+/** Persist a deployment proof after the watchdog has completed its canary. */
+export function setProvenDeployment(stateDir, proof, now) {
+    const state = loadState(stateDir);
+    const next = withAudit(state, {
+        action: 'prove-deployment', ts: now,
+        detail: `${proof.credential.revision} ${proof.fingerprintSha256.slice(0, 16)}`,
+    });
+    const updated = { ...next, provenDeployment: proof };
+    saveState(stateDir, updated);
+    return updated;
+}
 /**
  * Persist a pre-batch checkpoint commit reference.
  * @param stateDir - state directory.
@@ -132,15 +170,22 @@ export function setCheckpoint(stateDir, input, now) {
  * @param currentRevision - the git HEAD of the checkout, or null when unavailable.
  * @param now - epoch milliseconds (injected for deterministic tests).
  * @param maxAgeMinutes - freshness window.
+ * @param workingTreeClean - whether staged, unstaged, and untracked inputs are absent.
  * @returns ok plus a human reason either way.
  */
-export function verifyCredential(state, currentRevision, now, maxAgeMinutes) {
+export function verifyCredential(state, currentRevision, now, maxAgeMinutes, workingTreeClean = true) {
     const credential = state.credential;
     if (credential === undefined)
         return { ok: false, reason: 'no green-build credential recorded' };
     if (currentRevision === null) {
         return { ok: false, reason: 'current git HEAD unavailable (not inside a git repository?)' };
     }
+    if (!workingTreeClean) {
+        return {
+            ok: false,
+            reason: 'working tree is dirty (staged, unstaged, or untracked changes exist) — commit or remove them, then rebuild and re-record',
+        };
+    }
     if (credential.revision !== currentRevision) {
         return {
             ok: false,

package/lib/types/temp-artifact.d.ts

@@ -0,0 +1,15 @@
+import { type ProcessIdentity } from './processes.ts';
+/** Owner proof for a crash-left temporary artifact that may later be reaped. */
+export declare const TEMP_ARTIFACT_OWNER_FILE = ".ankh-guard-owner.json";
+export interface TempArtifactOwnerRecord {
+    version: 1;
+    kind: 'preflight-snapshot';
+    createdAt: number;
+    owner: ProcessIdentity;
+}
+/**
+ * Bind one private temporary artifact to the exact process identity creating
+ * it. A later reaper may remove the artifact only after this identity is gone.
+ */
+export declare function writeTempArtifactOwner(root: string, kind: TempArtifactOwnerRecord['kind']): TempArtifactOwnerRecord;
+//# sourceMappingURL=temp-artifact.d.ts.map

package/lib/types/temp-artifact.js

@@ -0,0 +1,17 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { processIdentity } from "./processes.js";
+/** Owner proof for a crash-left temporary artifact that may later be reaped. */
+export const TEMP_ARTIFACT_OWNER_FILE = '.ankh-guard-owner.json';
+/**
+ * Bind one private temporary artifact to the exact process identity creating
+ * it. A later reaper may remove the artifact only after this identity is gone.
+ */
+export function writeTempArtifactOwner(root, kind) {
+    const owner = processIdentity(process.pid);
+    if (owner === null)
+        throw new Error(`cannot capture temporary-artifact owner identity for pid ${process.pid}`);
+    const record = { version: 1, kind, createdAt: Date.now(), owner };
+    writeFileSync(join(root, TEMP_ARTIFACT_OWNER_FILE), `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+    return record;
+}

package/lib/types/test-seam-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=test-seam-cli.d.ts.map

package/lib/types/test-seam-cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Internal executable used only by dsh-watchdog.sh under an explicit test run. */
+import { appendTestLifecycleEventForProcess, registerCurrentTestProcess, registerTestProcess, TEST_PROCESS_ROLE_ENV, } from "./test-seam.js";
+const command = process.argv[2] ?? 'register';
+if (command === 'register-parent') {
+    const role = process.argv[3] ?? process.env[TEST_PROCESS_ROLE_ENV] ?? 'unknown';
+    registerTestProcess(process.ppid, role, { source: 'child-self' });
+}
+else if (command === 'event-parent') {
+    const role = process.argv[3] ?? process.env[TEST_PROCESS_ROLE_ENV] ?? 'unknown';
+    const event = process.argv[4] ?? 'unknown';
+    appendTestLifecycleEventForProcess(process.ppid, role, event);
+}
+else if (command === 'register-pid') {
+    const pid = Number(process.argv[3]);
+    const role = process.argv[4] ?? process.env[TEST_PROCESS_ROLE_ENV] ?? 'unknown';
+    registerTestProcess(pid, role, { source: 'child-self' });
+}
+else if (command === 'event-pid') {
+    const pid = Number(process.argv[3]);
+    const role = process.argv[4] ?? process.env[TEST_PROCESS_ROLE_ENV] ?? 'unknown';
+    const event = process.argv[5] ?? 'unknown';
+    appendTestLifecycleEventForProcess(pid, role, event);
+}
+else {
+    registerCurrentTestProcess();
+}

package/lib/types/test-seam.d.ts

@@ -0,0 +1,55 @@
+import { type ProcessIdentity } from './processes.ts';
+export declare const TEST_RUN_DIR_ENV = "ANKH_GUARD_TEST_RUN_DIR";
+export declare const TEST_RUN_TOKEN_ENV = "ANKH_GUARD_TEST_RUN_TOKEN";
+export declare const TEST_PROCESS_ROLE_ENV = "ANKH_GUARD_TEST_PROCESS_ROLE";
+export declare const TEST_PROCESS_PORT_ENV = "ANKH_GUARD_TEST_PROCESS_PORT";
+export declare const TEST_PROCESS_TEMP_ROOT_ENV = "ANKH_GUARD_TEST_PROCESS_TEMP_ROOT";
+export declare const TEST_REGISTER_BIN_ENV = "ANKH_GUARD_TEST_REGISTER_BIN";
+export declare const TEST_SLEEP_SCALE_ENV = "ANKH_GUARD_TEST_SLEEP_SCALE";
+export type TestObservationSource = 'child-self' | 'parent-observer' | 'node-exit-callback' | 'node-close-callback' | 'ps-sampler';
+export interface TestProcessLeaseRecord {
+    version: 1;
+    runToken: string;
+    role: string;
+    pid: number;
+    pgid: number;
+    startToken: string;
+    groupRoot: boolean;
+    registeredAt: number;
+    source: 'child-self' | 'parent-observer';
+    tempRoot?: string;
+    port?: number;
+}
+export interface TestLifecycleEvent {
+    version: 1;
+    runToken: string;
+    source: TestObservationSource;
+    role: string;
+    event: string;
+    pid: number;
+    pgid?: number;
+    startToken?: string;
+    wallTimeMs: number;
+    monotonicNs: string;
+    detail?: Record<string, string | number | boolean | null>;
+}
+interface RegisterOptions {
+    env?: NodeJS.ProcessEnv;
+    identity?: ProcessIdentity;
+    source?: 'child-self' | 'parent-observer';
+    tempRoot?: string;
+    port?: number;
+}
+export declare function appendTestLifecycleEventForProcess(subjectPid: number, roleValue: string, event: string, detail?: Record<string, string | number | boolean | null>, source?: TestObservationSource, env?: NodeJS.ProcessEnv): void;
+/** Record one credential-free event in this process's append-only event file. */
+export declare function appendTestLifecycleEvent(event: string, detail?: Record<string, string | number | boolean | null>, source?: TestObservationSource, env?: NodeJS.ProcessEnv): void;
+/**
+ * Atomically publish an immutable PID/PGID/start-identity lease. The same PID
+ * may be observed by its parent and then self-register; the first complete
+ * record wins because both describe the same kernel start identity.
+ */
+export declare function registerTestProcess(pid: number, role: string, options?: RegisterOptions): TestProcessLeaseRecord | null;
+/** Self-register only when an explicit test role accompanies the run lease. */
+export declare function registerCurrentTestProcess(env?: NodeJS.ProcessEnv): TestProcessLeaseRecord | null;
+export {};
+//# sourceMappingURL=test-seam.d.ts.map

package/lib/types/test-seam.js

@@ -0,0 +1,112 @@
+/**
+ * Explicit test-only process/event registration seam. Production execution is
+ * inert unless a test runner supplies all ANKH_GUARD_TEST_* ownership values.
+ */
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { processGroupId, processIdentity } from "./processes.js";
+export const TEST_RUN_DIR_ENV = 'ANKH_GUARD_TEST_RUN_DIR';
+export const TEST_RUN_TOKEN_ENV = 'ANKH_GUARD_TEST_RUN_TOKEN';
+export const TEST_PROCESS_ROLE_ENV = 'ANKH_GUARD_TEST_PROCESS_ROLE';
+export const TEST_PROCESS_PORT_ENV = 'ANKH_GUARD_TEST_PROCESS_PORT';
+export const TEST_PROCESS_TEMP_ROOT_ENV = 'ANKH_GUARD_TEST_PROCESS_TEMP_ROOT';
+export const TEST_REGISTER_BIN_ENV = 'ANKH_GUARD_TEST_REGISTER_BIN';
+export const TEST_SLEEP_SCALE_ENV = 'ANKH_GUARD_TEST_SLEEP_SCALE';
+function testCoordinates(env) {
+    const runDir = env[TEST_RUN_DIR_ENV];
+    const runToken = env[TEST_RUN_TOKEN_ENV];
+    if (runDir === undefined || runDir === '' || runToken === undefined || !/^[a-f0-9-]{16,}$/.test(runToken))
+        return null;
+    return { runDir, runToken };
+}
+function safeRole(value) {
+    const role = value.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 80);
+    return role === '' ? 'unknown' : role;
+}
+export function appendTestLifecycleEventForProcess(subjectPid, roleValue, event, detail, source = 'child-self', env = process.env) {
+    const coordinates = testCoordinates(env);
+    if (coordinates === null)
+        return;
+    const role = safeRole(roleValue);
+    const identity = processIdentity(subjectPid);
+    const pgid = processGroupId(subjectPid);
+    const record = {
+        version: 1,
+        runToken: coordinates.runToken,
+        source,
+        role,
+        event: safeRole(event),
+        pid: subjectPid,
+        ...(pgid === null ? {} : { pgid }),
+        ...(identity === null ? {} : { startToken: identity.startToken }),
+        wallTimeMs: Date.now(),
+        monotonicNs: process.hrtime.bigint().toString(),
+        ...(detail === undefined ? {} : { detail }),
+    };
+    try {
+        const dir = join(coordinates.runDir, 'events');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        appendFileSync(join(dir, `${subjectPid}-${source}.jsonl`), `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Diagnostics must never change the lifecycle under test.
+    }
+}
+/** Record one credential-free event in this process's append-only event file. */
+export function appendTestLifecycleEvent(event, detail, source = 'child-self', env = process.env) {
+    appendTestLifecycleEventForProcess(process.pid, env[TEST_PROCESS_ROLE_ENV] ?? 'unknown', event, detail, source, env);
+}
+/**
+ * Atomically publish an immutable PID/PGID/start-identity lease. The same PID
+ * may be observed by its parent and then self-register; the first complete
+ * record wins because both describe the same kernel start identity.
+ */
+export function registerTestProcess(pid, role, options = {}) {
+    const env = options.env ?? process.env;
+    const coordinates = testCoordinates(env);
+    if (coordinates === null)
+        return null;
+    const identity = options.identity ?? processIdentity(pid);
+    const pgid = processGroupId(pid);
+    if (identity === null || pgid === null)
+        return null;
+    const portText = env[TEST_PROCESS_PORT_ENV];
+    const envPort = portText === undefined ? undefined : Number(portText);
+    const port = options.port ?? (Number.isInteger(envPort) && (envPort ?? 0) > 0 ? envPort : undefined);
+    const tempRoot = options.tempRoot ?? env[TEST_PROCESS_TEMP_ROOT_ENV];
+    const record = {
+        version: 1,
+        runToken: coordinates.runToken,
+        role: safeRole(role),
+        pid,
+        pgid,
+        startToken: identity.startToken,
+        groupRoot: pgid === pid,
+        registeredAt: Date.now(),
+        source: options.source ?? (pid === process.pid ? 'child-self' : 'parent-observer'),
+        ...(tempRoot === undefined || tempRoot === '' ? {} : { tempRoot }),
+        ...(port === undefined ? {} : { port }),
+    };
+    try {
+        const dir = join(coordinates.runDir, 'processes');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const identityHash = createHash('sha256').update(identity.startToken).digest('hex').slice(0, 16);
+        writeFileSync(join(dir, `${pid}-${identityHash}.json`), `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            return null;
+    }
+    return record;
+}
+/** Self-register only when an explicit test role accompanies the run lease. */
+export function registerCurrentTestProcess(env = process.env) {
+    const role = env[TEST_PROCESS_ROLE_ENV];
+    if (role === undefined || role === '')
+        return null;
+    const record = registerTestProcess(process.pid, role, { env, source: 'child-self' });
+    if (record !== null)
+        appendTestLifecycleEvent('process-registered', { pgid: record.pgid }, 'child-self', env);
+    return record;
+}

package/lib/types/transition.d.ts

@@ -0,0 +1,118 @@
+/** One reversible filesystem operation approved before a cutover. */
+export interface TransitionOperation {
+    kind: 'quarantine';
+    /** Path relative to the shared previous/target dsh home. */
+    path: string;
+    /** State that both isolated preflight and live apply must observe. */
+    expect: 'present' | 'absent';
+}
+/** Caller-authored transition plan. Unknown operation kinds fail closed. */
+export interface TransitionPlan {
+    schemaVersion: 1;
+    /** Canonical dsh home containing every operation path. */
+    home: string;
+    operations: TransitionOperation[];
+}
+/** Immutable reference carried by the durable launch state and receipt. */
+export interface TransitionReference {
+    version: 1;
+    planPath: string;
+    planSha256: string;
+    operationCount: number;
+}
+type ApplyState = 'pending' | 'moving' | 'absent' | 'quarantined';
+type RollbackState = 'pending' | 'moving-target' | 'target-retained' | 'target-absent' | 'restoring' | 'restored';
+export type TransitionPhase = 'prepared' | 'applying' | 'applied' | 'rolling-back' | 'rolled-back' | 'failed';
+interface TransitionEntryState {
+    path: string;
+    original: 'present' | 'absent';
+    apply: ApplyState;
+    rollback: RollbackState;
+}
+/** Crash-recovery journal for one transition. */
+export interface TransitionRecord {
+    version: 1;
+    cutoverId: string;
+    planSha256: string;
+    phase: TransitionPhase;
+    entries: TransitionEntryState[];
+    updatedAt: number;
+    failure?: {
+        operation: 'apply' | 'rollback';
+        detail: string;
+    };
+}
+/** Result returned after an idempotent transition operation. */
+export interface TransitionResult {
+    phase: 'applied' | 'rolled-back';
+    changed: string[];
+    unchanged: string[];
+}
+/**
+ * Validate and normalize an untrusted transition plan.
+ * @param raw - Parsed JSON plan.
+ * @param expectedHome - Home shared by the previous and target launch specs.
+ * @param stateDir - Guard state directory, which no operation may move.
+ * @returns A canonical plan safe for durable preparation.
+ */
+export declare function validateTransitionPlan(raw: unknown, expectedHome: string, stateDir?: string): TransitionPlan;
+/**
+ * Persist the immutable plan and an empty crash-recovery journal before the previous host stops.
+ * @param raw - Validated or untrusted plan JSON.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Unique launch cutover identifier.
+ * @returns Reference stored in the launch state and redacted receipt.
+ */
+export declare function prepareTransition(raw: unknown, expectedHome: string, stateDir: string, cutoverId: string): TransitionReference;
+/**
+ * Apply a prepared transition after the previous host has stopped.
+ * @param reference - Immutable reference from the launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Active cutover identifier.
+ * @returns Idempotent apply result.
+ */
+export declare function applyTransition(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionResult;
+/**
+ * Roll back an applied or partially applied transition before previous starts.
+ * Target-created replacements are retained for diagnosis rather than deleted.
+ * @param reference - Immutable reference from the launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Active cutover identifier.
+ * @returns Idempotent rollback result.
+ */
+export declare function rollbackTransition(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionResult;
+/**
+ * Read and verify a transition record through its immutable reference.
+ * @param reference - Reference stored in launch state.
+ * @param expectedHome - Shared launch home.
+ * @param stateDir - Guard state directory.
+ * @param cutoverId - Cutover identifier.
+ * @returns Verified crash-recovery journal.
+ */
+export declare function readTransitionRecord(reference: TransitionReference, expectedHome: string, stateDir: string, cutoverId: string): TransitionRecord;
+/**
+ * Clone a live home while retaining a contained package-link graph. Internal
+ * links are rebuilt against copied nodes; external targets are deduplicated in
+ * a snapshot-owned materialization area. No retained link resolves outside the
+ * snapshot root, so writes through pnpm/Cordis links cannot reach live bytes.
+ * Runtime entries without copyable content (sockets, FIFOs — and links to
+ * them) are skipped and counted, never copied; the top-level scratch/ tree is
+ * excluded for size. Device nodes still fail closed.
+ * @param sourceHome - Live dsh home to read.
+ * @returns Isolated home, an idempotent cleanup callback, and the count of skipped runtime entries.
+ */
+export declare function createPreflightSnapshot(sourceHome: string): {
+    home: string;
+    root: string;
+    skippedRuntimeEntries: number;
+    cleanup(): void;
+};
+export declare function createTransitionPreflightSnapshot(plan: TransitionPlan): {
+    home: string;
+    cleanup(): void;
+};
+export {};
+//# sourceMappingURL=transition.d.ts.map