@vibesdotdev/pm 0.0.0-stage → 1.0.0-rc.3

package/dist/utils/port-ownership.d.ts

@@ -0,0 +1,160 @@
+/**
+ * WHO OWNS A PORT — the proof PM requires before it signals a port holder.
+ *
+ * MEASURED DEFECT (2026-08-30/31, this workstation). A scratch PM daemon booted
+ * under a throwaway `VIBES_HOME` by `bun run smoke:shipping` found machine-global
+ * port 3000 held by ANOTHER LANE's `vibes dev mcp serve --mode http --port 3000`
+ * and SIGKILLed it. Three foreign MCP hosts died that way in one day (pids 39452,
+ * 42306, 80610); PM's `autoRestart` put a body back within ~80 s, which is exactly
+ * why the damage read as harmless. Running the shipping harness on a shared
+ * machine took out other people's MCP hosts.
+ *
+ * THE BUG WAS NEVER "the port was busy". It was that a command line which LOOKS
+ * like ours was accepted as proof that it IS ours (`isCommandLineMatch`), and —
+ * worse — that a holder matching NO config at all was killed outright as a
+ * "foreign process on our port". Two lanes on one machine run byte-identical
+ * argv, so similarity can never be ownership.
+ *
+ * THE RULE. A holder may be signalled only when PM can point at the record that
+ * says PM started it:
+ *   1. `tracked-pid`      — the pid this daemon's store recorded for this process
+ *                           id, or a descendant of it (`PortConflict.isOurs`);
+ *   2. `daemon-descendant`— a descendant of this daemon process;
+ *   3. `same-scope-signature` — a signature match AND the same SCOPE: the same
+ *                           working directory as the config being started AND
+ *                           the same `VIBES_HOME`. This is the leftover-from-a-
+ *                           previous-run case the old code was written for, and it
+ *                           stays supported: nothing is taken away.
+ * Anything else is FOREIGN. Foreign holders are refused LOUDLY by pid with a
+ * remedy — never signalled, never adopted.
+ *
+ * WHAT "SCOPE" MEANS, AND WHY IT IS TWO FACTS.
+ *   - cwd (`utils/process-tree.ts#resolveProcessCwd`) — PM sets `config.cwd` to
+ *     the workspace a managed process belongs to, so it discriminates two lanes
+ *     working in different checkouts.
+ *   - `VIBES_HOME` (`utils/process-tree.ts#resolveProcessScopeEnv`) — the home a
+ *     vibes process's state, sessions and daemons actually belong to. This is
+ *     the STRONGER fact and it is what the original incident turned on: a
+ *     scratch daemon booted under a throwaway `VIBES_HOME` killed a host in the
+ *     real home. cwd alone cannot see that difference — `vibes dev mcp start`
+ *     run from the developer root under a scratch home has the SAME cwd as the
+ *     real host, and (since the port is now derived from the shared root) the
+ *     same derived port too, so contention there is guaranteed rather than
+ *     accidental.
+ * An earlier version of this file asserted that a foreign process's environment
+ * is unreadable on macOS. That was measured FALSE on 2026-08-31: `ps -Eww -p
+ * <pid>` prints a same-uid process's environment (verified against live pids
+ * 4224 and 1194). The weaker discriminator was being used while the stronger
+ * one was available, so `same-scope-signature` could still authorize a SIGKILL
+ * of a stranger. Both facts are now required.
+ *
+ * UNREADABLE IS UNPROVEN. A cwd or an environment we cannot read is foreign:
+ * refusing costs a loud error, guessing costs someone else's running process.
+ * This only holds because `resolveProcessScopeEnv` distinguishes "read the
+ * environment, it names no VIBES_HOME" (an object) from "never got the
+ * environment" (`null`). Some processes DO withhold it while `ps` still exits 0
+ * — pid 1, and anything exec'd from a SIP-protected binary — and if that
+ * collapsed into `{vibesHome: null}` then `canonicalVibesHome` below would
+ * normalize the stranger into `<userHome>/.vibes` and this conjunct would
+ * silently degrade to the cwd-only rule it exists to replace. Measured, not
+ * reasoned: `ps -Eww -p 1 -o command=` → `/sbin/launchd`, exit 0, no env.
+ */
+import type { HostServicesRuntime } from './process-tree.ts';
+import { type PMFileSystem } from '../helpers/runtime-files.ts';
+import { type ProcessScopeEnv } from './process-tree.ts';
+export type OwnershipBasis = 'tracked-pid' | 'daemon-descendant' | 'same-scope-signature';
+export type PortOwnership = {
+    owned: true;
+    basis: OwnershipBasis;
+    holderCwd: string | null;
+} | {
+    owned: false;
+    reason: 'foreign-scope' | 'unproven-scope' | 'no-signature';
+    holderCwd: string | null;
+    /** Which scope fact failed, for the refusal message. */
+    mismatch?: 'cwd' | 'vibes-home' | 'workspace-path';
+};
+/**
+ * The scope THIS daemon belongs to, as its runtime declares it (framework-M8):
+ * the admitted workspace root it supervises (the launch cwd and the
+ * `VIBES_WORKSPACE_PATH` its children's custody carries), its vibes home
+ * (`getPathRoots(runtime).vibesHome`), and the user home an unset `VIBES_HOME`
+ * resolves against. Never read from this process's environment or cwd.
+ */
+export interface DaemonScope {
+    workspaceRoot: string;
+    vibesHome: string;
+    userHome: string;
+}
+export interface ProvePortOwnershipInput {
+    /** The runtime whose host process service observes the holder. */
+    runtime: HostServicesRuntime;
+    /** Pid holding the port. */
+    pid: number;
+    /** Already-established ownership from the caller's own state (store pid / descendants). */
+    isOurs: boolean;
+    /** Does the holder's command line look like the config we are about to start? */
+    signatureMatches: boolean;
+    /**
+     * `config.cwd` — the workspace domain this daemon owns for that process.
+     * A config that declares no cwd is launched in the daemon's admitted
+     * workspace root (launch custody), which `daemonScope` supplies.
+     */
+    configCwd?: string;
+    /**
+     * This daemon's declared scope. Absent, nothing about this daemon is known,
+     * so no holder can be proved ours by scope (`unproven-scope`).
+     */
+    daemonScope?: DaemonScope;
+    /** Pid of this PM daemon. Defaults to the supplied runtime host identity. */
+    daemonPid?: number;
+    /**
+     * The scope env a child of THIS daemon carries. Defaults to the daemon's
+     * declared scope (`daemonScope.vibesHome`, `daemonScope.workspaceRoot`).
+     */
+    ourScopeEnv?: ProcessScopeEnv;
+    /** Seams, for tests. */
+    resolveCwd?: (pid: number) => Promise<string | null>;
+    resolveScopeEnv?: (pid: number) => Promise<ProcessScopeEnv | null>;
+    isDescendant?: (childPid: number, parentPid: number) => Promise<boolean>;
+}
+/**
+ * An unset `VIBES_HOME` is not "unknown" — it resolves to `<userHome>/.vibes`.
+ * Normalizing both sides that way stops "we set it explicitly, they inherited
+ * the default" from reading as a foreign scope and silently withdrawing the
+ * leftover-reclaim capability. The user home is the daemon's declared one;
+ * without it an unset value cannot be resolved (null).
+ */
+export declare function canonicalVibesHome(files: PMFileSystem, value: string | null | undefined, userHome: string | undefined): Promise<string | null>;
+/**
+ * Resolve symlinks so `/var/folders/...` and `/private/var/folders/...` compare
+ * equal, through the handed filesystem's `realpath`. A path that does not exist
+ * is compared as written; a link loop is `pm-symlink-loop`; any other
+ * resolution failure is real and propagates.
+ */
+export declare function canonicalizePathOn(files: PMFileSystem, path: string | null | undefined): Promise<string | null>;
+export declare function provePortOwnership(input: ProvePortOwnershipInput): Promise<PortOwnership>;
+export interface ForeignHolderRefusalInput {
+    port: number;
+    pid: number;
+    command: string | null;
+    holderCwd: string | null;
+    ourCwd?: string;
+    /** Which scope fact failed, when the caller knows. */
+    mismatch?: 'cwd' | 'vibes-home' | 'workspace-path';
+    /**
+     * Why the proof failed. `unproven-scope` and `foreign-scope` are DIFFERENT
+     * facts — "we read it and it is someone else's" vs "we could not read it at
+     * all" — and an operator reading the log needs to know which, because only
+     * the second one might be fixable by giving PM more visibility.
+     */
+    reason?: 'foreign-scope' | 'unproven-scope' | 'no-signature';
+    /** How to make progress without touching the stranger. */
+    alternatePortHint?: string;
+}
+/**
+ * The refusal a caller prints or throws. It NAMES the pid, what it is, where it
+ * lives, and two remedies that do not involve PM signalling a stranger.
+ */
+export declare function formatForeignHolderRefusal(input: ForeignHolderRefusalInput): string;
+//# sourceMappingURL=port-ownership.d.ts.map

