@khorsheed/dsh-ankh-guard 0.1.0 → 0.2.0

package/lib/types/preflight-runner.d.ts

@@ -5,10 +5,11 @@
  * deploy line) was wiped by the upstream reset and cannot be re-applied
  * without re-forking apps/cli on every release — which we cannot upstream
  * (no PR access). This runner replaces it WITHOUT touching the harness: it
- * resolves the official published packages (`@deepseek-ai/dsh-app-boot`,
- * `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from the LIVE
- * harness checkout's node_modules, so it always dry-runs the exact engine
- * the next boot will use and follows host updates automatically.
+ * resolves the official packages (`@deepseek-ai/dsh-app-boot`,
+ * `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from an explicit
+ * execution binding: source files in the host checkout for a source launch,
+ * or the npm toolchain selected by a built launch's dsh package.json. It never
+ * infers that choice from Node's execArgv.
  *
  * What it verifies (same contract as the old patch):
  * - the profile's full patch stack composes (bundle layers from
@@ -27,11 +28,17 @@
  *   error, env load failure): NOT a verdict on the composition.
  *
  * Run directly (any profile) or via the guard CLI:
- *   node --import <harness>/node_modules/tsx/dist/esm/index.mjs \
- *     packages/ankh-guard/src/preflight-runner.ts --profile web [--patch FILE]...
+ *   node packages/ankh-guard/lib/preflight-runner.js --profile web \
+ *     --host-surface built --install-anchor <toolchain>/node_modules/@deepseek-ai/dsh/package.json
  *
  * @module @khorsheed/dsh-ankh-guard/preflight-runner
  */
+export type PreflightHostSurface = 'source' | 'built';
+export interface PreflightHostBinding {
+    surface: PreflightHostSurface;
+    /** Real dsh package.json used by the successor's module graph. */
+    installAnchor: string;
+}
 /** The guarded (or tracking) harness checkout the live instance boots from. */
 export declare function resolveHarnessRoot(env?: Record<string, string | undefined>): string;
 /** The composed composition of one profile for a preflight (or a drift check). */
@@ -49,9 +56,12 @@ export interface PreflightComposition {
 /**
  * Compose one profile's full patch stack through the launcher's layering —
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
- * home-level user layer, `--patch` overlays, the agent-presets roots overlay,
- * then the telemetry switch. Exported so the drift tripwire can compare this
- * assembly against the launcher's own dump without booting anything.
+ * home-level user layer, `--patch` overlays, the agent-presets roots overlay
+ * (rc host line only; the 0.1.2 line's preset package self-ships its root),
+ * then the telemetry switch. Two host API generations are mirrored and
+ * feature-detected per run — see the `hostLine` branch below. Exported so
+ * the drift tripwire can compare this assembly against the launcher's own
+ * dump without booting anything.
  * @param profile - the profile name (same resolution as `--profile`).
  * @param patchFiles - `--patch` overlay paths, in argv order.
  * @param root - harness checkout root.
@@ -60,7 +70,7 @@ export interface PreflightComposition {
  * specific deployment must not silently compose a different home's tree.
  * @returns the patch stack and composed rows.
  */
-export declare function composePreflightPatches(profile: string, patchFiles: readonly string[], root: string, home?: string): Promise<PreflightComposition>;
+export declare function composePreflightPatches(profile: string, patchFiles: readonly string[], root: string, home?: string, binding?: PreflightHostBinding): Promise<PreflightComposition>;
 /**
  * Boot the profile's full tree once, tear it down, and report the verdict on
  * the process streams. No HMR, no user-patch watchers, no signal wiring —
@@ -70,11 +80,12 @@ export declare function composePreflightPatches(profile: string, patchFiles: rea
  * @param root - harness checkout root (default: DSH_HARNESS or ~/code/deepseek-harness).
  * @returns the process exit code (see the module contract).
  */
-export declare function runPreflight(profile: string, patchFiles?: readonly string[], root?: string): Promise<number>;
-/** Minimal argv parse for `--profile NAME` and repeatable `--patch FILE`. */
+export declare function runPreflight(profile: string, patchFiles?: readonly string[], root?: string, binding?: PreflightHostBinding): Promise<number>;
+/** Minimal argv parse; the host execution surface is mandatory and explicit. */
 export declare function parsePreflightArgs(argv: readonly string[]): {
     profile: string;
     patchFiles: string[];
+    binding?: PreflightHostBinding;
     error?: string;
 };
 //# sourceMappingURL=preflight-runner.d.ts.map

package/lib/types/preflight-runner.js

@@ -5,10 +5,11 @@
  * deploy line) was wiped by the upstream reset and cannot be re-applied
  * without re-forking apps/cli on every release — which we cannot upstream
  * (no PR access). This runner replaces it WITHOUT touching the harness: it
