@khorsheed/dsh-ankh-guard 0.1.1 → 0.3.0

package/lib/types/restart-request.js

@@ -0,0 +1,128 @@
+/**
+ * In-process guarded-restart trigger for UI-grade callers (the mode
+ * switcher's host half). Dispatches on supervision — no live watchdog: the
+ * `restart` verb's self-contained stop→start→canary; supervised:
+ * `reconfigure`'s transactional cutover, the only safe way to change the
+ * launch command under a live watchdog (its respawn would otherwise fight
+ * the new command). The trigger shells out to this package's own CLI, so
+ * the gate chain (credential → preflight → marker/lock) keeps exactly one
+ * behavior source and the detached driver keeps its proven lifetime rules;
+ * the structured verdict returns through DSH_ANKH_VERDICT_FILE, never
+ * scraped from the human stderr text.
+ *
+ * Never import the CLI module from the plugin graph: a runtime edge pulls
+ * cli.ts into a shared tsdown chunk, evicting its code from lib/cli.js so
+ * the direct-invocation guard never fires and the built CLI silently exits
+ * 0 on every call (observed 2026-09-09; type-only imports are erased and
+ * stay safe).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readInstanceLaunch } from "./restart-context.js";
+import { liveWatchdogPid } from "./state-files.js";
+/** Bounded human detail carried alongside the structured verdict, for display. */
+const DETAIL_CAP = 4096;
+/**
+ * argv (after process.execPath) that runs this package's CLI with the given
+ * args — the same source/built split as the CLI's own cliInvocation, resolved
+ * from this module's directory (src/ and lib/ keep their entries side by
+ * side). The two copies must not be unified through an import: see the module
+ * doc for what a runtime edge into the CLI module does to the built bundle.
+ */
+function cliEntryArgs(args) {
+    // Check the FILE path, not the directory: '…/src' has no trailing
+    // separator and never matches '/src/' — cliInvocation gets this right
+    // because it tests the module file itself.
+    const modulePath = fileURLToPath(import.meta.url);
+    const here = dirname(modulePath);
+    if (modulePath.includes(`${sep}src${sep}`)) {
+        const tsx = join(resolve(here, '../../../node_modules'), 'tsx', 'dist', 'esm', 'index.mjs');
+        if (existsSync(tsx))
+            return ['--import', tsx, join(here, 'cli.ts'), ...args];
+        return [join(here, 'cli.ts'), ...args];
+    }
+    return [join(here, 'cli.js'), ...args];
+}
+/** Read the caller-side verdict file, or null when the CLI never wrote one. */
+function readVerdict(file) {
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof value.stage === 'string' && typeof value.reason === 'string'
+            ? { stage: value.stage, reason: value.reason }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate and dispatch one restart request through the guard's own gate
+ * chain. A refusal never stops the running instance.
+ * @param request - the successor command, target profile, and owning session.
+ * @param context - the guard's resolved state dir and credential repo.
+ * @returns the structured verdict with bounded human detail for display.
+ */
+export async function requestRestart(request, context) {
+    if (request.start.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'start (the successor launch command) is required', detail: '' };
+    }
+    if (request.profile.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'profile (the dsh profile to preflight) is required', detail: '' };
+    }
+    if (request.initiator.trim() === '') {
+        return { accepted: false, stage: 'usage', reason: 'initiator (the session id the restart report returns to) is required — never invent one', detail: '' };
+    }
+    const port = readInstanceLaunch(context.stateDir)?.port;
+    if (port === undefined) {
+        return { accepted: false, stage: 'usage', reason: "no instance launch record in the state dir — the guard does not know this instance's port", detail: '' };
+    }
+    const via = liveWatchdogPid(context.stateDir) === null ? 'restart' : 'reconfigure';
+    const argv = via === 'restart'
+        ? [
+            'restart', '--port', String(port), '--start', request.start, '--profile', request.profile,
+            '--initiator', request.initiator, '--state-dir', context.stateDir, '--repo', context.repoDir,
+        ]
+        : [
+            'reconfigure', '--start', request.start, '--profile', request.profile,
+            '--on-failure', 'restore-previous', '--initiator', request.initiator, '--state-dir', context.stateDir,
+        ];
+    const verdictDir = mkdtempSync(join(tmpdir(), 'ankh-restart-request-'));
+    const verdictFile = join(verdictDir, 'verdict.json');
+    // This instance's own supervision variables must not leak into the CLI's
+    // children: a WD_STATE_DIR would retarget every watchdog they spawn (the
+    // same scrub the restart verb applies to the instance it starts).
+    const env = { ...process.env, DSH_ANKH_VERDICT_FILE: verdictFile };
+    delete env.DSH_ANKH_RESTART_DRIVER;
+    for (const key of Object.keys(env)) {
+        if (key.startsWith('WD_'))
+            delete env[key];
+    }
+    try {
+        const { code, output } = await new Promise((resolvePromise, rejectPromise) => {
+            let captured = '';
+            const child = spawn(process.execPath, cliEntryArgs(argv), { stdio: ['ignore', 'pipe', 'pipe'], env });
+            const append = (chunk) => { if (captured.length < DETAIL_CAP)
+                captured += chunk.toString('utf8'); };
+            child.stdout.on('data', append);
+            child.stderr.on('data', append);
+            child.once('error', rejectPromise);
+            child.once('exit', exitCode => { resolvePromise({ code: exitCode, output: captured }); });
+        });
+        const detail = output.trim();
+        if (code === 0)
+            return { accepted: true, via, detail };
+        const verdict = readVerdict(verdictFile);
+        return {
+            accepted: false,
+            stage: verdict?.stage ?? 'unknown',
+            reason: verdict?.reason ?? detail.split('\n', 1)[0] ?? `guard CLI exited ${code ?? 'signal'}`,
+            detail,
+        };
+    }
+    finally {
+        rmSync(verdictDir, { recursive: true, force: true });
+    }
+}

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;
+}