@vibesdotdev/plugins 0.0.0-stage → 1.0.0-rc.1

package/dist/cli/roll.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The roll census for `vibes update` (plan §5.1).
+ *
+ * `vibes update` replaces the module graph under running bodies. A body that
+ * keeps executing the previous graph answers plausibly and is wrong — that is
+ * the stale-body failure class this whole program exists to end. So the update
+ * does not merely restart what it can reach; it ENUMERATES every body it knows
+ * how to find and prints one line per body, including the ones it could not
+ * roll and why.
+ *
+ * ### Where the census comes from, and why it is three sources, not one
+ *
+ * 1. **The OS agent directory** — `~/Library/LaunchAgents/*.plist` (darwin) or
+ *    `~/.config/systemd/user/*.service` (linux). This is the ONLY source that
+ *    sees the `dev.vibes.bignet.*` bodies: they invoke `vibes fleet daemon
+ *    --host-id …` directly and are **not** `hq/os-service` descriptors, so a
+ *    census built from the hq registry alone reports them as absent when they
+ *    are in fact running the old graph.
+ * 2. **The hq service registry** — `hq/os-service` descriptors, read from THIS
+ *    runtime. No manifest edge: if the host composed hq, the kind is there; if
+ *    it did not, the census says so instead of pretending.
+ * 3. **PM and stdio MCP** — the PM daemon rolls through its own supervised
+ *    handoff; an stdio MCP body is owned by its client (Claude Code, Cursor,
+ *    …) and CANNOT be restarted from here. It is reported `NOT ROLLED` with
+ *    `/mcp` as the remedy rather than silently omitted.
+ *
+ * Each body is classified by what its command line actually is, because the
+ * three shapes roll differently: an installed-binary body picks up the new
+ * graph on restart; a **source-mode** body (`bun …/vibes.ts`) already reads the
+ * files that just changed and needs a restart only for module cache; a
+ * **hostWorkspace-delegated** body resolves its graph through
+ * `$VIBES_HOME/package.json#vibes.hostWorkspace`, so it is rolled by the same
+ * restart but its graph root is not `$VIBES_HOME`.
+ *
+ * Rolling happens IN-PROCESS through the owner of each body, never by
+ * re-entering the CLI: an hq-registered OS service through hq's service
+ * registry (`restartService`, whose receipt says whether the main pid was
+ * replaced), the PM daemon through PM's own `pm.daemon.restart` command
+ * resolved from this runtime and verified by reading the daemon pid again.
+ * A body whose owner is not composed into this host is reported `NOT ROLLED`
+ * with that reason, never omitted and never counted as success.
+ *
+ * Every host fact comes from the handed runtime: files through its filesystem
+ * adapter, the platform from its host facts, process-table reads and the
+ * executable-replacement verdict from `runtime/host-identity`, and the
+ * service-manager census (`launchctl list`, `systemctl --user show`) through
+ * `runtime/execution` in argv form with a declared deadline.
+ */
+import { type CaughtFailure, type ChildEnvRuntime, type RuntimeHostIdentity, type VibesRuntime } from '@vibesdotdev/kernel';
+import type { RollBody, RollBodyMode } from '../schemas/roll.ts';
+export type { RollBody, RollBodyKind, RollBodyMode, RollBodyShape } from '../schemas/roll.ts';
+export interface RollOutcome {
+    /** Original restart failure retained for programmatic callers; human output is redacted. */
+    cause?: CaughtFailure;
+    body: RollBody;
+    rolled: boolean;
+    previousPid?: number;
+    pid?: number;
+    /** Human line: `rolled (pid a→b)` or `NOT ROLLED: <id> — <reason>`. */
+    line: string;
+    reason?: string;
+}
+/** The deadline on one service-manager census command. */
+export declare const SERVICE_MANAGER_TIMEOUT_MS = 5000;
+/** Classify a supervised program path into the three graph shapes. */
+export declare function classifyProgram(program: string | undefined): RollBodyMode;
+/**
+ * Every `com.vibes.*` / `dev.vibes.*` LaunchAgent on disk. Deliberately reads
+ * the DIRECTORY, not a registry: the `dev.vibes.bignet.*` bodies are real,
+ * running, and unknown to hq.
+ */
+export declare function censusLaunchAgents(runtime: VibesRuntime, userHome: string): Promise<RollBody[]>;
+/** systemd user units named for vibes. Same contract as the launchd census. */
+export declare function censusSystemdUserUnits(runtime: VibesRuntime, userHome: string): Promise<RollBody[]>;
+/**
+ * `hq/os-service` descriptors composed into THIS runtime. Returns `[]` when hq
+ * is not part of the host — the absence is reported by the caller as a
+ * denominator note, never as "no services".
+ */
+export declare function censusHqServices(runtime: VibesRuntime, userHome: string): Promise<RollBody[]>;
+/** stdio MCP bodies, which no command can restart — their client owns them. */
+export declare function censusStdioMcpBodies(runtime: VibesRuntime, vibesHome: string): Promise<RollBody[]>;
+/** What the whole census reads. */
+export interface CensusInput {
+    runtime: VibesRuntime;
+    userHome: string;
+    vibesHome: string;
+    includePmDaemon: boolean;
+}
+/**
+ * The whole census, deduplicated by `<kind>:<id>`. An hq-registered label seen
+ * in the agent directory keeps the hq row (it carries the restart capability)
+ * but inherits the on-disk program, so the shape is what is actually running.
+ * The OS agent source follows the platform the host declared.
+ */
+export declare function censusBodies(input: CensusInput): Promise<RollBody[]>;
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Is this body running a REPLACED executable? (plan §7)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `vibes update` used to roll only when the module graph moved or `--self`
+ * downloaded a release. A local `bun run build:install` replaces
+ * `~/.local/bin/vibes` by atomic rename and changes NEITHER, so the command
+ * printed "nothing changed, so no body was rolled" at the same moment
+ * `vibes pm status` printed "⚠ PM daemon (pid …) runs a replaced vibes
+ * executable" — two shipping surfaces disagreeing about one fact, with the
+ * weaker predicate winning the decision that matters.
+ *
+ * The verdict reads `runtime/host-identity` (`readProcessExecutablePath` →
+ * `readProcessStartMs` → `executableReplacedSince`), the same nerve `pm status`
+ * and the PM daemon's `ExecutableFreshnessReconciler` read.
+ */
+export interface BodyExecutableVerdict {
+    /**
+     * true  — the file this body executes was written after the body started;
+     * false — it predates the body;
+     * null  — unanswerable (no pid, `ps` unavailable, path unreadable). NEVER
+     *         collapsed into `false`: "we could not read it" and "it is fresh"
+     *         are different facts and only the first must not trigger a roll.
+     */
+    replaced: boolean | null;
+    reason: string;
+}
+/** The three host-identity reads a body verdict makes. */
+export type BodyProcessReaders = Pick<RuntimeHostIdentity, 'readProcessExecutablePath' | 'readProcessStartMs' | 'executableReplacedSince'>;
+/** The production readers: the host's own process-table and executable-identity capability. */
+export declare function bodyProcessReaders(runtime: VibesRuntime): Promise<BodyProcessReaders>;
+/** One body to judge: its live pid and its plist program, when known. */
+export interface JudgedBody {
+    pid?: number;
+    program?: string;
+}
+/**
+ * The shared predicate, applied to one body.
+ *
+ * `program` (argv[0] from the plist/unit) is only a FALLBACK: the OS is asked
+ * first, because a plist may name a symlink or a `PATH`-resolved word while the
+ * kernel knows the actual file. A relative `program` is refused rather than
+ * guessed against `PATH`.
+ */
+export declare function judgeBodyExecutable(body: JudgedBody, readers: BodyProcessReaders): BodyExecutableVerdict;
+/**
+ * The service managers' environment: the kernel's host set plus the user
+ * session keys `systemctl --user` reaches its manager through.
+ */
+export declare function serviceManagerEnv(runtime: ChildEnvRuntime): Record<string, string>;
+/**
+ * Live pids for every loaded LaunchAgent, in ONE `launchctl list` call
+ * (`PID\tStatus\tLabel`). A label with `-` for a pid is loaded but not running,
+ * and is deliberately absent from the map — there is no body to be stale.
+ */
+export declare function launchdPids(runtime: VibesRuntime, env: Record<string, string>): Promise<Map<string, number>>;
+/** `MainPID` of one systemd user unit; 0/absent means not running. */
+export declare function systemdMainPid(runtime: VibesRuntime, unit: string, env: Record<string, string>): Promise<number | undefined>;
+/** What the PM pid census reads from the runtime it is handed. */
+export type PmPidRuntime = VibesRuntime;
+/**
+ * The PM daemon's pid, read from PM's own PID file for `runtime`'s admitted
+ * workspace (the runtime the caller was handed).
+ *
+ * Deliberately NOT `runtime.context('pm/client')`: resolving that context
+ * SPAWNS a daemon as a side effect (`pm.context.impl.consumer.ts` fires
+ * `ensureDaemonRunning()` on consumer hardware), and a census that starts the
+ * body it is measuring is not a census. The path itself has one owner —
+ * `@vibesdotdev/pm/daemon-pid` — imported dynamically because `pm` is an
+ * OPTIONAL peer here. `undefined` ("unanswerable", not "fresh") has exactly
+ * two causes: a host composed without PM (the module is not installed), and a
+ * workspace PM never admitted (so no PM daemon of it exists). Every other
+ * failure propagates.
+ */
+export declare function pmDaemonPid(runtime: PmPidRuntime): Promise<number | undefined>;
+/**
+ * Attach a pid and the executable verdict to every body in a census.
+ *
+ * Pure of side effects on the bodies themselves: it starts nothing, restarts
+ * nothing, and returns new rows. stdio-MCP bodies are skipped — their client
+ * owns them, nothing here can roll them, so asking costs a `ps` for no decision.
+ */
+export declare function markReplacedExecutables(bodies: ReadonlyArray<RollBody>, runtime: VibesRuntime, readers?: BodyProcessReaders): Promise<RollBody[]>;
+/** The bodies that MUST be rolled: they execute a file that was replaced. */
+export declare function bodiesRunningReplacedExecutable(bodies: ReadonlyArray<RollBody>): RollBody[];
+/** Parse a restart receipt line into the pids it reported. */
+export declare function parseRestartPids(output: string): {
+    previousPid: number;
+    pid: number;
+} | {
+    pid: number;
+    previousPid?: undefined;
+} | {
+    previousPid?: undefined;
+    pid?: undefined;
+};
+/** Who restarts one body in-process: PM's command, hq's service registry, or nobody. */
+export type RollRoute = {
+    owner: 'pm';
+    commandId: 'pm.daemon.restart';
+} | {
+    owner: 'hq';
+    serviceId: string;
+};
+/** The in-process route that rolls one body, or `null` when no owner can. */
+export declare function rollRouteFor(body: RollBody): RollRoute | null;
+/** The pids a restart receipt carried; the restart itself reported whether the main pid was replaced. */
+interface RestartReceipt {
+    replaced: boolean;
+    previousPid?: number;
+    pid?: number;
+}
+/** What rolls a body: the two owners, injectable so a test fakes only the far boundary. */
+export interface BodyRestarters {
+    restartPmDaemon(runtime: VibesRuntime, previousPid: number | undefined): Promise<RestartReceipt>;
+    restartHqService(runtime: VibesRuntime, serviceId: string): Promise<RestartReceipt>;
+}
+/** The production restarters: PM's own restart command and hq's service registry, both in this process. */
+export declare const defaultRestarters: BodyRestarters;
+/** What one roll pass reads. */
+export interface RollInput {
+    runtime: VibesRuntime;
+    bodies: ReadonlyArray<RollBody>;
+    dryRun?: boolean;
+    restarters?: BodyRestarters;
+}
+/**
+ * Roll every body in the census, in order, and return one verified outcome per
+ * body. A body this host cannot roll produces a `NOT ROLLED` line naming the
+ * remedy; it is never omitted, and it never reads as success.
+ */
+export declare function rollBodies(input: RollInput): Promise<RollOutcome[]>;
+//# sourceMappingURL=roll.d.ts.map

package/dist/cli/roll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../../src/cli/roll.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,EAQN,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE9F,MAAM,WAAW,WAAW;IAC3B,4FAA4F;IAC5F,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAMhD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAMzE;AA+BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA6BrG;AAED,+EAA+E;AAC/E,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAezG;AAcD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA+BnG;AAED,+EAA+E;AAC/E,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcxG;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAkB1E;AAED;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,qBAAqB;IACrC;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,mBAAmB,EAAE,2BAA2B,GAAG,oBAAoB,GAAG,yBAAyB,CAAC,CAAC;AAE3I,+FAA+F;AAC/F,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAO3F;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,GAAG,qBAAqB,CAsBxG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAElF;AAcD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAclH;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMlI;AAED,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAepF;AASD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC5C,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,EAC/B,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAwBrB;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,QAAQ,EAAE,CAE3F;AAKD,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM;;;;;;;;;EAM9C;AAED,wFAAwF;AACxF,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,mBAAmB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7G,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAI7D;AAED,yGAAyG;AACzG,UAAU,cAAc;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC9B,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjG,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACpF;AAmCD,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,EAAE,cA6B/B,CAAC;AAwBF,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAyCzE"}