@pinet/slack-bridge 0.2.4 → 0.2.6

package/dist/broker/hibernation-activation.js

@@ -0,0 +1,95 @@
+// Phase B live-runtime activation composition.
+//
+// Wires the reviewed, approved hibernation RUNTIME ADAPTERS (real process/tmux
+// controllers + spawn-authored runtime-spec builder + git-remote VCS identity)
+// into the broker's three live seams, all behind the DEFAULT-OFF durable,
+// non-reloadable activation authority (see hibernation-activation-authority.ts;
+// `hibernationRuntimeActive()`):
+//
+//   1. createHibernationOrchestrator  — the real orchestrator-backed executor
+//      that replaces the `activation_pending` stub ONLY under the gate.
+//   2. persistSpawnedRuntimeSpec      — records a durable, broker-authored
+//      runtime spec (canonical git-remote VCS identity) at worker spawn.
+//   3. recoverStrandedWakesBeforeRegistrations — reconciles crash-stranded wake
+//      rows at broker startup, before the socket accepts new registrations.
+//
+// Keeping the composition here (rather than inline in index.ts / the subtree
+// runtime) makes every seam unit- and E2E-testable against REAL dependencies
+// (real BrokerDB, real git, real tmux/pi) with no production side effects.
+import { HibernationOrchestrator, } from "@pinet/broker-core";
+import { createHibernationProcessController, createHibernationTmuxController, resolveVcsIdentity, } from "./hibernation-runtime-adapters.js";
+import { buildRuntimeSpecInput, } from "./hibernation-runtime-helpers.js";
+import { hibernationActivationAuthorized } from "./hibernation-activation-authority.js";
+/**
+ * The DEFAULT-OFF live-runtime gate. Live process/tmux composition happens ONLY
+ * when the durable, process-lifetime activation authority — captured at broker
+ * start from the external launch environment, never agent-editable settings — is
+ * set. Config reloads and settings edits can NEVER flip it, so the production
+ * default (authority unset) keeps the broker on the `activation_pending` stub
+ * with zero live-runtime side effects. Operational permission (enabled / mode /
+ * repo allowlist) is a SEPARATE settings policy enforced by the command layer;
+ * this gate only decides whether the real machinery is wired in at all.
+ */
+export function hibernationRuntimeActive() {
+    return hibernationActivationAuthorized();
+}
+/**
+ * Seam 1 — compose the real orchestrator-backed executor.
+ *
+ * The process and tmux controllers are constructed INDEPENDENTLY: the immutable
+ * launch generation rides inside the attempt handle `respawnRuntime` returns, so
+ * attempt-scoped stop/liveness bind to the exact launched process with no shared
+ * registry. The returned {@link HibernationOrchestrator} structurally satisfies
+ * `HibernateCommandExecutor & WakeCommandExecutor`, so it drops directly into the
+ * command executor slot in place of the `activation_pending` stub — but only the
+ * caller's {@link hibernationRuntimeActive} gate decides when to use it.
+ */
+export function createHibernationOrchestrator(deps) {
+    const process = createHibernationProcessController({
+        pendingInboxCount: (agentId) => deps.db.getUnreadInboxCount(agentId),
+    });
+    const tmux = createHibernationTmuxController({
+        extensionEntryPath: deps.extensionEntryPath,
+        baseLaunchEnv: deps.baseLaunchEnv,
+        inheritedEnvKeys: deps.inheritedEnvKeys,
+    });
+    return new HibernationOrchestrator({
+        db: deps.db,
+        process,
+        tmux,
+        brokerInstanceId: deps.brokerInstanceId,
+        ...(deps.config ? { config: deps.config } : {}),
+        ...(deps.awaitRuntimeRegistration
+            ? { awaitRuntimeRegistration: deps.awaitRuntimeRegistration }
+            : {}),
+    });
+}
+/**
+ * Seam 2 — persist a durable, broker-authored runtime spec at worker spawn.
+ *
+ * The canonical `owner/repo` VCS identity (the ONLY value the repo allowlist
+ * authorizes against) is resolved HERE from the runtime's actual git `origin`
+ * remote — never from filesystem directory names. Fails closed: an unresolvable
+ * remote records `vcsIdentity: null` (the fail-closed gate then refuses), and a
+ * spec that could not be safely hibernated/woken (missing session/tmux/repo
+ * locators) is never written. Returns the persisted spec, or null when the facts
+ * do not compose a durable spec.
+ */
+export async function persistSpawnedRuntimeSpec(db, facts, runner) {
+    const vcsIdentity = await resolveVcsIdentity(facts.repoRoot, runner);
+    const input = buildRuntimeSpecInput({ ...facts, vcsIdentity });
+    if (!input)
+        return null;
+    return db.upsertAgentRuntimeSpec(input);
+}
+/**
+ * Seam 3 — reconcile crash-stranded wake state at broker startup.
+ *
+ * Must run BEFORE the broker socket accepts new registrations so a stranded
+ * `waking`/`dispatching` row is completed, quarantined, or requeued deterministically
+ * rather than racing an incoming (possibly duplicate) wake registration. This is a
+ * synchronous DB reconciliation; it launches nothing.
+ */
+export function recoverStrandedWakesBeforeRegistrations(orchestrator) {
+    return orchestrator.recoverStrandedWakes();
+}

