@rynx-ai/daemon 0.1.10 → 0.1.11-beta.10

package/dist/maintenance-lease.js

@@ -0,0 +1,250 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+const LEASE_SCHEMA_VERSION = 1;
+// The detached updater can spend 24h waiting for idle before cutover begins.
+// Once accepted, retain a separate bounded recovery window long enough for the
+// package switch and rollback even if the updater is killed at its outer limit.
+const DEFAULT_LEASE_TTL_MS = 30 * 60 * 60 * 1_000;
+const EXPIRY_RETRY_MS = 1_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LEASE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,256}$/;
+export function maintenanceLeaseFile(env = process.env) {
+    return join(rynxHome(env), "maintenance-lease.json");
+}
+/**
+ * Cross-process admission fence used only during daemon replacement.
+ *
+ * The raw bearer token is never persisted. The bounded expiry means a crashed
+ * upgrader cannot leave the daemon permanently unavailable, while atomic rename
+ * ensures a replacement daemon sees either the complete lease or no lease.
+ */
+export class MaintenanceLeaseStore {
+    filePath;
+    now;
+    ttlMs;
+    syncDirectory;
+    onExpired;
+    lease;
+    expiryTimer;
+    constructor(options = {}) {
+        this.filePath = options.filePath ?? maintenanceLeaseFile();
+        this.now = options.now ?? (() => Date.now());
+        this.ttlMs = options.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.syncDirectory = options.syncDirectory ?? fsyncDirectory;
+        this.onExpired = options.onExpired ?? (() => undefined);
+        if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs <= 0) {
+            throw new Error("maintenance lease TTL must be a positive safe integer");
+        }
+        this.lease = this.readPersistedLease();
+        this.scheduleExpiry();
+    }
+    isActive() {
+        if (!this.lease)
+            return false;
+        if (this.lease.expiresAt > this.now())
+            return true;
+        this.expire();
+        return false;
+    }
+    isHeldBy(token) {
+        let tokenHash;
+        try {
+            tokenHash = hashLeaseToken(token);
+        }
+        catch {
+            return false;
+        }
+        return Boolean(this.isActive()
+            && this.lease
+            && hashesEqual(this.lease.tokenHash, tokenHash));
+    }
+    acquire(token) {
+        const tokenHash = hashLeaseToken(token);
+        if (this.isActive()) {
+            if (this.lease && hashesEqual(this.lease.tokenHash, tokenHash)) {
+                const createdAt = this.now();
+                const renewed = {
+                    schemaVersion: LEASE_SCHEMA_VERSION,
+                    tokenHash,
+                    createdAt,
+                    expiresAt: createdAt + this.ttlMs,
+                };
+                // Fail closed in memory if persistence reaches an indeterminate I/O
+                // outcome; the caller sees the error, but this process must not reopen
+                // admission around a lease file that may already have been renamed.
+                this.lease = renewed;
+                try {
+                    this.writePersistedLease(renewed);
+                }
+                finally {
+                    this.scheduleExpiry();
+                }
+                return false;
+            }
+            throw new Error("a different maintenance lease is already active");
+        }
+        const createdAt = this.now();
+        const lease = {
+            schemaVersion: LEASE_SCHEMA_VERSION,
+            tokenHash,
+            createdAt,
+            expiresAt: createdAt + this.ttlMs,
+        };
+        this.lease = lease;
+        try {
+            this.writePersistedLease(lease);
+        }
+        finally {
+            this.scheduleExpiry();
+        }
+        return true;
+    }
+    release(token) {
+        if (!this.isActive())
+            return "not_active";
+        const lease = this.lease;
+        if (!lease)
+            return "not_active";
+        let tokenHash;
+        try {
+            tokenHash = hashLeaseToken(token);
+        }
+        catch {
+            return "denied";
+        }
+        if (!hashesEqual(lease.tokenHash, tokenHash))
+            return "denied";
+        this.clear();
+        return "released";
+    }
+    readPersistedLease() {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
+        }
+        catch (error) {
+            if (error
+                && typeof error === "object"
+                && "code" in error
+                && error.code === "ENOENT")
+                return undefined;
+            throw new Error("maintenance lease state is unreadable", { cause: error });
+        }
+        if (!isPersistedLease(parsed, this.ttlMs)) {
+            throw new Error("maintenance lease state is invalid");
+        }
+        if (parsed.expiresAt <= this.now()) {
+            this.clearFile();
+            return undefined;
+        }
+        return parsed;
+    }
+    writePersistedLease(lease) {
+        const parent = dirname(this.filePath);
+        mkdirSync(parent, { recursive: true, mode: 0o700 });
+        const temporary = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+        let descriptor;
+        try {
+            descriptor = openSync(temporary, "wx", 0o600);
+            writeFileSync(descriptor, `${JSON.stringify(lease)}\n`, "utf8");
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporary, this.filePath);
+            this.syncDirectory(parent);
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            rmSync(temporary, { force: true });
+        }
+    }
+    clear() {
+        this.clearFile();
+        this.lease = undefined;
+        this.cancelExpiry();
+    }
+    clearFile() {
+        rmSync(this.filePath, { force: true });
+        this.syncDirectory(dirname(this.filePath));
+    }
+    expire() {
+        this.clear();
+        this.onExpired();
+    }
+    scheduleExpiry(delayOverride) {
+        this.cancelExpiry();
+        if (!this.lease)
+            return;
+        const delay = delayOverride ?? Math.max(0, this.lease.expiresAt - this.now());
+        this.expiryTimer = setTimeout(() => {
+            this.expiryTimer = undefined;
+            if (!this.lease)
+                return;
+            if (this.lease.expiresAt > this.now()) {
+                this.scheduleExpiry();
+                return;
+            }
+            try {
+                this.expire();
+            }
+            catch {
+                // Keep the in-memory fence and retry cleanup. A failed durability
+                // operation must not turn an expired lease into open admission.
+                this.scheduleExpiry(EXPIRY_RETRY_MS);
+            }
+        }, Math.min(delay, MAX_TIMER_DELAY_MS));
+        this.expiryTimer.unref?.();
+    }
+    cancelExpiry() {
+        if (this.expiryTimer)
+            clearTimeout(this.expiryTimer);
+        this.expiryTimer = undefined;
+    }
+}
+function fsyncDirectory(directory) {
+    let descriptor;
+    try {
+        descriptor = openSync(directory, "r");
+        fsyncSync(descriptor);
+    }
+    catch (error) {
+        if (error
+            && typeof error === "object"
+            && "code" in error
+            && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function hashLeaseToken(token) {
+    if (!LEASE_TOKEN_PATTERN.test(token)) {
+        throw new Error("maintenance lease token must be 32-256 base64url characters");
+    }
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+function hashesEqual(left, right) {
+    const leftBuffer = Buffer.from(left, "hex");
+    const rightBuffer = Buffer.from(right, "hex");
+    return leftBuffer.length === rightBuffer.length
+        && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function isPersistedLease(value, maximumTtlMs) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return candidate.schemaVersion === LEASE_SCHEMA_VERSION
+        && typeof candidate.tokenHash === "string"
+        && /^[a-f0-9]{64}$/.test(candidate.tokenHash)
+        && Number.isSafeInteger(candidate.createdAt)
+        && Number.isSafeInteger(candidate.expiresAt)
+        && candidate.createdAt >= 0
+        && candidate.expiresAt > candidate.createdAt
+        && candidate.expiresAt - candidate.createdAt <= maximumTtlMs;
+}

package/dist/migrations/cleanup-legacy-sessions.d.ts

@@ -1,5 +1,5 @@
 export interface CleanupOptions {
-    /** CodexSessionStore JSON path; defaults to `<cwd>/.codex-proxy/sessions.json`. */
+    /** CodexSessionStore JSON path; defaults to `{RYNX_HOME}/.codex-proxy/sessions.json`. */
     codexStorePath?: string;
     /** Report what would be removed without deleting anything. */
     dryRun?: boolean;

package/dist/migrations/cleanup-legacy-sessions.js

@@ -8,20 +8,21 @@
  *   - canonical-log rows (`session_items`) and identity rows (`sessions`) whose
  *     id is not an opaque `sess_` id,
  *   - the daemon-owned runtime thread→rollout bindings in
- *     `.codex-proxy/sessions.json` that use a legacy id.
+ *     `.codex-proxy/sessions.json` that no longer have a Session row. This also
+ *     removes opaque bindings left behind by the snapshot-schema cutover.
  *
  * Runs on every daemon boot (not marker-gated): on a healthy system it deletes
  * nothing and writes nothing, so it is cheap; if a legacy session ever appears
- * the next boot removes it. The `sess_` filter means it can never touch a
- * current session. Plugin-private routing stores are deliberately not read.
+ * the next boot removes it. Plugin-private routing stores are deliberately not
+ * read.
  */
 import { mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import path from "node:path";
-import { isMachineSessionId } from "@rynx-ai/core";
+import { rynxHome } from "@rynx-ai/core";
 import { db } from "../db.js";
 /** Mirrors the daemon runtime store's default resolution. */
 function defaultProxyDir() {
-    return path.join(process.cwd(), ".codex-proxy");
+    return path.join(rynxHome(), ".codex-proxy");
 }
 // Anything whose id isn't an opaque `sess_` id is legacy. GLOB treats `_` as a
 // literal (unlike LIKE), so `sess_*` matches exactly the new id shape.
@@ -31,11 +32,14 @@ export function cleanupLegacySessions(opts = {}) {
     const log = opts.log ?? (() => { });
     const dryRun = Boolean(opts.dryRun);
     const conn = db();
-    const codexStorePath = opts.codexStorePath ?? path.join(defaultProxyDir(), "sessions.json");
+    const liveSessionIds = new Set(conn.prepare("SELECT id FROM sessions").all().map((row) => row.id));
+    const codexStorePath = opts.codexStorePath
+        ? path.resolve(rynxHome(), opts.codexStorePath)
+        : path.join(defaultProxyDir(), "sessions.json");
     if (dryRun) {
         const deletedLogRows = countRows(conn, `SELECT COUNT(*) AS n FROM session_items WHERE ${LEGACY_LOG}`);
         const deletedSessions = countRows(conn, `SELECT COUNT(*) AS n FROM sessions WHERE ${LEGACY_META}`);
-        const prunedStoreEntries = countLegacyStoreEntries(readJsonStore(codexStorePath), (key) => key);
+        const prunedStoreEntries = countOrphanedStoreEntries(readJsonStore(codexStorePath), (key) => key, liveSessionIds);
         log({ event: "cleanup.dry_run", deletedLogRows, deletedSessions, prunedStoreEntries });
         return { dryRun: true, deletedLogRows, deletedSessions, prunedStoreEntries };
     }
@@ -48,7 +52,7 @@ export function cleanupLegacySessions(opts = {}) {
     })();
     // The runtime store is daemon-owned. Plugin routing stores remain private to
     // their plugins and are never inspected by this migration.
-    prunedStoreEntries += pruneStore(codexStorePath, (key) => key);
+    prunedStoreEntries += pruneStore(codexStorePath, (key) => key, liveSessionIds);
     if (deletedLogRows || deletedSessions || prunedStoreEntries) {
         log({ event: "cleanup.done", deletedLogRows, deletedSessions, prunedStoreEntries });
     }
@@ -57,31 +61,45 @@ export function cleanupLegacySessions(opts = {}) {
 function countRows(conn, sql) {
     return conn.prepare(sql).get().n;
 }
-function countLegacyStoreEntries(data, idOf) {
+function countOrphanedStoreEntries(data, idOf, liveSessionIds) {
     let n = 0;
     for (const [key, record] of Object.entries(data.sessions ?? {})) {
         const id = idOf(key, record);
-        if (typeof id === "string" && !isMachineSessionId(id))
+        if (typeof id === "string" && !liveSessionIds.has(id))
+            n += 1;
+    }
+    for (const key of Object.keys(data.claudeForkIntents ?? {})) {
+        if (!liveSessionIds.has(key))
             n += 1;
     }
     return n;
 }
-/** Drop every legacy entry from a JSON store; returns how many were removed. */
-function pruneStore(file, idOf) {
+/** Drop every binding whose owning Session no longer exists. */
+function pruneStore(file, idOf, liveSessionIds) {
     const data = readJsonStore(file);
-    if (!data.sessions)
+    if (!data.sessions && !data.claudeForkIntents)
         return 0;
     let pruned = 0;
     const kept = {};
-    for (const [key, record] of Object.entries(data.sessions)) {
+    for (const [key, record] of Object.entries(data.sessions ?? {})) {
         const id = idOf(key, record);
-        if (typeof id === "string" && !isMachineSessionId(id)) {
+        if (typeof id === "string" && !liveSessionIds.has(id)) {
             pruned += 1;
         }
         else {
             kept[key] = record;
         }
     }
+    if (data.claudeForkIntents) {
+        const keptIntents = {};
+        for (const [targetSessionId, intent] of Object.entries(data.claudeForkIntents)) {
+            if (liveSessionIds.has(targetSessionId))
+                keptIntents[targetSessionId] = intent;
+            else
+                pruned += 1;
+        }
+        data.claudeForkIntents = keptIntents;
+    }
     if (pruned > 0) {
         data.sessions = kept;
         writeJsonStore(file, data);

package/dist/official-plugins.d.ts

@@ -0,0 +1,2 @@
+export declare const OFFICIAL_MARKETPLACE_ID = "rynx-ai/rynx";
+export declare const DEFAULT_BUNDLED_PLUGINS: readonly ["lark@rynx-ai/rynx"];

package/dist/official-plugins.js

@@ -0,0 +1,2 @@
+export const OFFICIAL_MARKETPLACE_ID = "rynx-ai/rynx";
+export const DEFAULT_BUNDLED_PLUGINS = ["lark@rynx-ai/rynx"];

package/dist/plugin-cli.d.ts

@@ -1,4 +1,3 @@
-import { type PluginCliHostEffect } from "@rynx-ai/plugin-sdk";
 import { type RunnablePluginRecord } from "./plugin-store.js";
 export interface RunPluginCliOptions {
     stdio?: "inherit" | "pipe";
@@ -14,7 +13,6 @@ export interface RunPluginCliOptions {
 }
 export interface PluginCliCommandResult {
     code: number;
-    effects: PluginCliHostEffect[];
     output?: {
         stdout: string;
         stderr: string;
@@ -22,7 +20,7 @@ export interface PluginCliCommandResult {
         stderrTruncated: boolean;
     };
 }
-/** Execute one statically declared plugin command in a separate Node process. */
+/** Execute one statically declared, language-neutral plugin command. */
 export declare function runPluginCliCommand(pluginId: string, args: readonly string[], options?: RunPluginCliOptions): Promise<PluginCliCommandResult>;
 export declare function pluginCommandUsage(record: RunnablePluginRecord): string;
 export declare class PluginCliUsageError extends Error {

package/dist/plugin-cli.js

@@ -1,14 +1,15 @@
 import { spawn } from "node:child_process";
 import { mkdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
-import { rynxHome } from "@rynx-ai/core";
-import { createPluginCliInvocationLeaseId, parsePluginCliHostEffect, removePluginRuntimeLease, writePluginRuntimeLease, } from "@rynx-ai/plugin-sdk";
+import { createPluginCliInvocationLeaseId, removePluginRuntimeLease, writePluginRuntimeLease, } from "@rynx-ai/plugin-sdk";
 import { db } from "./db.js";
-import { getPlugin, isRunnablePluginRecord } from "./plugin-store.js";
+import { pluginDataDir, pluginRuntimeCacheDir } from "./plugin-installer.js";
+import { validatePluginPackageSnapshot } from "./plugin-package.js";
+import { getPlugin } from "./plugin-store.js";
 import { loadOrCreateDaemonInstallationIdentitySync } from "./installation-id.js";
 const DEFAULT_TERMINATION_GRACE_MS = 2_000;
 const MAX_TERMINATION_GRACE_MS = 30_000;
-/** Execute one statically declared plugin command in a separate Node process. */
+/** Execute one statically declared, language-neutral plugin command. */
 export async function runPluginCliCommand(pluginId, args, options = {}) {
     const hostEnv = options.env ?? process.env;
     const terminationGraceMs = options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS;
@@ -21,7 +22,6 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
     let terminationReason;
     let forceKillTimer;
     let abortListener;
-    const effects = new Map();
     if (options.stdin !== undefined && options.stdio !== "pipe") {
         throw new Error("plugin CLI stdin requires piped stdio");
     }
@@ -37,6 +37,13 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
     if (options.signal?.aborted)
         throw pluginCliAbortError(options.signal.reason);
     const installationIdentity = loadOrCreateDaemonInstallationIdentitySync(hostEnv);
+    const verifiedRecord = getPlugin(pluginId);
+    if (!verifiedRecord)
+        throw new Error(`plugin "${pluginId}" is not installed`);
+    const verifiedIntegrity = await validatePluginPackageSnapshot(verifiedRecord.installPath, options.signal ? { signal: options.signal } : {});
+    if (verifiedIntegrity !== verifiedRecord.integrity) {
+        throw new Error(`plugin package integrity changed for "${verifiedRecord.canonicalId}"`);
+    }
     const clearForceKill = () => {
         if (forceKillTimer)
             clearTimeout(forceKillTimer);
@@ -47,24 +54,14 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
         terminationReason ??= reason;
         if (!childIsRunning())
             return;
-        try {
-            child.kill("SIGTERM");
-        }
-        catch {
-            // The close/error event remains authoritative for cleanup.
-        }
+        signalChildTree(child, "SIGTERM");
         if (forceKillTimer)
             return;
         forceKillTimer = setTimeout(() => {
             forceKillTimer = undefined;
             if (!childIsRunning())
                 return;
-            try {
-                child.kill("SIGKILL");
-            }
-            catch {
-                // Completion still waits for close/error; no lease is removed early.
-            }
+            signalChildTree(child, "SIGKILL");
         }, terminationGraceMs);
         forceKillTimer.unref?.();
     };
@@ -81,14 +78,13 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
             const record = getPlugin(pluginId);
             if (!record)
                 throw new Error(`plugin "${pluginId}" is not installed`);
-            if (!isRunnablePluginRecord(record)) {
-                throw new Error(`plugin "${pluginId}" uses the removed legacy format; reinstall it`);
+            if (record.integrity !== verifiedRecord.integrity ||
+                record.installPath !== verifiedRecord.installPath ||
+                record.updatedAt !== verifiedRecord.updatedAt) {
+                throw new Error(`plugin "${pluginId}" changed while its command was being prepared; retry`);
             }
-            // `enabled` controls daemon runtime contributions, not explicit CLI calls.
-            // Keeping commands available lets a user stop/status a managed service before
-            // uninstalling a disabled plugin.
             const command = args[0];
-            const declared = record.manifest.contributions?.commands?.find((entry) => entry.id === command);
+            const declared = record.manifest.commands?.items.find((entry) => entry.id === command);
             if (!command ||
                 command === "--help" ||
                 command === "-h" ||
@@ -98,41 +94,40 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
             if (!declared) {
                 throw new PluginCliUsageError(`plugin "${pluginId}" does not declare command "${command}"\n\n${pluginCommandUsage(record)}`);
             }
-            if (!record.manifest.cliEntry) {
-                throw new Error(`plugin "${pluginId}" declares commands but has no cliEntry`);
+            if (!record.manifest.commands) {
+                throw new Error(`plugin "${pluginId}" declares no CLI command executable`);
             }
             const packageRoot = realpathSync(record.installPath);
-            const cliEntry = realpathSync(path.resolve(packageRoot, record.manifest.cliEntry));
+            const cliEntry = realpathSync(path.resolve(packageRoot, record.manifest.commands.command));
             if (!isPathInside(packageRoot, cliEntry) || !statSync(cliEntry).isFile()) {
-                throw new Error(`plugin "${pluginId}" cliEntry resolves outside its package`);
+                throw new Error(`plugin "${pluginId}" commands.command resolves outside its package`);
             }
-            dataDir = path.join(rynxHome(), "plugin-data", record.name);
+            dataDir = pluginDataDir(record.marketplaceId, record.pluginId);
+            const cacheDir = pluginRuntimeCacheDir(record.marketplaceId, record.pluginId, record.integrity);
             mkdirSync(dataDir, { recursive: true, mode: 0o700 });
-            child = spawn(process.execPath, [cliEntry, ...args], {
+            mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+            child = spawn(cliEntry, [...args], {
                 cwd: dataDir,
                 env: {
-                    ...hostEnv,
+                    PATH: hostEnv.PATH,
+                    HOME: hostEnv.HOME,
+                    TMPDIR: hostEnv.TMPDIR,
+                    LANG: hostEnv.LANG,
                     RYNX_HOST_INSTALLATION_ID: installationIdentity.installationId,
                     RYNX_HOST_INSTALLATION_PROOF_ALGORITHM: installationIdentity.algorithm,
                     RYNX_HOST_INSTALLATION_PUBLIC_KEY: installationIdentity.publicKey,
-                    RYNX_PLUGIN_ID: record.name,
+                    RYNX_PLUGIN_ID: record.pluginId,
+                    RYNX_PLUGIN_INSTALLATION_ID: record.canonicalId,
                     RYNX_PLUGIN_PACKAGE_ROOT: packageRoot,
                     RYNX_PLUGIN_DATA_DIR: dataDir,
+                    RYNX_PLUGIN_CACHE_DIR: cacheDir,
                 },
                 stdio: options.stdio === "pipe"
-                    ? ["pipe", "pipe", "pipe", "ipc"]
-                    : ["inherit", "inherit", "inherit", "ipc"],
+                    ? ["pipe", "pipe", "pipe"]
+                    : ["inherit", "inherit", "inherit"],
+                detached: process.platform !== "win32",
             });
             completion = new Promise((resolve, reject) => {
-                child.on("message", (message) => {
-                    try {
-                        const effect = parsePluginCliHostEffect(message);
-                        effects.set(effect.effect, effect);
-                    }
-                    catch (error) {
-                        terminateChild(error instanceof Error ? error : new Error(String(error)));
-                    }
-                });
                 child.once("error", (error) => {
                     if (!childIsRunning()) {
                         reject(error);
@@ -172,7 +167,7 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
             leaseId = createPluginCliInvocationLeaseId(child.pid ?? process.pid);
             writePluginRuntimeLease({
                 dataDir,
-                pluginId: record.name,
+                pluginId: record.pluginId,
                 leaseId,
                 installPath: packageRoot,
             });
@@ -193,7 +188,6 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
         const code = await completion;
         return {
             code,
-            effects: code === 0 ? [...effects.values()] : [],
             ...(options.captureOutputBytes !== undefined && stdout && stderr
                 ? {
                     output: {
@@ -210,6 +204,23 @@ export async function runPluginCliCommand(pluginId, args, options = {}) {
         cleanup();
     }
 }
+function signalChildTree(child, signal) {
+    if (process.platform !== "win32" && child.pid) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // Fall back to the direct child if its process group already exited.
+        }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch {
+        // Completion still waits for close/error; no lease is removed early.
+    }
+}
 function pluginCliAbortError(reason) {
     const error = new Error(reason instanceof Error && reason.message ? reason.message : "plugin CLI command aborted");
     error.name = reason instanceof Error && reason.name === "TimeoutError"
@@ -246,7 +257,7 @@ function captureStream(stream, limit) {
     };
 }
 export function pluginCommandUsage(record) {
-    const commands = record.manifest.contributions?.commands ?? [];
+    const commands = record.manifest.commands?.items ?? [];
     const lines = [`Usage: rynx plugin ${record.name} <command> [args...]`];
     if (commands.length === 0)
         return [...lines, "", "This plugin declares no CLI commands."].join("\n");

package/dist/plugin-host-leases.d.ts

@@ -0,0 +1,4 @@
+/** Fixed leases owned by the resident daemon's plugin supervisor. A new daemon
+ * may reclaim these only after it has acquired the exclusive RYNX_HOME owner
+ * lock and before starting any plugin runners. */
+export declare const PLUGIN_HOST_RUNTIME_LEASE_IDS: readonly ["host-runtime", "host-settings"];

package/dist/plugin-host-leases.js

@@ -0,0 +1,7 @@
+/** Fixed leases owned by the resident daemon's plugin supervisor. A new daemon
+ * may reclaim these only after it has acquired the exclusive RYNX_HOME owner
+ * lock and before starting any plugin runners. */
+export const PLUGIN_HOST_RUNTIME_LEASE_IDS = [
+    "host-runtime",
+    "host-settings",
+];