@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/scripts/m3-cohort.js

@@ -0,0 +1,310 @@
+#!/usr/bin/env tsx
+/**
+ * Explicit opt-in M3 seed-cohort capture CLI (issue #22).
+ *
+ * Produces the records `scripts/product-metrics.ts` consumes. The scorer is the only
+ * component that divides anything; this CLI only records funnel facts and then hands the
+ * written evidence root straight back to the scorer for verification.
+ *
+ * The production CLI intentionally has no `--at` flag: timestamps come from the local
+ * clock. Tests inject clocks through `../src/m3-cohort.ts`.
+ *
+ * HMAC key custody: `GOTRY_M3_COHORT_HMAC_KEY` (>= 32 chars) lives outside the repository
+ * and is never printed by this CLI. Losing it makes the store unreadable by design, and
+ * `verify` needs it too — the export attestation is keyed, not a public digest.
+ *
+ * Argv exposure (accepted, documented): `--participant`, `--plan` and `--consent` carry raw
+ * labels on the command line, so they are visible to `ps` and land in shell history. Only
+ * their HMAC refs are ever persisted, but the invocation itself is not secret. For a real
+ * cohort, drive this CLI from a script whose history is not shared, or export the labels
+ * from a file the shell does not record; never pass anything you would not put in `ps`.
+ *
+ *   npx tsx scripts/m3-cohort.ts init --state-root "$ROOT" --consent "$C" \
+ *     --cohort m3-seed --evidence-kind real_seed_cohort \
+ *     --window-start 2026-10-01T00:00:00.000Z --window-end 2026-12-31T23:59:59.000Z \
+ *     --timezone Asia/Shanghai --attribution gotry_primary
+ *   npx tsx scripts/m3-cohort.ts enroll   ... --participant <handle> --invited --participant-consent
+ *   npx tsx scripts/m3-cohort.ts deliver  ... --participant <handle> --plan <handle> --attribution gotry_primary
+ *   npx tsx scripts/m3-cohort.ts finalize ... --participant <handle> --plan <handle>
+ *   npx tsx scripts/m3-cohort.ts nps      ... --participant <handle> --plan <handle> --score 9
+ *   npx tsx scripts/m3-cohort.ts poi-lock ... --participant <handle> --plan <handle> --locked-claims 12 --invalid-claims 0
+ *   npx tsx scripts/m3-cohort.ts export   ... --evidence-root <dir>
+ *   npx tsx scripts/m3-cohort.ts verify   --evidence-root <dir>        # needs the HMAC key
+ *   npx tsx scripts/m3-cohort.ts lock-status --state-root "$ROOT"      # read-only
+ *   npx tsx scripts/m3-cohort.ts unlock     --state-root "$ROOT"       # dead writer only
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { enrollParticipant, exportM3Cohort, initM3Cohort, inspectStoreLock, M3CohortError, M3_SIMULATION_PROVENANCE_SCHEMA, recordNps, recordPlanDelivered, recordPlanFinalized, recordPoiLock, unlockStore, verifyExportedEvidence, } from '../src/m3-cohort.js';
+import { parseCohortRecord, parseManifest, scoreProductMetrics } from './product-metrics.js';
+const ERROR_CODES = [
+    'bad_args',
+    'cohort_already_initialized',
+    'cohort_consent_mismatch',
+    'cohort_key_mismatch',
+    'cohort_not_initialized',
+    'evidence_kind_mismatch',
+    'evidence_root_conflict',
+    'export_validation_failed',
+    'internal_error',
+    'invalid_hmac_key',
+    'invalid_input',
+    'invalid_store',
+    'invalid_transition',
+    'lock_busy',
+    'missing_consent',
+    'missing_hmac_key',
+    'missing_state_root',
+    'output_exists',
+    'simulation_forbidden_in_real_cohort',
+    'simulation_label_required',
+    'unsafe_state_root',
+];
+function parseFlags(args) {
+    const [command, ...rest] = args;
+    if (!command)
+        throw new M3CohortError('bad_args');
+    const flags = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (!token.startsWith('--'))
+            throw new M3CohortError('bad_args');
+        const key = token.slice(2);
+        if (!key)
+            throw new M3CohortError('bad_args');
+        const next = rest[index + 1];
+        const value = next === undefined || next.startsWith('--') ? true : (index += 1, next);
+        if (key in flags) {
+            const current = flags[key];
+            flags[key] = Array.isArray(current) ? [...current, value] : [current, value];
+        }
+        else {
+            flags[key] = value;
+        }
+    }
+    return { command, flags };
+}
+function one(flags, key, required = true) {
+    const value = flags[key];
+    if (Array.isArray(value) || value === true)
+        throw new M3CohortError('bad_args');
+    if (value === undefined && required)
+        throw new M3CohortError(key === 'state-root' ? 'missing_state_root' : 'invalid_input');
+    return value;
+}
+function many(flags, key) {
+    const value = flags[key];
+    if (value === undefined)
+        return [];
+    if (value === true)
+        throw new M3CohortError('bad_args');
+    const list = Array.isArray(value) ? value : [value];
+    return list.map(item => {
+        if (item === true)
+            throw new M3CohortError('bad_args');
+        return item;
+    });
+}
+function boolFlag(flags, key) {
+    const value = flags[key];
+    if (value === undefined)
+        return false;
+    if (value !== true)
+        throw new M3CohortError('bad_args');
+    return true;
+}
+function exclusiveBool(flags, trueKey, falseKey) {
+    const positive = boolFlag(flags, trueKey);
+    const negative = boolFlag(flags, falseKey);
+    if (positive === negative)
+        throw new M3CohortError('invalid_input');
+    return positive;
+}
+function integerFlag(flags, key) {
+    const raw = one(flags, key);
+    if (!/^\d{1,9}$/.test(raw))
+        throw new M3CohortError('invalid_input');
+    return Number(raw);
+}
+function common(flags) {
+    const stateRoot = one(flags, 'state-root');
+    const consent = one(flags, 'consent', false);
+    if (!consent)
+        throw new M3CohortError('missing_consent');
+    return { stateRoot: stateRoot, consent, hmacKey: process.env['GOTRY_M3_COHORT_HMAC_KEY'] };
+}
+function ensureNoUnknownFlags(flags, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(flags)) {
+        if (!allowedSet.has(key))
+            throw new M3CohortError('bad_args');
+    }
+}
+function attributionFlag(flags) {
+    const value = one(flags, 'attribution');
+    if (value !== 'gotry_primary' && value !== 'gotry_assisted')
+        throw new M3CohortError('invalid_input');
+    return value;
+}
+function attributionList(flags) {
+    const values = many(flags, 'attribution');
+    if (values.length === 0)
+        throw new M3CohortError('invalid_input');
+    return values.map(value => {
+        if (value !== 'gotry_primary' && value !== 'gotry_assisted')
+            throw new M3CohortError('invalid_input');
+        return value;
+    });
+}
+function simulationFlags(flags) {
+    const simulated = boolFlag(flags, 'simulated');
+    const personaId = one(flags, 'persona-id', false);
+    const productModel = one(flags, 'product-model', false);
+    const personaModel = one(flags, 'persona-model', false);
+    const promptDigest = one(flags, 'prompt-digest', false);
+    const provided = [personaId, productModel, personaModel, promptDigest];
+    if (!simulated) {
+        if (provided.some(value => value !== undefined))
+            throw new M3CohortError('invalid_input');
+        return undefined;
+    }
+    if (provided.some(value => value === undefined))
+        throw new M3CohortError('invalid_input');
+    return {
+        schema_version: M3_SIMULATION_PROVENANCE_SCHEMA,
+        kind: 'llm_persona',
+        persona_id: personaId,
+        product_model: productModel,
+        persona_model: personaModel,
+        prompt_digest: promptDigest,
+    };
+}
+function output(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** Consumer-side verification: the exact parsers and scorer the M3 gate uses. */
+export function scorerValidator(payload) {
+    const manifest = parseManifest(JSON.parse(JSON.stringify(payload.manifest)));
+    const cohort = payload.cohort.map((record, index) => parseCohortRecord(JSON.parse(JSON.stringify(record)), index));
+    const summary = scoreProductMetrics(manifest, cohort, []);
+    if (manifest.evidence_kind === 'synthetic_fixture' && summary.business_pass) {
+        throw new M3CohortError('export_validation_failed');
+    }
+}
+function run(command, flags) {
+    switch (command) {
+        case 'init': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'cohort', 'evidence-kind', 'window-start', 'window-end', 'timezone', 'attribution']);
+            const evidenceKind = one(flags, 'evidence-kind');
+            if (evidenceKind !== 'real_seed_cohort' && evidenceKind !== 'synthetic_fixture')
+                throw new M3CohortError('invalid_input');
+            output(initM3Cohort({
+                ...common(flags),
+                cohort: one(flags, 'cohort'),
+                evidenceKind,
+                windowStartAt: one(flags, 'window-start'),
+                windowEndAt: one(flags, 'window-end'),
+                timezone: one(flags, 'timezone'),
+                allowedAttribution: attributionList(flags),
+            }));
+            return;
+        }
+        case 'enroll': {
+            ensureNoUnknownFlags(flags, [
+                'state-root', 'consent', 'participant', 'invited', 'not-invited', 'participant-consent',
+                'participant-consent-withdrawn', 'test-or-staff', 'simulated', 'persona-id', 'product-model',
+                'persona-model', 'prompt-digest',
+            ]);
+            output(enrollParticipant({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                invited: exclusiveBool(flags, 'invited', 'not-invited'),
+                participantConsent: exclusiveBool(flags, 'participant-consent', 'participant-consent-withdrawn'),
+                testOrStaff: boolFlag(flags, 'test-or-staff'),
+                simulation: simulationFlags(flags),
+            }));
+            return;
+        }
+        case 'deliver': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'attribution']);
+            output(recordPlanDelivered({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                attribution: attributionFlag(flags),
+            }));
+            return;
+        }
+        case 'finalize': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan']);
+            output(recordPlanFinalized({ ...common(flags), participant: one(flags, 'participant'), plan: one(flags, 'plan') }));
+            return;
+        }
+        case 'nps': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'score']);
+            output(recordNps({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                score: integerFlag(flags, 'score'),
+            }));
+            return;
+        }
+        case 'poi-lock': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'participant', 'plan', 'locked-claims', 'invalid-claims']);
+            output(recordPoiLock({
+                ...common(flags),
+                participant: one(flags, 'participant'),
+                plan: one(flags, 'plan'),
+                lockedClaims: integerFlag(flags, 'locked-claims'),
+                invalidClaims: integerFlag(flags, 'invalid-claims'),
+            }));
+            return;
+        }
+        case 'export': {
+            ensureNoUnknownFlags(flags, ['state-root', 'consent', 'evidence-root']);
+            const evidenceRoot = one(flags, 'evidence-root');
+            const shared = common(flags);
+            const { payload, result } = exportM3Cohort({ ...shared, evidenceRoot, validate: scorerValidator });
+            // Verify the bytes that actually landed: re-read the evidence root through the real
+            // scorer parsers plus the keyed attestation check.
+            const manifest = parseManifest(JSON.parse(JSON.stringify(payload.manifest)));
+            const cohort = payload.cohort.map((record, index) => parseCohortRecord(JSON.parse(JSON.stringify(record)), index));
+            const summary = scoreProductMetrics(manifest, cohort, []);
+            const verification = verifyExportedEvidence(evidenceRoot, shared.hmacKey);
+            output({ ...result, verification, scorer_summary: summary });
+            return;
+        }
+        case 'verify': {
+            ensureNoUnknownFlags(flags, ['evidence-root']);
+            output(verifyExportedEvidence(one(flags, 'evidence-root'), process.env['GOTRY_M3_COHORT_HMAC_KEY']));
+            return;
+        }
+        case 'lock-status': {
+            ensureNoUnknownFlags(flags, ['state-root']);
+            output(inspectStoreLock(one(flags, 'state-root')));
+            return;
+        }
+        case 'unlock': {
+            ensureNoUnknownFlags(flags, ['state-root']);
+            output(unlockStore(one(flags, 'state-root')));
+            return;
+        }
+        default:
+            throw new M3CohortError('bad_args');
+    }
+}
+function main() {
+    try {
+        const { command, flags } = parseFlags(process.argv.slice(2));
+        run(command, flags);
+    }
+    catch (error) {
+        const code = error instanceof M3CohortError && ERROR_CODES.includes(error.code) ? error.code : 'internal_error';
+        process.stderr.write(`m3_cohort_error:${code}\n`);
+        process.exitCode = 2;
+    }
+}
+const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (import.meta.url === invokedPath)
+    main();