package/dist/broker/hibernation-command-router.d.ts

@@ -0,0 +1,54 @@
+import { type HibernationCommandResult, type RuntimeLaunchContext } from "@pinet/broker-core";
+import type { BrokerDB } from "./schema.js";
+import type { ResolvedHibernationSettings } from "../hibernation-config.js";
+/**
+ * The authoritative runtime-control surface the command path binds to when runtime
+ * activation is active. Structurally identical to the subtree broker's
+ * `SubtreeHibernationRuntimeControl`; kept here so the router has no import
+ * dependency on the extension wiring and stays independently testable.
+ */
+export interface HibernationRuntimeControl {
+    /** The ONE authoritative DB that owns the spawned workers + their specs. */
+    db: BrokerDB;
+    /** Broker instance id recorded on lifecycle leases; matches startup recovery. */
+    brokerInstanceId: string;
+    /** Base PINET_* env re-establishing the mesh connection for a woken worker. */
+    baseLaunchEnv: Record<string, string>;
+}
+export interface RouteHibernationCommandInput {
+    command: "hibernate" | "wake";
+    target: string;
+    reason?: string;
+    /** Must be "broker"; any other role (or null) rejects (this session is not the broker). */
+    brokerRole: string | null;
+    /** Operational policy (enabled/mode/allowlist) — SEPARATE from runtime activation. */
+    hib: ResolvedHibernationSettings;
+    /**
+     * Real accessor for the subtree broker's authoritative control surface. Invoked
+     * only when the frozen activation authority is set; returns null when no subtree
+     * broker is running (nothing is command-addressable).
+     */
+    getRuntimeControl: () => HibernationRuntimeControl | null;
+    /** Central broker DB, used ONLY as the default-off fallback (never when active). */
+    getFallbackDb: () => BrokerDB | null;
+    /** slack-bridge extension entry a woken runtime loads (`pi -e <path>`). */
+    extensionEntryPath: string;
+    /** Broker env var NAMES (never values) re-exported into a woken runtime. */
+    inheritedEnvKeys: string[];
+    /**
+     * Socket-registration RPC stand-in. PRODUCTION leaves this undefined so the
+     * orchestrator's default polls the broker DB until the socket server's fenced
+     * handler accepts the woken worker's generation. Injectable so an isolated E2E
+     * can key acceptance off the REAL respawned process instead of a live handshake.
+     */
+    awaitRuntimeRegistration?: (ctx: RuntimeLaunchContext) => Promise<boolean>;
+}
+/**
+ * Resolve and run one hibernate/wake command exactly as the live extension does.
+ *
+ * Ordering matters and is asserted by regression tests: activation is read from
+ * the frozen authority FIRST, which decides whether the authoritative DB is the
+ * subtree control DB or the central fallback, which decides whether the real
+ * orchestrator or the `activation_pending` stub is composed.
+ */
+export declare function routeHibernationCommand(input: RouteHibernationCommandInput): Promise<HibernationCommandResult>;

package/dist/broker/hibernation-command-router.js