package/dist/utils/port-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-ownership.d.ts","sourceRoot":"","sources":["../../src/utils/port-ownership.ts"],"names":[],"mappings":"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"}

package/dist/utils/port-ownership.js

@@ -0,0 +1,176 @@
+/**
+ * WHO OWNS A PORT — the proof PM requires before it signals a port holder.
+ *
+ * MEASURED DEFECT (2026-08-30/31, this workstation). A scratch PM daemon booted
+ * under a throwaway `VIBES_HOME` by `bun run smoke:shipping` found machine-global
+ * port 3000 held by ANOTHER LANE's `vibes dev mcp serve --mode http --port 3000`
+ * and SIGKILLed it. Three foreign MCP hosts died that way in one day (pids 39452,
+ * 42306, 80610); PM's `autoRestart` put a body back within ~80 s, which is exactly
+ * why the damage read as harmless. Running the shipping harness on a shared
+ * machine took out other people's MCP hosts.
+ *
+ * THE BUG WAS NEVER "the port was busy". It was that a command line which LOOKS
+ * like ours was accepted as proof that it IS ours (`isCommandLineMatch`), and —
+ * worse — that a holder matching NO config at all was killed outright as a
+ * "foreign process on our port". Two lanes on one machine run byte-identical
+ * argv, so similarity can never be ownership.
+ *
+ * THE RULE. A holder may be signalled only when PM can point at the record that
+ * says PM started it:
+ *   1. `tracked-pid`      — the pid this daemon's store recorded for this process
+ *                           id, or a descendant of it (`PortConflict.isOurs`);
+ *   2. `daemon-descendant`— a descendant of this daemon process;
+ *   3. `same-scope-signature` — a signature match AND the same SCOPE: the same
+ *                           working directory as the config being started AND
+ *                           the same `VIBES_HOME`. This is the leftover-from-a-
+ *                           previous-run case the old code was written for, and it
+ *                           stays supported: nothing is taken away.
+ * Anything else is FOREIGN. Foreign holders are refused LOUDLY by pid with a
+ * remedy — never signalled, never adopted.
+ *
+ * WHAT "SCOPE" MEANS, AND WHY IT IS TWO FACTS.
+ *   - cwd (`utils/process-tree.ts#resolveProcessCwd`) — PM sets `config.cwd` to
+ *     the workspace a managed process belongs to, so it discriminates two lanes
+ *     working in different checkouts.
+ *   - `VIBES_HOME` (`utils/process-tree.ts#resolveProcessScopeEnv`) — the home a
+ *     vibes process's state, sessions and daemons actually belong to. This is
+ *     the STRONGER fact and it is what the original incident turned on: a
+ *     scratch daemon booted under a throwaway `VIBES_HOME` killed a host in the
+ *     real home. cwd alone cannot see that difference — `vibes dev mcp start`
+ *     run from the developer root under a scratch home has the SAME cwd as the
+ *     real host, and (since the port is now derived from the shared root) the
+ *     same derived port too, so contention there is guaranteed rather than
+ *     accidental.
+ * An earlier version of this file asserted that a foreign process's environment
+ * is unreadable on macOS. That was measured FALSE on 2026-08-31: `ps -Eww -p
+ * <pid>` prints a same-uid process's environment (verified against live pids
+ * 4224 and 1194). The weaker discriminator was being used while the stronger
+ * one was available, so `same-scope-signature` could still authorize a SIGKILL
+ * of a stranger. Both facts are now required.
+ *
+ * UNREADABLE IS UNPROVEN. A cwd or an environment we cannot read is foreign:
+ * refusing costs a loud error, guessing costs someone else's running process.
+ * This only holds because `resolveProcessScopeEnv` distinguishes "read the
+ * environment, it names no VIBES_HOME" (an object) from "never got the
+ * environment" (`null`). Some processes DO withhold it while `ps` still exits 0
+ * — pid 1, and anything exec'd from a SIP-protected binary — and if that
+ * collapsed into `{vibesHome: null}` then `canonicalVibesHome` below would
+ * normalize the stranger into `<userHome>/.vibes` and this conjunct would
+ * silently degrade to the cwd-only rule it exists to replace. Measured, not
+ * reasoned: `ps -Eww -p 1 -o command=` → `/sbin/launchd`, exit 0, no env.
+ */
+import { CapabilityError, getRuntimeHostIdentity } from '@vibesdotdev/kernel';
+import { DEFAULT_VIBES_HOME_DIRNAME } from '@vibesdotdev/paths';
+import { pmFileSystem, resolveExistingPrefix } from "../helpers/runtime-files.js";
+import { isDescendantOf, resolveProcessCwd, resolveProcessScopeEnv } from "./process-tree.js";
+/**
+ * An unset `VIBES_HOME` is not "unknown" — it resolves to `<userHome>/.vibes`.
+ * Normalizing both sides that way stops "we set it explicitly, they inherited
+ * the default" from reading as a foreign scope and silently withdrawing the
+ * leftover-reclaim capability. The user home is the daemon's declared one;
+ * without it an unset value cannot be resolved (null).
+ */
+export async function canonicalVibesHome(files, value, userHome) {
+    const explicit = value?.trim();
+    if (explicit && explicit.length > 0)
+        return canonicalizePathOn(files, explicit);
+    return userHome ? canonicalizePathOn(files, files.join(userHome, DEFAULT_VIBES_HOME_DIRNAME)) : null;
+}
+/**
+ * Resolve symlinks so `/var/folders/...` and `/private/var/folders/...` compare
+ * equal, through the handed filesystem's `realpath`. A path that does not exist
+ * is compared as written; a link loop is `pm-symlink-loop`; any other
+ * resolution failure is real and propagates.
+ */
+export async function canonicalizePathOn(files, path) {
+    if (!path)
+        return null;
+    const { resolved, absent } = await resolveExistingPrefix(files, path);
+    return absent.length > 0 ? path : resolved;
+}
+export async function provePortOwnership(input) {
+    const resolveCwd = input.resolveCwd ?? ((pid) => resolveProcessCwd(input.runtime, pid));
+    const isDescendant = input.isDescendant ?? ((child, parent) => isDescendantOf(input.runtime, child, parent));
+    if (input.isOurs)
+        return { owned: true, basis: 'tracked-pid', holderCwd: null };
+    const daemonPid = input.daemonPid ?? (await getRuntimeHostIdentity(input.runtime)).currentPid();
+    if (input.daemonPid === undefined && (!Number.isSafeInteger(daemonPid) || daemonPid <= 0)) {
+        throw new CapabilityError('The selected host supplied an invalid process identity.', 'INVALID_INPUT', {
+            reason: 'pm-host-pid-invalid', retryable: false
+        });
+    }
+    // A process in our own tree is ours by construction: we spawned it.
+    if (input.pid !== daemonPid && (await isDescendant(input.pid, daemonPid))) {
+        return { owned: true, basis: 'daemon-descendant', holderCwd: null };
+    }
+    const holderCwd = await resolveCwd(input.pid);
+    if (!input.signatureMatches) {
+        return { owned: false, reason: 'no-signature', holderCwd };
+    }
+    const files = await pmFileSystem(input.runtime);
+    const ourScope = await canonicalizePathOn(files, input.configCwd ?? input.daemonScope?.workspaceRoot);
+    const theirScope = await canonicalizePathOn(files, holderCwd);
+    if (!ourScope || !theirScope) {
+        return { owned: false, reason: 'unproven-scope', holderCwd, mismatch: 'cwd' };
+    }
+    if (ourScope !== theirScope) {
+        return { owned: false, reason: 'foreign-scope', holderCwd, mismatch: 'cwd' };
+    }
+    // Same cwd is NOT enough: a scratch-home process invoked from this very
+    // directory has the same cwd and (now) the same derived port. VIBES_HOME is
+    // the scope a vibes process's state actually belongs to, and it is readable.
+    const resolveScopeEnv = input.resolveScopeEnv ?? ((pid) => resolveProcessScopeEnv(input.runtime, pid));
+    const theirEnv = await resolveScopeEnv(input.pid);
+    if (!theirEnv) {
+        return { owned: false, reason: 'unproven-scope', holderCwd, mismatch: 'vibes-home' };
+    }
+    const ourEnv = input.ourScopeEnv ??
+        (input.daemonScope
+            ? { vibesHome: input.daemonScope.vibesHome, workspacePath: input.daemonScope.workspaceRoot }
+            : null);
+    const userHome = input.daemonScope?.userHome;
+    const ourHome = ourEnv ? await canonicalVibesHome(files, ourEnv.vibesHome, userHome) : null;
+    const theirHome = await canonicalVibesHome(files, theirEnv.vibesHome, userHome);
+    if (!ourEnv || ourHome === null || theirHome === null) {
+        return { owned: false, reason: 'unproven-scope', holderCwd, mismatch: 'vibes-home' };
+    }
+    if (ourHome !== theirHome) {
+        return { owned: false, reason: 'foreign-scope', holderCwd, mismatch: 'vibes-home' };
+    }
+    // Only compared when BOTH sides declare one: an undeclared workspace path is
+    // absence of evidence, and cwd + home already carried the decision.
+    if (ourEnv.workspacePath && theirEnv.workspacePath) {
+        if ((await canonicalizePathOn(files, ourEnv.workspacePath)) !== (await canonicalizePathOn(files, theirEnv.workspacePath))) {
+            return { owned: false, reason: 'foreign-scope', holderCwd, mismatch: 'workspace-path' };
+        }
+    }
+    return { owned: true, basis: 'same-scope-signature', holderCwd };
+}
+const MISMATCH_TEXT = {
+    cwd: 'its working directory is not the one this daemon owns',
+    'vibes-home': 'it belongs to a different VIBES_HOME',
+    'workspace-path': 'it belongs to a different VIBES_WORKSPACE_PATH'
+};
+const UNPROVEN_TEXT = {
+    cwd: 'its working directory could not be read, so it cannot be proved ours',
+    'vibes-home': 'its environment could not be read, so its VIBES_HOME cannot be proved ours',
+    'workspace-path': 'its environment could not be read, so its workspace cannot be proved ours'
+};
+/**
+ * The refusal a caller prints or throws. It NAMES the pid, what it is, where it
+ * lives, and two remedies that do not involve PM signalling a stranger.
+ */
+export function formatForeignHolderRefusal(input) {
+    const what = input.command ? ` (${input.command})` : '';
+    const where = input.holderCwd ? ` running in ${input.holderCwd}` : ' (working directory unreadable)';
+    const ours = input.ourCwd ? ` This daemon owns ${input.ourCwd}.` : '';
+    const why = input.mismatch
+        ? ` (${(input.reason === 'unproven-scope' ? UNPROVEN_TEXT : MISMATCH_TEXT)[input.mismatch]})`
+        : '';
+    const alternate = input.alternatePortHint ??
+        `start this process on a different port (its port is workspace-scoped; pass an explicit --port to override)`;
+    return (`Port ${input.port} is held by PID ${input.pid}${what}${where}, which this PM daemon did not start${why}.${ours} ` +
+        `Refusing to signal a process we do not own. ` +
+        `Remedy: ${alternate}, or stop the holder yourself: kill ${input.pid}.`);
+}
+//# sourceMappingURL=port-ownership.js.map