package/dist/scripts/managed-dsh-cleanup-diagnostic-proof.js

@@ -0,0 +1,184 @@
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { ManagedDshRunPort } from '../src/booking-surface/managed-dsh-run-port.js';
+import { ManagedDshCleanupError, managedDshGroupIsQuiescent, parseManagedDshGroupSnapshot, readManagedDshWorkerStart, snapshotManagedDshGroup, } from '../src/booking-surface/managed-dsh-cleanup-diagnostic.js';
+const workerPath = fileURLToPath(new URL('./fixtures/managed-dsh-worker-fixture.mjs', import.meta.url));
+async function proveFailedObservation(kind) {
+    const port = new ManagedDshRunPort({ workerPath, graceMs: 50, cleanupRole: kind === 'timeout' ? 'task' : 'warmer' });
+    // This seam injects an observation failure, not a real process-cleanup bug.
+    // Launch and termination still use the installed runtime and real child tree.
+    const handle = port.handle;
+    const waitForExit = handle.waitForExit.bind(handle);
+    try {
+        const result = await port.run('fixture', { sessionId: 'cleanup-diagnostic-proof' });
+        const descendant = result.events[0].grandchildPid;
+        handle.waitForExit = async () => {
+            if (kind === 'rejected')
+                throw new Error('PRIVATE_PROVIDER_TOKEN_DO_NOT_EXPOSE');
+            return false;
+        };
+        const closing = port.close();
+        assert.strictEqual(port.close(), closing, 'failure remains sticky for every close caller');
+        const error = await closing.then(() => undefined, (reason) => reason);
+        assert.ok(error instanceof ManagedDshCleanupError, 'failure carries a typed safe diagnostic');
+        const diagnostic = error.diagnostic;
+        assert.equal(diagnostic.role, kind === 'timeout' ? 'task' : 'warmer');
+        assert.equal(diagnostic.schemaVersion, 'managed-dsh-cleanup.v2');
+        if (process.platform === 'darwin')
+            assert.ok(Number.isSafeInteger(diagnostic.workerPid) && diagnostic.workerPid > 0, 'direct fallback receipt identifies the worker');
+        assert.equal(diagnostic.deadlineMs, 1_000, 'existing minimum teardown deadline is preserved');
+        assert.equal(diagnostic.graceMs, 50);
+        assert.ok(diagnostic.elapsedMs >= 0);
+        assert.ok(['pending', 'exited', 'failed'].includes(diagnostic.workerOutcome.state));
+        assert.equal(diagnostic.processGroup.expectedPgid, process.platform === 'darwin' ? diagnostic.workerPid : null);
+        assert.equal(JSON.stringify(error).includes('PRIVATE_'), false, 'provider observation errors are not forwarded');
+        const log = spawnSync(process.execPath, ['--input-type=module', '-e',
+            'let error = new Error(process.argv[1]); for (let i = 0; i < 3; i++) error = new AggregateError([error], "nested cleanup"); throw error',
+            error.message], { encoding: 'utf8', timeout: 5_000 });
+        assert.equal(log.status, 1, 'nested uncaught error child fails as intended');
+        assert.ok(log.stderr.includes(`diagnostic=${JSON.stringify(diagnostic)}`), 'default nested error log retains every safe diagnostic value');
+        assert.equal(log.stderr.includes('PRIVATE_'), false, 'nested log does not expose provider errors');
+        for (const member of diagnostic.processGroup.members) {
+            assert.equal(member.pgid, diagnostic.workerPid, 'only the owned process group is returned');
+            assert.deepEqual(Object.keys(member).sort(), ['pgid', 'pid', 'ppid', 'startedAt', 'state', 'zombie']);
+            assert.equal(member.zombie, member.state.startsWith('Z'), 'zombie flag matches the observed state letter');
+        }
+        if (kind === 'timeout' && diagnostic.processGroup.status === 'observed') {
+            // Right after terminate() the real fixture tree still holds live members,
+            // so the safe snapshot must classify it as not quiescent.
+            assert.equal(diagnostic.processGroup.classification, 'has-live-members');
+            assert.ok(diagnostic.processGroup.liveMemberCount >= 1);
+            assert.equal(managedDshGroupIsQuiescent(diagnostic.processGroup), false);
+        }
+        assert.equal(await waitForExit(AbortSignal.timeout(2_000)), true, 'actual runtime still reaps the worker tree');
+        if (process.platform !== 'win32')
+            assert.throws(() => process.kill(descendant, 0), 'grandchild is reaped');
+        console.log(`MANAGED DSH CLEANUP DIAGNOSTIC: ${kind} observation preserves ${diagnostic.role} identity and actual tree teardown`);
+    }
+    finally {
+        handle.waitForExit = waitForExit;
+        handle.terminate();
+        assert.equal(await waitForExit(AbortSignal.timeout(2_000)), true, 'proof cleans its own processes even after an assertion failure');
+    }
+}
+/** Classify crafted ps tables without signalling anything. */
+async function proveSyntheticClassification() {
+    const anchor = 'Sun Sep 20 19:59:16 2026';
+    const zombieOnly = parseManagedDshGroupSnapshot(' 4242 1 4242 Z    Sun Sep 20 19:59:16 2026', 4242, anchor);
+    assert.equal(zombieOnly.status, 'observed');
+    assert.equal(zombieOnly.classification, 'zombie-only');
+    assert.deepEqual([zombieOnly.liveMemberCount, zombieOnly.zombieMemberCount], [0, 1]);
+    assert.equal(zombieOnly.workerIdentity, 'match');
+    assert.equal(managedDshGroupIsQuiescent(zombieOnly), true, 'a group holding only un-reaped zombies is quiescent');
+    const reused = parseManagedDshGroupSnapshot(' 4242 1 4242 Z    Mon Dec 1 08:00:00 2025', 4242, anchor);
+    assert.equal(reused.workerIdentity, 'mismatch', 'a start time that differs from the live anchor proves PID reuse');
+    const live = parseManagedDshGroupSnapshot(' 4242 1 4242 Ss   Sun Sep 20 19:59:16 2026\n 4243 4242 4242 R    Sun Sep 20 19:59:17 2026', 4242, anchor);
+    assert.equal(live.classification, 'has-live-members');
+    assert.deepEqual([live.liveMemberCount, live.zombieMemberCount], [2, 0]);
+    assert.equal(live.workerIdentity, 'match');
+    assert.equal(managedDshGroupIsQuiescent(live), false);
+    const mixed = parseManagedDshGroupSnapshot(' 4242 1 4242 Z    Sun Sep 20 19:59:16 2026\n 4243 4242 4242 U    Sun Sep 20 19:59:17 2026', 4242, null);
+    assert.equal(mixed.classification, 'has-live-members', 'an uninterruptible member is live, never zombie');
+    assert.equal(mixed.workerIdentity, 'unknown', 'without a live anchor identity stays unknown');
+    const empty = parseManagedDshGroupSnapshot('', 4242, anchor);
+    assert.equal(empty.classification, 'empty');
+    assert.equal(managedDshGroupIsQuiescent(empty), true);
+    assert.equal(parseManagedDshGroupSnapshot('4243 1 999 Z Sun Sep 20 19:59:16 2026', 4242).classification, 'empty', 'foreign groups are excluded');
+    console.log('MANAGED DSH CLEANUP DIAGNOSTIC: synthetic tables classify zombie-only, live, uninterruptible, empty and reused identities');
+}
+/**
+ * A live process that never reaps its child keeps a real zombie inside its own
+ * process group for as long as it lives: `sh -c 'sleep 0.3 & exec sleep 600'`
+ * leaves the exited background job owned by the exec'd sleep.
+ */
+async function proveRealGroupClassification() {
+    if (process.platform !== 'darwin') {
+        console.log('MANAGED DSH CLEANUP DIAGNOSTIC: real group classification is Darwin-only, skipped');
+        return;
+    }
+    const holder = spawn('/bin/sh', ['-c', 'sleep 0.3 & exec sleep 600'], { detached: true, stdio: 'ignore' });
+    try {
+        const anchor = await readManagedDshWorkerStart(holder.pid);
+        assert.ok(anchor, 'live holder reports its start-time anchor');
+        const deadline = Date.now() + 2_000;
+        let group;
+        while (Date.now() < deadline) {
+            group = await snapshotManagedDshGroup(holder.pid, anchor);
+            if (group.status === 'observed' && group.zombieMemberCount >= 1)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        assert.equal(group.status, 'observed');
+        assert.equal(group.classification, 'has-live-members', 'a live member holding a zombie is not zombie-only');
+        assert.ok(group.liveMemberCount >= 1 && group.zombieMemberCount >= 1, 'the real group holds one live holder and one real zombie');
+        for (const member of group.members) {
+            assert.ok(member.startedAt, 'every real member carries a start time');
+            assert.equal(member.zombie, member.state.startsWith('Z'));
+        }
+        assert.equal(group.workerIdentity, 'match', 'the live anchor matches the observed holder identity');
+        assert.equal(managedDshGroupIsQuiescent(group), false);
+        console.log(`MANAGED DSH CLEANUP DIAGNOSTIC: real group ${holder.pid} classified with live holder and real zombie member`);
+    }
+    finally {
+        try {
+            process.kill(-holder.pid, 'SIGKILL');
+        }
+        catch { /* already gone */ }
+        const reaped = Date.now() + 2_000;
+        while (Date.now() < reaped) {
+            try {
+                process.kill(-holder.pid, 0);
+                await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            catch {
+                break;
+            }
+        }
+    }
+}
+/** The close verdict: an observation deadline plus a quiescent group is a successful cleanup, not a timeout. */
+async function proveCloseVerdict(classification) {
+    let observedPgid = null;
+    const port = new ManagedDshRunPort({
+        workerPath, graceMs: 50, cleanupRole: 'task',
+        groupObserver: async (pid) => {
+            observedPgid = pid;
+            const table = classification === 'empty' ? '' : ` ${pid} 1 ${pid} ${classification === 'zombie-only' ? 'Z' : 'Ss'}   Sun Sep 20 19:59:16 2026`;
+            return parseManagedDshGroupSnapshot(table, pid, null);
+        },
+    });
+    const handle = port.handle;
+    const waitForExit = handle.waitForExit.bind(handle);
+    try {
+        await port.run('fixture', { sessionId: 'cleanup-verdict-proof' });
+        handle.waitForExit = async () => false;
+        const closing = port.close();
+        if (classification === 'has-live-members') {
+            const error = await closing.then(() => undefined, (reason) => reason);
+            assert.ok(error instanceof ManagedDshCleanupError, 'a live member still converts the deadline into a failure');
+            assert.equal(error.message.split(';')[0], 'managed DSH process tree cleanup timeout');
+            assert.equal(error.diagnostic.processGroup.classification, 'has-live-members');
+            assert.equal(error.diagnostic.processGroup.liveMemberCount, 1);
+        }
+        else {
+            await closing;
+        }
+        assert.ok(Number.isInteger(observedPgid) && observedPgid > 0, 'the verdict observer receives the owned worker identity');
+        assert.equal(await waitForExit(AbortSignal.timeout(2_000)), true, 'the real runtime still reaps the tree in every verdict case');
+    }
+    finally {
+        handle.waitForExit = waitForExit;
+        handle.terminate();
+        assert.equal(await waitForExit(AbortSignal.timeout(2_000)), true, 'proof cleans its own processes even after an assertion failure');
+    }
+}
+await proveFailedObservation('timeout');
+await proveFailedObservation('rejected');
+await proveSyntheticClassification();
+await proveRealGroupClassification();
+await proveCloseVerdict('zombie-only');
+await proveCloseVerdict('empty');
+await proveCloseVerdict('has-live-members');
+assert.equal((await snapshotManagedDshGroup(null)).status, 'unknown_worker');
+console.log('MANAGED DSH CLEANUP DIAGNOSTIC PROOF: observation failures, zombie classification, identity anchors and verdict-by-quiescence OK');

package/dist/scripts/managed-dsh-close-failure-proof.js

@@ -0,0 +1,172 @@
+import assert from 'node:assert/strict';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local';
+import { ManagedDshRunPort } from '../src/booking-surface/managed-dsh-run-port.js';
+import { ManagedDshCleanupError } from '../src/booking-surface/managed-dsh-cleanup-diagnostic.js';
+const workerPath = fileURLToPath(new URL('./fixtures/managed-dsh-pending-worker-fixture.mjs', import.meta.url));
+function observe(promise) {
+    return promise.then((value) => ({ status: 'fulfilled', value }), (reason) => ({ status: 'rejected', reason }));
+}
+async function bounded(promise, timeoutMs, label) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(label)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function reasonMessage(reason) {
+    return reason instanceof Error ? reason.message : String(reason);
+}
+async function assertRejected(promise, expected, label) {
+    const outcome = await bounded(promise, 2_000, `${label}: close did not settle`);
+    assert.equal(outcome.status, 'rejected', `${label}: close must reject`);
+    const reason = outcome.reason;
+    // Since #518 close failures carry the typed safe diagnostic; the stable
+    // public meaning lives before its appended diagnostic payload.
+    assert.ok(reason instanceof ManagedDshCleanupError, `${label}: close failure carries the typed cleanup diagnostic`);
+    assert.equal(reason.message.split(';')[0], expected, `${label}: stable close error`);
+}
+async function settleInjectedHandle(port, originalWaitForExit, doneOutcome) {
+    const handle = port.handle;
+    handle.waitForExit = originalWaitForExit;
+    // The pinned fallback owner makes the real observation deterministic: the
+    // spawn never produced a child (no pid), so the owner's liveness probe is
+    // immediately false and confirmed-empty arrives without any provider-side
+    // wait. The bounded window stays as harness safety, not as a contract.
+    const rangeEmpty = await bounded(originalWaitForExit(AbortSignal.timeout(12_000)), 13_500, 'real handle cleanup did not settle');
+    assert.equal(rangeEmpty, true, 'real handle cleanup must confirm the range empty (deterministic fallback owner)');
+    const done = await bounded(doneOutcome, 2_500, 'real handle done did not settle');
+    assert.equal(done.status, 'rejected', 'real spawn-failure handle.done rejects');
+    await bounded(observe(port.close()), 2_500, 'sticky close promise did not settle');
+}
+const runtimeProto = LocalSubprocessRuntime.prototype;
+/**
+ * Construct the port with the runtime's PUBLIC test hooks pinned to the POSIX
+ * fallback owner for the one synchronous spawn the constructor performs.
+ * `platform: 'darwin'` routes selectContainmentMode away from the linux-scope
+ * owner whose uncancellable shared wait can hang the runner; the recorded
+ * `spawn` hook delegates to the real node spawn so the missing-cwd failure is
+ * genuine. Prototype and per-instance internals are restored before any
+ * asynchronous assertion can observe them.
+ */
+function constructPortWithFallbackOwner(options) {
+    const spawnCalls = [];
+    let pinnedInternals = null;
+    const originalProtoSpawn = runtimeProto.spawn;
+    runtimeProto.spawn = function (spec) {
+        pinnedInternals = this.internals;
+        const hadPlatform = Object.hasOwn(this.internals, 'platform');
+        const previousPlatform = this.internals.platform;
+        const previousSpawn = this.internals.spawn;
+        this.internals.platform = 'darwin';
+        this.internals.spawn = (program, args, opts) => {
+            spawnCalls.push({ program, args: [...args], options: opts });
+            return (previousSpawn ?? nodeSpawn)(program, args, opts);
+        };
+        try {
+            return originalProtoSpawn.call(this, spec);
+        }
+        finally {
+            if (previousSpawn !== undefined)
+                this.internals.spawn = previousSpawn;
+            else
+                delete this.internals.spawn;
+            if (hadPlatform)
+                this.internals.platform = previousPlatform;
+            else
+                delete this.internals.platform;
+        }
+    };
+    let port;
+    try {
+        port = new ManagedDshRunPort(options);
+    }
+    finally {
+        runtimeProto.spawn = originalProtoSpawn;
+    }
+    return { port, spawnCalls, pinnedInternals, prototypeRestored: runtimeProto.spawn === originalProtoSpawn };
+}
+async function proveCloseFailure(mode, expected, unhandled) {
+    const root = mkdtempSync(join(tmpdir(), `gotry-510-close-${mode}-`));
+    const missingCwd = join(root, 'missing-cwd');
+    const { port, spawnCalls, pinnedInternals, prototypeRestored } = constructPortWithFallbackOwner({
+        cwd: missingCwd,
+        workerPath,
+        graceMs: 50,
+    });
+    // Containment-selection coverage: the pinned platform hook must have routed
+    // this spawn through the POSIX fallback owner — the ordinary spawn hook
+    // fired exactly once for the real Node executable with the real missing
+    // cwd and detached POSIX options (the native linux-scope branch would have
+    // exec'd systemd-run instead).
+    assert.equal(spawnCalls.length, 1, `${mode}: ordinary spawn fired exactly once (fallback owner selected)`);
+    assert.equal(spawnCalls[0].program, process.execPath, `${mode}: real worker executable spawned`);
+    assert.equal(spawnCalls[0].args.at(-1), workerPath, `${mode}: real worker path spawned`);
+    assert.equal(spawnCalls[0].options.cwd, missingCwd, `${mode}: real missing cwd passed to the real spawn`);
+    assert.equal(spawnCalls[0].options.detached, true, `${mode}: detached POSIX fallback owner selected`);
+    // Hook restoration coverage: nothing observable of the test hooks may
+    // outlive the synchronous construction.
+    assert.ok(prototypeRestored, `${mode}: runtime prototype spawn restored`);
+    assert.ok(pinnedInternals !== null && !Object.hasOwn(pinnedInternals, 'platform') && !Object.hasOwn(pinnedInternals, 'spawn'), `${mode}: internals test hooks restored`);
+    const handle = port.handle;
+    const originalWaitForExit = handle.waitForExit.bind(handle);
+    const doneOutcome = observe(handle.done);
+    const unhandledAtStart = unhandled.length;
+    const injected = mode === 'reject'
+        ? () => Promise.reject(new Error('fault-injected observation failure'))
+        : () => Promise.resolve(false);
+    handle.waitForExit = injected;
+    try {
+        const closePromise = port.close();
+        const repeatedClosePromise = port.close();
+        assert.strictEqual(repeatedClosePromise, closePromise, `${mode}: repeated close returns one Promise`);
+        await assertRejected(observe(closePromise), expected, mode);
+        await assertRejected(observe(repeatedClosePromise), expected, `${mode} repeated close`);
+        await settleInjectedHandle(port, originalWaitForExit, doneOutcome);
+        // Give the real done rejection a turn to expose an unhandled derived
+        // outcome Promise. The proof itself observes every public close Promise.
+        await new Promise((resolve) => setImmediate(resolve));
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.equal(unhandled.length, unhandledAtStart, `${mode}: no unhandled rejection from close cleanup (${unhandled.slice(unhandledAtStart).map(reasonMessage).join('; ')})`);
+    }
+    finally {
+        handle.waitForExit = originalWaitForExit;
+        await bounded(observe(port.close()), 2_500, `${mode}: final cleanup did not settle`);
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const unhandled = [];
+const onUnhandled = (reason) => { unhandled.push(reason); };
+process.on('unhandledRejection', onUnhandled);
+try {
+    const failures = [];
+    for (const [mode, expected] of [
+        ['reject', 'managed DSH process tree observation failed'],
+        ['false', 'managed DSH process tree cleanup timeout'],
+    ]) {
+        try {
+            await proveCloseFailure(mode, expected, unhandled);
+        }
+        catch (error) {
+            failures.push(error);
+            console.error(`MANAGED DSH CLOSE FAILURE PROOF RED (${mode}):`, error);
+        }
+    }
+    if (failures.length > 0)
+        throw new AggregateError(failures, 'managed DSH close failure proof failed');
+    console.log('MANAGED DSH CLOSE FAILURE PROOF: observation reject/timeout are bounded, idempotent, and handled');
+}
+finally {
+    process.off('unhandledRejection', onUnhandled);
+}