@@ -0,0 +1,124 @@
+// Production hibernate/wake command router + executor composition.
+//
+// This is the SINGLE source of truth for how an operator `pinet hibernate` /
+// `pinet wake` command resolves its authoritative DB, target worker, policy, and
+// executor. It is extracted out of the extension closure so BOTH the live
+// extension (`index.ts` `runHibernationCommand`) and the isolated production-route
+// E2E drive the exact same integration code — the code that fixed the DB-topology
+// and activation-authority seams — rather than re-composing the pieces by hand.
+//
+// The design invariants this router encodes (each has a negative regression test):
+//
+//   • Activation is authorized ONLY by the durable, non-reloadable, frozen
+//     broker-start authority (`hibernationRuntimeActive()`), never by reloadable
+//     settings. A settings reload can NEVER flip a running broker on.
+//   • When active, the SUBTREE broker is the authority: it spawned and OWNS these
+//     workers and authored their durable runtime specs, so target resolution, the
+//     authz spec read, AND the orchestrator all run against that SAME subtree DB
+//     (`getRuntimeControl().db`) — never the central broker DB.
+//   • When inactive (production default) there is no runtime control, so resolution
+//     falls back to the central DB and the executor stays the `activation_pending`
+//     stub: a clear refusal, never a silent no-op.
+//   • The repo allowlist is a security boundary authorized ONLY against the
+//     broker-authored spec's canonical `owner/repo` VCS identity (captured at spawn
+//     from the git remote), never a filesystem path slug or worker-declared metadata.
+import { executeHibernateCommand, executeWakeCommand, unknownHibernationTarget, } from "@pinet/broker-core";
+import { createHibernationOrchestrator, hibernationRuntimeActive, } from "./hibernation-activation.js";
+/**
+ * Resolve and run one hibernate/wake command exactly as the live extension does.
+ *
+ * Ordering matters and is asserted by regression tests: activation is read from
+ * the frozen authority FIRST, which decides whether the authoritative DB is the
+ * subtree control DB or the central fallback, which decides whether the real
+ * orchestrator or the `activation_pending` stub is composed.
+ */
+export async function routeHibernationCommand(input) {
+    const { command, target, reason, brokerRole, hib } = input;
+    if (brokerRole !== "broker") {
+        throw new Error(`pinet ${command} is broker-managed. Connect this session as the broker (/pinet start) to hibernate or wake workers.`);
+    }
+    // Authoritative DB unification + explicit trust boundary. When the durable,
+    // non-reloadable runtime-activation authority is set, the SUBTREE broker owns
+    // these workers AND authored their durable runtime specs, so hibernate/wake must
+    // resolve the target, read its authz spec, AND drive the orchestrator against
+    // that SAME subtree DB end to end. The operator may therefore only address
+    // workers this process's subtree broker owns. In the default-off configuration
+    // there is no runtime control, so resolution falls back to the central broker DB
+    // and the executor stays the `activation_pending` stub (a clear refusal, never a
+    // silent no-op).
+    const runtimeControl = hibernationRuntimeActive() ? input.getRuntimeControl() : null;
+    const db = runtimeControl?.db ?? input.getFallbackDb();
+    if (!db)
+        throw new Error("Broker database is unavailable.");
+    const wanted = target.trim().replace(/^@/, "");
+    const agents = db.getAllAgents();
+    const lowerWanted = wanted.toLowerCase();
+    const nameMatches = agents.filter((a) => a.name?.toLowerCase() === lowerWanted);
+    const agent = agents.find((a) => a.id === wanted) ??
+        agents.find((a) => a.stableId === wanted) ??
+        (nameMatches.length === 1 ? nameMatches[0] : undefined);
+    if (!agent)
+        return unknownHibernationTarget(command, target);
+    const policy = {
+        enabled: hib.enabled,
+        mode: hib.mode,
+        allowedRepos: hib.allowedRepos,
+    };
+    const state = (agent.lifecycleState ?? "live");
+    // Provenance: the repo allowlist is a security boundary, so authorization trusts
+    // ONLY the broker-authored durable runtime spec's CANONICAL VCS IDENTITY
+    // (`owner/repo`), captured at spawn from the runtime's git remote. Ownership is
+    // NEVER inferred from filesystem directory names or worker-declared metadata.
+    // When no trusted spec / resolvable remote exists the identifier stays null and
+    // the fail-closed gate refuses.
+    const repoIdentifier = db.getAgentRuntimeSpec(agent.id)?.vcsIdentity ?? null;
+    // Live process/tmux checkpoint/respawn adapters are a separate, explicitly gated
+    // activation step (default-off). When runtime activation is unset `runtimeControl`
+    // is null and callers get a clear `activation_pending` refusal rather than a
+    // silent no-op. When set, the real process/tmux HibernationOrchestrator is
+    // composed over the SAME subtree DB that owns the worker and its spec, with
+    // `brokerInstanceId` matching the spawn/startup-recovery owner so lease fencing
+    // lines up. The woken worker's respawn env is the subtree broker's child-launch
+    // env; inherited secret var NAMES come from the shared spawn/wake allowlist.
+    const executor = runtimeControl
+        ? createHibernationOrchestrator({
+            db: runtimeControl.db,
+            brokerInstanceId: runtimeControl.brokerInstanceId,
+            extensionEntryPath: input.extensionEntryPath,
+            baseLaunchEnv: runtimeControl.baseLaunchEnv,
+            inheritedEnvKeys: input.inheritedEnvKeys,
+            config: {
+                handshakeTimeoutMs: hib.handshakeTimeoutMs,
+                wakeLeaseMs: hib.wakeLeaseMs,
+                maxConcurrentWakes: hib.maxConcurrentWakes,
+                maxConcurrentWakesPerRepo: hib.maxConcurrentWakesPerRepo,
+            },
+            ...(input.awaitRuntimeRegistration
+                ? { awaitRuntimeRegistration: input.awaitRuntimeRegistration }
+                : {}),
+        })
+        : {
+            prepareHibernation: () => ({ ready: false, state, reason: "activation_pending" }),
+            hibernate: async () => ({ ok: false, state, reason: "activation_pending" }),
+            wake: async () => ({ ok: false, state, reason: "activation_pending" }),
+        };
+    if (command === "hibernate") {
+        return executeHibernateCommand({
+            executor,
+            agentId: agent.id,
+            state,
+            repoIdentifier,
+            policy,
+            actor: "operator",
+            reason,
+        });
+    }
+    return executeWakeCommand({
+        executor,
+        agentId: agent.id,
+        state,
+        policy,
+        actor: "operator",
+        reason,
+    });
+}