- * resolves the official published packages (`@deepseek-ai/dsh-app-boot`,
- * `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from the LIVE
- * harness checkout's node_modules, so it always dry-runs the exact engine
- * the next boot will use and follows host updates automatically.
+ * resolves the official packages (`@deepseek-ai/dsh-app-boot`,
+ * `dsh-home-paths`, `dsh-launch-environment`, `dsh-cmdline`) from an explicit
+ * execution binding: source files in the host checkout for a source launch,
+ * or the npm toolchain selected by a built launch's dsh package.json. It never
+ * infers that choice from Node's execArgv.
  *
  * What it verifies (same contract as the old patch):
  * - the profile's full patch stack composes (bundle layers from
@@ -27,8 +28,8 @@
  *   error, env load failure): NOT a verdict on the composition.
  *
  * Run directly (any profile) or via the guard CLI:
- *   node --import <harness>/node_modules/tsx/dist/esm/index.mjs \
- *     packages/ankh-guard/src/preflight-runner.ts --profile web [--patch FILE]...
+ *   node packages/ankh-guard/lib/preflight-runner.js --profile web \
+ *     --host-surface built --install-anchor <toolchain>/node_modules/@deepseek-ai/dsh/package.json
  *
  * @module @khorsheed/dsh-ankh-guard/preflight-runner
  */
@@ -40,9 +41,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { existsSync, mkdtempSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isDirectInvocation } from "./defaults.js";
 const NAME = 'dsh';
@@ -50,6 +52,17 @@ const PROFILE_ROOT_FILENAME = 'cordis.yml';
 const HOME_PATCH_FILENAME = 'cordis.patch.yml';
 const TELEMETRY_ROW_ID = 'session-telemetry-otel';
 const DSH_HARNESS_ENV = 'DSH_HARNESS';
+/**
+ * The empty root entry list every profile tree patches over — the exact
+ * bytes the launcher's prepareProfile rewrites on every boot (the vendored
+ * Loader's tree write-back can bake composed rows into this file, so both
+ * the launcher and this dry-run always start from the empty root).
+ */
+const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
+# --patch overlays. Edit cordis.patch.yml, not this file.
+[]
+`;
 /** The guarded (or tracking) harness checkout the live instance boots from. */
 export function resolveHarnessRoot(env = process.env) {
     const fromEnv = env[DSH_HARNESS_ENV];
@@ -67,18 +80,9 @@ const HARNESS_PACKAGE_DIRS = {
     '@deepseek-ai/dsh-cmdline': 'packages/boot/cmdline',
 };
 /**
- * Whether this runtime can import TypeScript sources (the runner is launched
- * through tsx; a plain-node consumer of the published package cannot).
- */
-function canImportTypeScript() {
-    return process.execArgv.some(arg => arg.includes('tsx'));
-}
-/**
- * Dynamically import a harness package from the live checkout, SOURCE FIRST:
- * a source-launched prod instance (tsx … apps/cli/src/bin.ts) boots the
- * source, so the preflight engine must be the source too — a stale `lib/`
- * must never make the preflight greener than the real boot. The built entry
- * is the fallback for harnesses that ship only artifacts.
+ * Dynamically import one host package from the explicitly selected surface.
+ * A source launch uses checkout source and fails rather than falling back to
+ * stale lib; a built launch resolves only through its npm install anchor.
  *
  * The composition layers below (bundle layers, user layers, overlays, the
  * agent-presets roots, the telemetry switch) mirror the launcher's private
@@ -90,27 +94,34 @@ function canImportTypeScript() {
  * @param name - package name (a key of {@link HARNESS_PACKAGE_DIRS}).
  * @returns the imported module.
  */
-async function loadHarnessPackage(root, name) {
+async function loadHarnessPackage(root, name, binding) {
+    if (binding.surface === 'built') {
+        let entry;
+        try {
+            entry = createRequire(binding.installAnchor).resolve(name);
+        }
+        catch (error) {
+            throw new Error(`built host package ${name} is not resolvable from ${binding.installAnchor}: ${String(error)}`, { cause: error });
+        }
+        return await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href));
+    }
     const relative = HARNESS_PACKAGE_DIRS[name];
     if (relative === undefined)
         throw new Error(`no known harness layout entry for ${name}`);
     const base = join(root, relative);
     const source = join(base, 'src', 'index.ts');
-    if (canImportTypeScript() && existsSync(source)) {
-        try {
-            return await import(__rewriteRelativeImportExtension(pathToFileURL(source).href));
-        }
-        catch (error) {
-            // A broken source import (syntax error, unresolved workspace dep) is
-            // EXACTLY what the next source boot would hit — surface it as a
-            // composition verdict, never silently fall back to a stale build.
-            throw new Error(`harness source ${source} failed to import (this is what a source boot would hit): ${String(error)}`, { cause: error });
-        }
+    if (!existsSync(source)) {
+        throw new Error(`harness source entry does not exist: ${source}`);
+    }
+    try {
+        return await import(__rewriteRelativeImportExtension(pathToFileURL(source).href));
+    }
+    catch (error) {
+        // A broken source import (syntax error, unresolved workspace dep) is
+        // EXACTLY what the next source boot would hit — surface it as a
+        // composition verdict, never silently fall back to a stale build.
+        throw new Error(`harness source ${source} failed to import (this is what a source boot would hit): ${String(error)}`, { cause: error });
     }
-    const manifest = JSON.parse(readFileSync(join(base, 'package.json'), 'utf8'));
-    const entry = manifest.main ?? 'lib/index.js';
-    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(join(base, entry)).href));
-    return module;
 }
 /** Thrown for harness-side load failures — preflight infrastructure, never a composition verdict. */
 class PreflightInfraError extends Error {
@@ -118,9 +129,12 @@ class PreflightInfraError extends Error {
 /**
  * Compose one profile's full patch stack through the launcher's layering —
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
- * home-level user layer, `--patch` overlays, the agent-presets roots overlay,
- * then the telemetry switch. Exported so the drift tripwire can compare this
- * assembly against the launcher's own dump without booting anything.
+ * home-level user layer, `--patch` overlays, the agent-presets roots overlay
+ * (rc host line only; the 0.1.2 line's preset package self-ships its root),
+ * then the telemetry switch. Two host API generations are mirrored and
+ * feature-detected per run — see the `hostLine` branch below. Exported so
+ * the drift tripwire can compare this assembly against the launcher's own
+ * dump without booting anything.
  * @param profile - the profile name (same resolution as `--profile`).
  * @param patchFiles - `--patch` overlay paths, in argv order.
  * @param root - harness checkout root.
@@ -129,12 +143,15 @@ class PreflightInfraError extends Error {
  * specific deployment must not silently compose a different home's tree.
  * @returns the patch stack and composed rows.
  */
-export async function composePreflightPatches(profile, patchFiles, root, home) {
+export async function composePreflightPatches(profile, patchFiles, root, home, binding = {
+    surface: 'source',
+    installAnchor: join(root, 'apps', 'cli', 'package.json'),
+}) {
     let appBoot;
     let homePaths;
     try {
-        appBoot = await loadHarnessPackage(root, '@deepseek-ai/dsh-app-boot');
-        homePaths = await loadHarnessPackage(root, '@deepseek-ai/dsh-home-paths');
+        appBoot = await loadHarnessPackage(root, '@deepseek-ai/dsh-app-boot', binding);
+        homePaths = await loadHarnessPackage(root, '@deepseek-ai/dsh-home-paths', binding);
     }
     catch (error) {
         throw new PreflightInfraError(`harness packages unavailable under ${root}: ${String(error)}`, { cause: error });
@@ -151,10 +168,30 @@ export async function composePreflightPatches(profile, patchFiles, root, home) {
     // healing then re-points fallback links into self-referential loops
     // (observed on a second preflight from the installed CLI: ~20 links looped,
     // the next real boot would have failed).
-    const anchor = join(root, 'apps', 'cli', 'package.json');
+    const anchor = binding.installAnchor;
     const resolvedHome = resolveDshHome(home);
-    healProfilesModuleFallback(anchor);
+    // Which app-boot API generation this host speaks. The 0.1.2 line re-layered
+    // the profile composition: the heal moved behind the async options API and
+    // below the profile load (see HealProfilesModuleFallback), and the launcher
+    // dropped its agent-presets shipped-root overlay because the preset package
+    // now self-ships its root. DEFAULT_PROFILE_PATCH_RELOAD is a value export
+    // only the new line carries, so it is the feature marker; a version parse
+    // would break on exactly the unreleased builds this runner must dry-run.
+    // Both lines stay supported: prod hosts run the rc line until 0.1.2 lands
+    // on npm.
+    const hostLine = 'DEFAULT_PROFILE_PATCH_RELOAD' in appBoot ? '0.1.2' : 'rc';
+    if (hostLine === 'rc')
+        healProfilesModuleFallback(anchor, resolvedHome);
     const composed = loadProfile(NAME, profile, anchor, resolvedHome, { userLayer: true });
+    // Mirror prepareProfile: rewrite the empty root config the tree patches
+    // over. The Loader needs the real file to anchor the include, and on a
+    // fresh home (the launcher never booted it) the file does not exist yet —
+    // the dry-run would otherwise fail on exactly the tree a first boot
+    // composes fine.
+    writeFileSync(join(composed.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+    if (hostLine === '0.1.2') {
+        await healProfilesModuleFallback({ installAnchor: anchor, profile: composed, home: resolvedHome });
+    }
     const homePatches = loadOptionalPatches(NAME, join(resolvedHome, HOME_PATCH_FILENAME)) ?? [];
     const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)));
     const bundlePatches = composed.layers.flatMap(layer => layer.patches);
@@ -165,12 +202,19 @@ export async function composePreflightPatches(profile, patchFiles, root, home) {
             rows.set(row.id, row);
     }
     const composedOverlays = [...overlays];
-    if (rows.has('agent-presets')) {
+    // The launcher's shipped preset root exists only on the rc line — the
+    // 0.1.2 line removed apps/cli/config/agent-presets and lets the preset
+    // package self-ship its root, so the overlay follows the directory, not
+    // the host line.
+    const shippedPresetRoot = binding.surface === 'built'
+        ? join(dirname(binding.installAnchor), 'config', 'agent-presets')
+        : join(root, 'apps', 'cli', 'config', 'agent-presets');
+    if (rows.has('agent-presets') && existsSync(shippedPresetRoot)) {
         composedOverlays.push({
             id: 'agent-presets',
             config: {
                 ...(rows.get('agent-presets')?.config ?? {}),
-                roots: [{ path: join(root, 'apps/cli/config/agent-presets/'), trust: 'system' }],
+                roots: [{ path: shippedPresetRoot, trust: 'system' }],
             },
         });
     }
@@ -210,6 +254,36 @@ export async function composePreflightPatches(profile, patchFiles, root, home) {
     patches.push(...composedOverlays);
     return { patches, rows, profileDir: composed.dir };
 }
+/**
+ * The launcher's readiness signal, mirrored: 0.1.2's runProfile provides an
+ * `appReady` service through provideCmdline and commits it once boot and host
+ * setup settle. The rc line's provideCmdline ignores the field, so one
+ * implementation serves both host lines.
+ */
+function createAppReadyStub() {
+    let committed = false;
+    const listeners = new Set();
+    return {
+        service: {
+            onReady(listener) {
+                if (committed) {
+                    listener();
+                    return () => { };
+                }
+                listeners.add(listener);
+                return () => { listeners.delete(listener); };
+            },
+        },
+        commit() {
+            if (committed)
+                return;
+            committed = true;
+            for (const listener of [...listeners])
+                listener();
+            listeners.clear();
+        },
+    };
+}
 /** Stat every registered client bundle; report one line per missing/unreadable artifact. */
 function missingClientArtifacts(ctx) {
     const registry = ctx.get?.('clientModules');
@@ -240,16 +314,19 @@ function missingClientArtifacts(ctx) {
  * @param root - harness checkout root (default: DSH_HARNESS or ~/code/deepseek-harness).
  * @returns the process exit code (see the module contract).
  */
-export async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot()) {
+export async function runPreflight(profile, patchFiles = [], root = resolveHarnessRoot(), binding = {
+    surface: 'source',
+    installAnchor: join(root, 'apps', 'cli', 'package.json'),
+}) {
     // Environment loading sits outside the composition pipeline; a failure here
     // is preflight infrastructure, not a verdict on the tree.
     let appBoot;
     let launchEnvironment;
     let cmdline;
     try {
-        appBoot = await loadHarnessPackage(root, '@deepseek-ai/dsh-app-boot');
-        launchEnvironment = await loadHarnessPackage(root, '@deepseek-ai/dsh-launch-environment');
-        cmdline = await loadHarnessPackage(root, '@deepseek-ai/dsh-cmdline');
+        appBoot = await loadHarnessPackage(root, '@deepseek-ai/dsh-app-boot', binding);
+        launchEnvironment = await loadHarnessPackage(root, '@deepseek-ai/dsh-launch-environment', binding);
+        cmdline = await loadHarnessPackage(root, '@deepseek-ai/dsh-cmdline', binding);
     }
     catch (error) {
         process.stderr.write(`preflight could not execute (harness packages unavailable under ${root}): ${error instanceof Error ? error.message : String(error)}\n`);
@@ -268,7 +345,7 @@ export async function runPreflight(profile, patchFiles = [], root = resolveHarne
         return 3;
     }
     try {
-        const composed = await composePreflightPatches(profile, patchFiles, root);
+        const composed = await composePreflightPatches(profile, patchFiles, root, undefined, binding);
         const patches = [...composed.patches];
         const rows = composed.rows;
         // Never collide with the live instance on its configured port: 0 asks the
@@ -282,12 +359,17 @@ export async function runPreflight(profile, patchFiles = [], root = resolveHarne
             });
         }
         const rootConfig = join(composed.profileDir, PROFILE_ROOT_FILENAME);
+        const appReady = createAppReadyStub();
         // Cloned for the same insert-aliasing reason the launcher documents: boot
         // application mutates rows by reference.
         const ctx = await boot(NAME, rootConfig, structuredClone(patches), (hostCtx) => {
             hostCtx.provide?.(launchEnvironmentKey, environment);
-            provideCmdline(hostCtx, { args: [], exit: () => { } });
+            provideCmdline(hostCtx, { args: [], exit: () => { }, ready: appReady.service });
         });
+        // The launcher commits readiness once boot and host setup settle; a
+        // dry-run's host setup is the no-op cmdline above, so boot settling is
+        // that point.
+        appReady.commit();
         const missing = missingClientArtifacts(ctx);
         // A repeated dispose returns the settled single-shot result when boot
         // already tore the tree down, so this is safe on every path.
@@ -310,10 +392,12 @@ export async function runPreflight(profile, patchFiles = [], root = resolveHarne
         return 1;
     }
 }
-/** Minimal argv parse for `--profile NAME` and repeatable `--patch FILE`. */
+/** Minimal argv parse; the host execution surface is mandatory and explicit. */
 export function parsePreflightArgs(argv) {
     const patchFiles = [];
     let profile = '';
+    let surface = '';
+    let installAnchor = '';
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--profile') {
@@ -324,20 +408,31 @@ export function parsePreflightArgs(argv) {
             if (file !== undefined)
                 patchFiles.push(file);
         }
+        else if (arg === '--host-surface') {
+            surface = argv[++i] ?? '';
+        }
+        else if (arg === '--install-anchor') {
+            installAnchor = argv[++i] ?? '';
+        }
         else if (arg === '--help' || arg === '-h') {
-            return { profile: '', patchFiles: [], error: 'usage: preflight-runner --profile <name> [--patch FILE]...' };
+            return { profile: '', patchFiles: [], error: 'usage: preflight-runner --profile <name> --host-surface source|built --install-anchor FILE [--patch FILE]...' };
         }
     }
     if (profile === '')
         return { profile: '', patchFiles: [], error: 'preflight requires --profile <name>' };
-    return { profile, patchFiles };
+    if (surface !== 'source' && surface !== 'built') {
+        return { profile, patchFiles, error: 'preflight requires --host-surface source|built' };
+    }
+    if (installAnchor === '')
+        return { profile, patchFiles, error: 'preflight requires --install-anchor FILE' };
+    return { profile, patchFiles, binding: { surface, installAnchor } };
 }
 // Standalone entry: only when executed directly (not imported by the CLI).
 if (isDirectInvocation(import.meta.url)) {
-    const { profile, patchFiles, error } = parsePreflightArgs(process.argv.slice(2));
-    if (error !== undefined) {
+    const { profile, patchFiles, binding, error } = parsePreflightArgs(process.argv.slice(2));
+    if (error !== undefined || binding === undefined) {
         process.stderr.write(`${error}\n`);
         process.exit(2);
     }
-    process.exitCode = await runPreflight(profile, patchFiles);
+    process.exitCode = await runPreflight(profile, patchFiles, resolveHarnessRoot(), binding);
 }

package/lib/types/processes.d.ts

@@ -1,5 +1,40 @@
+/** A PID plus the kernel-visible process start instant used to reject PID reuse. */
+export interface ProcessIdentity {
+    pid: number;
+    startToken: string;
+}
+/** The old supervisor's exact child root and the listener inside that tree. */
+export interface OwnedListener {
+    child: ProcessIdentity;
+    listener: ProcessIdentity;
+}
+/** Every process listening on a TCP port. An empty list also covers unavailable lsof. */
+export declare function findPidsOnPort(port: number): number[];
+/** TCP listen ports owned directly by one PID, using the same absolute lsof resolution. */
+export declare function listeningPortsForPid(pid: number): number[];
 /** The first process listening on a TCP port, or null when none is (via lsof). */
 export declare function findPidOnPort(port: number): string | null;
+/**
+ * Current identity for a live process, or null when it cannot be proved.
+ * Linux exposes a boot-scoped kernel start tick. Other POSIX hosts do not,
+ * so bind the start instant to the boot, uid, session, and settled command.
+ * This materially strengthens macOS ps(1)'s second-granularity lstart; all
+ * guard captures occur after the watchdog/child has reached its steady argv.
+ */
+export declare function processIdentity(pid: number): ProcessIdentity | null;
+/** Whether the same, non-recycled process is still alive. */
+export declare function processIdentityMatches(identity: ProcessIdentity): boolean;
+/** The live POSIX process-group id for one PID, or null when unavailable. */
+export declare function processGroupId(pid: number): number | null;
+/** Whether candidate is root itself or a live descendant of root. */
+export declare function pidBelongsToTree(root: number, candidate: number): boolean;
+/**
+ * Prove that exactly one port listener belongs to a supervisor and return the
+ * direct child root through which that supervisor owns it. This is captured
+ * before cutover; the successor must stop this identity, never an arbitrary
+ * process discovered later from the shared port.
+ */
+export declare function findOwnedListener(port: number, supervisorPid: number): OwnedListener | null;
 /**
  * Discover how the process on a port was launched — its exact argv from
  * `ps -o command=`, its cwd from lsof, and its DSH_* environment from
@@ -12,12 +47,9 @@ export declare function findPidOnPort(port: number): string | null;
  */
 export declare function discoverLaunchCommand(pid: string): string | null;
 /**
- * Kill a pid AND its descendants, deepest first (best effort). The supervised
- * instance may have forked children; a plain signal on the pid alone would
- * orphan them (the EADDRINUSE race the watchdog's EADDRINUSE branch exists
- * for). The process-group model is NOT assumed — the instance is not
- * setsid'd — so the sweep walks `pgrep -P` instead. `pgrep` missing or
- * returning nothing is fine: the pid itself still gets the signal.
+ * Freeze, then revalidate, then signal an authorized process identity. A
+ * mismatch resumes the PID without delivering the requested signal.
  */
+export declare function signalProcessIdentity(identity: ProcessIdentity, signal: NodeJS.Signals): 'signalled' | 'gone' | 'mismatch';
 export declare function killPidTree(pid: number, signal: NodeJS.Signals): void;
 //# sourceMappingURL=processes.d.ts.map