package/dist/utils/port-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-ownership.js","sourceRoot":"","sources":["../../src/utils/port-ownership.ts"],"names":[],"mappings":"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"}

package/dist/utils/ports.d.ts

@@ -0,0 +1,43 @@
+import type { HostServicesRuntime } from './process-tree.ts';
+import type { ProcessConfig } from '../schemas/process.ts';
+import { type LaunchPreparationImplementation } from '../launch-preparation.ts';
+export declare function extractPortFromEndpoint(endpoint: string): number | null;
+/**
+ * Resolve the launch-preparation implementation selected for a config, the
+ * same way `prepareProcessLaunch` selects one. Returns undefined when the
+ * config declares no preparation or the host composed no provider; the
+ * generic command-line match then applies. A provider that fails validation
+ * is treated as absent here: launch itself refuses `pm-launch-preparation-invalid`
+ * before spawn, and identity matching must not branch on it.
+ */
+export declare function resolveLaunchIdentity(runtime: HostServicesRuntime, config: ProcessConfig): Promise<{
+    matchedBy: string;
+    implementation: LaunchPreparationImplementation;
+} | undefined>;
+export declare function extractMonitoredPorts(runtime: HostServicesRuntime, config: ProcessConfig): Promise<number[]>;
+export declare function findProcessOnPort(runtime: HostServicesRuntime, port: number): Promise<number | null>;
+export declare function isCommandLineMatch(cmd: string | null, config: ProcessConfig): boolean;
+export interface ProcessLineageEntry {
+    pid: number;
+    command: string | null;
+}
+export declare function selectCommandLineageKillPid(lineage: ProcessLineageEntry[], config: ProcessConfig, fallbackPid: number): number;
+export interface PortConflict {
+    port: number;
+    pid: number;
+    killPid: number;
+    command: string | null;
+    type: 'http' | 'tcp' | 'forward' | 'orphan';
+    isOurs: boolean;
+    /** The id of the launch-preparation descriptor whose identity hook matched; absent for generic command-line matches. */
+    matchedBy?: string;
+}
+/**
+ * Positive signature evidence only; ownership is proved separately. The
+ * selected launch-preparation provider owns process identity when it supplies
+ * `matchesProcessCommand`; without that hook the generic command-line match
+ * decides.
+ */
+export declare function matchesCommandSignature(runtime: HostServicesRuntime, command: string | null, config: ProcessConfig, port?: number): Promise<boolean>;
+export declare function findPortConflicts(runtime: HostServicesRuntime, config: ProcessConfig, existingPid: number | null): Promise<PortConflict[]>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/utils/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/utils/ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAmE,KAAK,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAGjJ,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQvE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,aAAa,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,+BAA+B,CAAA;CAAE,GAAG,SAAS,CAAC,CAc7F;AAgBD,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BlH;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE1G;AAcD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CA0BrF;AAED,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAsBD,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,GACjB,MAAM,CAQR;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,wHAAwH;IACxH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAAC,YAAY,EAAE,CAAC,CAkDzB"}