package/dist/broker/hibernation-runtime-adapters.d.ts

@@ -0,0 +1,79 @@
+import type { HibernationProcessController, HibernationTmuxController, RuntimeLaunchContext } from "@pinet/broker-core";
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/** Minimal command executor abstraction (fake in tests, execFile at runtime). */
+export interface CommandRunner {
+    run(file: string, args: string[]): Promise<CommandResult>;
+}
+/** Real `CommandRunner` over `child_process.execFile` that never throws on a
+ * non-zero exit — it resolves the captured exit code so callers branch on it. */
+export declare function createExecFileRunner(): CommandRunner;
+/** The minimal tmux pane address the pane probes/signals operate against. */
+interface PaneAddress {
+    tmuxSocket: string;
+    tmuxTarget: string;
+}
+/**
+ * A verified OS process generation: the pane's foreground pid PLUS an OS
+ * generation token (the process START TIME). The token pins the exact process
+ * instance so a cross-second reused pid (same number, different process, later
+ * start) is not mistaken for — or signalled as — the original runtime. Start time
+ * survives the launcher's `exec` of Pi (unlike the command line), so it stays
+ * stable for the life of the runtime. See the header note on the residual
+ * same-second window.
+ */
+interface ProcessGeneration {
+    pid: number;
+    generationToken: string;
+}
+/**
+ * The attempt-bound generation a single wake launched, carrying the pane address
+ * so the attempt-scoped stop/liveness probes read the exact pane the attempt
+ * respawned into. Embedded in {@link LaunchedAttemptHandle}.
+ */
+export interface AttemptGeneration extends ProcessGeneration, PaneAddress {
+}
+export interface RuntimeAdapterDeps {
+    runner?: CommandRunner;
+    /** Byte size of a session file, or null when absent (non-empty ⇒ resumable). */
+    sessionByteSize?: (filePath: string) => number | null;
+    processAlive?: (pid: number) => boolean;
+    sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Pending inbox count projection for the checkpoint outcome. */
+    pendingInboxCount?: (agentId: string) => number;
+    /** Grace window for TERM before escalating to KILL. */
+    stopGraceMs?: number;
+    /** Poll interval while awaiting process exit. */
+    pollMs?: number;
+}
+export declare function createHibernationProcessController(deps?: RuntimeAdapterDeps): HibernationProcessController;
+export interface RuntimeRespawnDeps {
+    runner?: CommandRunner;
+    /** slack-bridge extension entry the woken runtime loads (`pi -e <path>`). */
+    extensionEntryPath: string;
+    /** Base PINET_* env re-establishing the mesh connection for the woken worker. */
+    baseLaunchEnv: Record<string, string>;
+    /** Broker env keys re-exported into the woken runtime when present. */
+    inheritedEnvKeys: string[];
+    buildNickname?: (ctx: RuntimeLaunchContext) => string;
+    /** Private, owner-only directory launchers are materialized in (lazily made). */
+    launcherDir?: string;
+    writeFile?: (filePath: string, content: string, mode: number) => void;
+    unlink?: (filePath: string) => void;
+    readEnv?: (key: string) => string | undefined;
+}
+export declare function createHibernationTmuxController(deps: RuntimeRespawnDeps): HibernationTmuxController;
+/**
+ * Resolve the canonical git-remote-derived `owner/repo` VCS identity for a repo
+ * root at spawn time. This is the ONLY identity the repo allowlist authorizes
+ * against — derived from the runtime's actual `origin` remote, never from the
+ * filesystem directory name. Returns null when no remote is resolvable (the
+ * fail-closed authorization gate then refuses).
+ */
+export declare function resolveVcsIdentity(repoRoot: string, runner?: CommandRunner): Promise<string | null>;
+export {};