package/dist/utils/ports.js

@@ -0,0 +1,200 @@
+import { getRuntimeProcessService } from '@vibesdotdev/kernel/process';
+import { LaunchPreparationImplementationSchema, launchPreparationRequest } from "../launch-preparation.js";
+import { getDescendantPids, getProcessCommand } from "./process-tree.js";
+export function extractPortFromEndpoint(endpoint) {
+    // An endpoint that is not a URL names no port (a typed answer, no catch).
+    if (!URL.canParse(endpoint))
+        return null;
+    const url = new URL(endpoint);
+    if (url.port) {
+        return parseInt(url.port, 10);
+    }
+    return url.protocol === 'https:' ? 443 : 80;
+}
+/**
+ * Resolve the launch-preparation implementation selected for a config, the
+ * same way `prepareProcessLaunch` selects one. Returns undefined when the
+ * config declares no preparation or the host composed no provider; the
+ * generic command-line match then applies. A provider that fails validation
+ * is treated as absent here: launch itself refuses `pm-launch-preparation-invalid`
+ * before spawn, and identity matching must not branch on it.
+ */
+export async function resolveLaunchIdentity(runtime, config) {
+    const request = launchPreparationRequest(config);
+    if (!request)
+        return undefined;
+    const kind = 'pm/launch-preparation';
+    if (!runtime.hasKind(kind) ||
+        !runtime.query(kind).withId(request.adapter).enabled().descriptors().length) {
+        return undefined;
+    }
+    const selected = await runtime.query(kind).withId(request.adapter).enabled().resolve();
+    const implementation = LaunchPreparationImplementationSchema.safeParse(selected);
+    if (!implementation.success)
+        return undefined;
+    const { monitoredPorts, matchesProcessCommand } = implementation.data;
+    if (!monitoredPorts && !matchesProcessCommand)
+        return undefined;
+    return { matchedBy: request.adapter, implementation: implementation.data };
+}
+/** Ports a resolved launch-preparation provider monitors, if it supplies the hook. */
+async function providerMonitoredPortsFor(resolved, config) {
+    return resolved.implementation.monitoredPorts?.(config) ?? [];
+}
+/** Ports a config's selected launch-preparation provider monitors, if any. */
+async function providerMonitoredPorts(runtime, config) {
+    const resolved = await resolveLaunchIdentity(runtime, config);
+    return resolved ? providerMonitoredPortsFor(resolved, config) : [];
+}
+export async function extractMonitoredPorts(runtime, config) {
+    const ports = [];
+    const healthPortIsManaged = config.healthCheck?.portOwnership !== 'external';
+    // HTTP health check port
+    if (healthPortIsManaged &&
+        config.healthCheck?.type === 'http' &&
+        config.healthCheck.endpoint) {
+        const port = extractPortFromEndpoint(config.healthCheck.endpoint);
+        if (port)
+            ports.push(port);
+    }
+    // TCP health check port
+    if (healthPortIsManaged && config.healthCheck?.type === 'tcp' && config.healthCheck.port) {
+        ports.push(config.healthCheck.port);
+    }
+    // Ports the selected launch-preparation provider owns (e.g. a forwarded
+    // tunnel's local listeners); a provider that supplies no hook adds none.
+    ports.push(...await providerMonitoredPorts(runtime, config));
+    // Explicit orphan ports
+    if (config.orphanPorts) {
+        ports.push(...config.orphanPorts);
+    }
+    return [...new Set(ports)];
+}
+export async function findProcessOnPort(runtime, port) {
+    return (await getRuntimeProcessService(runtime)).listeningPid(port);
+}
+const LAUNCHER_COMMANDS = new Set([
+    'bun',
+    'bunx',
+    'node',
+    'deno',
+    'python',
+    'python3',
+    'bash',
+    'sh',
+    'zsh'
+]);
+const WRAPPER_ARGS = new Set(['run', '--bun', '--hot', '--watch']);
+export function isCommandLineMatch(cmd, config) {
+    if (!cmd)
+        return false;
+    if (!config.args || config.args.length === 0)
+        return false;
+    const candidates = config.args
+        .filter((t) => !t.startsWith('-') && t.length >= 3)
+        .filter((t) => !WRAPPER_ARGS.has(t));
+    if (candidates.length === 0)
+        return false;
+    // When the command matches directly (e.g. a tunnel binary), keep strict matching.
+    if (cmd.includes(config.command)) {
+        const minMatches = Math.min(4, candidates.length);
+        const matches = candidates.reduce((count, token) => (cmd.includes(token) ? count + 1 : count), 0);
+        return matches >= minMatches;
+    }
+    // For launcher commands (bun/node/etc), the listener is often a child (e.g. bun -> node -> vite).
+    // Allow matching against the meaningful args even if the launcher itself isn't in the command line.
+    if (!LAUNCHER_COMMANDS.has(config.command))
+        return false;
+    const minMatches = Math.min(2, candidates.length);
+    const matches = candidates.reduce((count, token) => (cmd.includes(token) ? count + 1 : count), 0);
+    return matches >= minMatches;
+}
+async function getProcessLineage(runtime, pid) {
+    const lineage = [];
+    const seen = new Set();
+    let currentPid = pid;
+    while (currentPid > 1 && !seen.has(currentPid)) {
+        seen.add(currentPid);
+        // A null command is a process that exited; the lineage ends there.
+        const command = await getProcessCommand(runtime, currentPid);
+        if (command === null)
+            break;
+        lineage.push({ pid: currentPid, command });
+        const parentPid = await (await getRuntimeProcessService(runtime)).parent(currentPid);
+        if (parentPid === null || parentPid <= 1)
+            break;
+        currentPid = parentPid;
+    }
+    return lineage;
+}
+export function selectCommandLineageKillPid(lineage, config, fallbackPid) {
+    for (let i = lineage.length - 1; i >= 0; i -= 1) {
+        const entry = lineage[i];
+        if (isCommandLineMatch(entry.command, config)) {
+            return entry.pid;
+        }
+    }
+    return fallbackPid;
+}
+/**
+ * Positive signature evidence only; ownership is proved separately. The
+ * selected launch-preparation provider owns process identity when it supplies
+ * `matchesProcessCommand`; without that hook the generic command-line match
+ * decides.
+ */
+export async function matchesCommandSignature(runtime, command, config, port) {
+    const resolved = await resolveLaunchIdentity(runtime, config);
+    if (resolved?.implementation.matchesProcessCommand) {
+        return resolved.implementation.matchesProcessCommand({ command, config, port });
+    }
+    return isCommandLineMatch(command, config);
+}
+export async function findPortConflicts(runtime, config, existingPid) {
+    const conflicts = [];
+    const resolved = await resolveLaunchIdentity(runtime, config);
+    const ports = await extractMonitoredPorts(runtime, config);
+    // Pre-compute descendant PIDs if we have an existing managed process
+    // This allows us to recognize child processes (like node spawned by bun)
+    // as belonging to our managed process tree
+    const descendants = existingPid
+        ? new Set(await getDescendantPids(runtime, existingPid))
+        : new Set();
+    for (const port of ports) {
+        const pid = await findProcessOnPort(runtime, port);
+        if (!pid)
+            continue;
+        const lineage = await getProcessLineage(runtime, pid);
+        // The holder exited between the port probe and the process table read.
+        if (lineage.length === 0)
+            continue;
+        const cmd = lineage
+            .map((entry) => entry.command)
+            .filter((command) => Boolean(command))
+            .join(' <- ');
+        const killPid = selectCommandLineageKillPid(lineage, config, pid);
+        // Check if it's our process OR a child/descendant of our process
+        // This fixes the issue where bun spawns node for vite, and node holds the port
+        const isOurs = existingPid !== null && (pid === existingPid || descendants.has(pid));
+        // Determine conflict type
+        let type = 'orphan';
+        if (config.healthCheck?.type === 'http') {
+            const hcPort = extractPortFromEndpoint(config.healthCheck.endpoint);
+            if (hcPort === port)
+                type = 'http';
+        }
+        if (config.healthCheck?.type === 'tcp' && config.healthCheck.port === port) {
+            type = 'tcp';
+        }
+        let matchedBy;
+        if (resolved) {
+            const owned = (await providerMonitoredPortsFor(resolved, config)).includes(port);
+            if (owned) {
+                type = 'forward';
+                matchedBy = resolved.matchedBy;
+            }
+        }
+        conflicts.push({ port, pid, killPid, command: cmd || null, type, isOurs, matchedBy });
+    }
+    return conflicts;
+}
+//# sourceMappingURL=ports.js.map

package/dist/utils/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/utils/ports.ts"],"names":[],"mappings":"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"}