@bitsocial/bitsocial-cli 0.19.64 → 0.19.66

package/dist/cli/commands/challenge/list.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "@oclif/core";
 export default class List extends Command {
     static description: string;
+    static aliases: string[];
     static flags: {
         quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "pkcOptions.dataPath": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/cli/commands/challenge/list.js

@@ -1,10 +1,11 @@
 import { Flags, Command } from "@oclif/core";
 import { EOL } from "os";
-import { printTable } from "@oclif/table";
+import path from "path";
 import defaults from "../../../common-utils/defaults.js";
-import { listInstalledChallenges } from "../../../challenge-packages/challenge-utils.js";
+import { getChallengesDir, listInstalledChallenges, formatChallengeNameVersion } from "../../../challenge-packages/challenge-utils.js";
 export default class List extends Command {
     static description = "List installed challenge packages";
+    static aliases = ["challenge:ls"];
     static flags = {
         quiet: Flags.boolean({ char: "q", summary: "Only display challenge names" }),
         "pkcOptions.dataPath": Flags.directory({
@@ -16,7 +17,8 @@ export default class List extends Command {
     async run() {
         const { flags } = await this.parse(List);
         const dataPath = flags["pkcOptions.dataPath"] || defaults.PKC_DATA_PATH;
-        const challenges = await listInstalledChallenges(dataPath);
+        // Sort alphabetically like npm ls (readdir order is filesystem-dependent)
+        const challenges = (await listInstalledChallenges(dataPath)).sort((a, b) => a.name.localeCompare(b.name));
         if (challenges.length === 0) {
             this.log("No challenge packages installed.");
             return;
@@ -25,12 +27,11 @@ export default class List extends Command {
             this.log(challenges.map((c) => c.name).join(EOL));
         }
         else {
-            printTable({
-                data: challenges.map((c) => ({
-                    name: c.name,
-                    version: c.version,
-                    description: c.description
-                }))
+            // npm-ls-style tree: challenges dir header, then name@version entries
+            this.log(path.resolve(getChallengesDir(dataPath)));
+            challenges.forEach((c, i) => {
+                const branch = i === challenges.length - 1 ? "└── " : "├── ";
+                this.log(`${branch}${formatChallengeNameVersion(c)}`);
             });
         }
     }

package/dist/cli/commands/challenge/remove.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "@oclif/core";
 export default class Remove extends Command {
     static description: string;
+    static aliases: string[];
     static args: {
         name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/cli/commands/challenge/remove.js

@@ -2,9 +2,10 @@ import { Args, Flags, Command } from "@oclif/core";
 import fs from "fs/promises";
 import path from "path";
 import defaults from "../../../common-utils/defaults.js";
-import { getChallengesDir, challengeNameToDir } from "../../../challenge-packages/challenge-utils.js";
+import { getChallengesDir, challengeNameToDir, readChallengePackageJson } from "../../../challenge-packages/challenge-utils.js";
 export default class Remove extends Command {
     static description = "Remove an installed challenge package";
+    static aliases = ["challenge:uninstall", "challenge:rm", "challenge:un"];
     static args = {
         name: Args.string({
             description: "The challenge package name (e.g., my-challenge or @scope/my-challenge)",
@@ -33,6 +34,16 @@ export default class Remove extends Command {
         catch {
             this.error(`Challenge "${args.name}" is not installed.`);
         }
+        // Read the installed version for the success message (best-effort)
+        let version = "";
+        try {
+            const pkg = await readChallengePackageJson(challengeDir);
+            if (pkg.version)
+                version = `@${pkg.version}`;
+        }
+        catch {
+            // unreadable package.json — report the name only
+        }
         // Remove the challenge directory
         await fs.rm(challengeDir, { recursive: true, force: true });
         // Clean up empty @scope/ dir for scoped packages
@@ -48,7 +59,7 @@ export default class Remove extends Command {
                 // ignore
             }
         }
-        this.log(`Removed challenge '${args.name}'`);
+        this.log(`removed ${args.name}${version}`);
         // Best-effort reload via daemon
         try {
             await fetch("http://localhost:9138/api/challenges/reload", { method: "POST" });

package/dist/cli/commands/community/export.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from "../../base-command.js";
+export default class Export extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        address: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        publicKey: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        path: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        includePrivateKey: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private _printProgress;
+    run(): Promise<void>;
+    /** Start the export on the RPC server and resolve with the terminal record (progress === 1). */
+    private _runExport;
+    /** Download the finished snapshot to destPath, verifying its sha256 against the export record. */
+    private _downloadAndVerify;
+}

package/dist/cli/commands/community/export.js

@@ -0,0 +1,198 @@
+import { Args, Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import defaults from "../../../common-utils/defaults.js";
+import { PKCLogger } from "../../../util.js";
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+export default class Export extends BaseCommand {
+    static description = "Export a local community to a SQLite snapshot file. The export runs on the RPC server (daemon); once finished the snapshot is downloaded and its sha256 checksum is verified. Pass --includePrivateKey to produce a restorable backup that keeps the community's address.";
+    static examples = [
+        "bitsocial community export plebmusic.bso",
+        "bitsocial community export plebmusic.bso --includePrivateKey -o ./backups/plebmusic.sqlite",
+        "bitsocial community export --name my-community",
+        "bitsocial community export --publicKey 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu"
+    ];
+    static args = {
+        address: Args.string({
+            name: "address",
+            required: false,
+            description: "Address of the community to export"
+        })
+    };
+    static flags = {
+        name: Flags.string({
+            description: "Name of the community to export"
+        }),
+        publicKey: Flags.string({
+            description: "Public key of the community to export"
+        }),
+        path: Flags.string({
+            char: "o",
+            description: "Destination file for the downloaded snapshot (default: <dataPath>/exports/<address>_<datetime>.sqlite)"
+        }),
+        includePrivateKey: Flags.boolean({
+            default: false,
+            description: "Ask the RPC server to include the community signer's private key in the export. Required for a restorable backup that keeps the same community address. The daemon may refuse (see `bitsocial daemon --no-allowPrivateKeyExport`)"
+        }),
+        force: Flags.boolean({
+            default: false,
+            description: "Overwrite the destination file if it already exists"
+        }),
+        quiet: Flags.boolean({
+            char: "q",
+            default: false,
+            description: "Suppress progress output; only print the path of the downloaded snapshot"
+        })
+    };
+    _printProgress(quiet, message) {
+        if (!quiet)
+            process.stderr.write(message);
+    }
+    async run() {
+        const { args, flags } = await this.parse(Export);
+        const log = PKCLogger("bitsocial-cli:commands:community:export");
+        log(`args: `, args);
+        log(`flags: `, flags);
+        const lookupParam = {};
+        if (args.address)
+            lookupParam.address = args.address;
+        if (flags.name)
+            lookupParam.name = flags.name;
+        if (flags.publicKey)
+            lookupParam.publicKey = flags.publicKey;
+        if (Object.keys(lookupParam).length === 0) {
+            this.error("At least one of address argument, --name, or --publicKey must be provided");
+        }
+        const pkc = await this._connectToPkcRpc(flags.pkcRpcUrl.toString());
+        // Cancel the in-flight export server-side on Ctrl+C. A second Ctrl+C force-exits
+        // (the handler is registered with `once`, so the default SIGINT behavior is restored).
+        const abortController = new AbortController();
+        const onSigint = () => {
+            this._printProgress(flags.quiet, "\nCancelling export... (Ctrl+C again to force exit)\n");
+            abortController.abort();
+        };
+        process.once("SIGINT", onSigint);
+        try {
+            const community = (await pkc.createCommunity(lookupParam));
+            if (typeof community.export !== "function") {
+                this.error(`Community is not local to the RPC server at ${flags.pkcRpcUrl}. Only communities created on this daemon can be exported`);
+            }
+            const exportableCommunity = community;
+            // Datetime in the filename matches the daemon log convention (ISO 8601 with ':' → '-')
+            // so repeated exports never collide and snapshots sort chronologically
+            const defaultFilename = `${exportableCommunity.address}_${new Date().toISOString().replace(/:/g, "-")}.sqlite`;
+            const destPath = path.resolve(flags.path ?? path.join(defaults.PKC_DATA_PATH, "exports", defaultFilename));
+            const destExists = await fs
+                .stat(destPath)
+                .then(() => true)
+                .catch(() => false);
+            if (destExists && !flags.force) {
+                this.error(`Destination file already exists: ${destPath}. Use --force to overwrite it`);
+            }
+            const finishedRecord = await this._runExport(exportableCommunity, flags.includePrivateKey, abortController.signal, flags.quiet);
+            log("Export finished on the RPC server", finishedRecord);
+            if (!finishedRecord.url) {
+                this.error(`Export ${finishedRecord.exportId} finished but the RPC server did not provide a download URL`);
+            }
+            // Mirrors pkc-js's rpcHttpOrigin: the ws[s]:// RPC URL with the protocol swapped to http[s]://
+            const parsedRpcUrl = new URL(flags.pkcRpcUrl.toString());
+            const expectedDownloadOrigin = `${parsedRpcUrl.protocol === "wss:" ? "https:" : "http:"}//${parsedRpcUrl.host}`;
+            await this._downloadAndVerify(finishedRecord, destPath, abortController.signal, flags.quiet, expectedDownloadOrigin);
+            this.log(destPath);
+        }
+        catch (e) {
+            console.error(e);
+            await pkc.destroy();
+            this.exit(1);
+        }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+        }
+        await pkc.destroy();
+    }
+    /** Start the export on the RPC server and resolve with the terminal record (progress === 1). */
+    async _runExport(community, includePrivateKey, signal, quiet) {
+        const { exportId } = await community.export({ includePrivateKey, signal });
+        return new Promise((resolve, reject) => {
+            let lastPrintedPercent = -1;
+            const cleanup = () => {
+                community.removeListener("exportschange", checkRecords);
+                signal.removeEventListener("abort", onAbort);
+            };
+            // Don't wait for the server's terminal ERR_EXPORT_CANCELLED record — it never arrives if the
+            // daemon died or the connection dropped. pkc-js's own abort listener (registered inside
+            // community.export(), before this one) already dispatched cancelExport() to the server.
+            const onAbort = () => {
+                cleanup();
+                reject(new Error("Export cancelled"));
+            };
+            const checkRecords = (records) => {
+                const record = records.find((rec) => rec.exportId === exportId);
+                if (!record)
+                    return;
+                if (record.error) {
+                    cleanup();
+                    reject(new Error(`Export failed (${record.error.code}): ${record.error.message}`));
+                }
+                else if (record.progress === 1) {
+                    cleanup();
+                    this._printProgress(quiet, `\rExporting ${community.address}: 100%\n`);
+                    resolve(record);
+                }
+                else {
+                    const percent = Math.floor(record.progress * 100);
+                    if (percent !== lastPrintedPercent) {
+                        lastPrintedPercent = percent;
+                        this._printProgress(quiet, `\rExporting ${community.address}: ${percent}%`);
+                    }
+                }
+            };
+            community.on("exportschange", checkRecords);
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted)
+                return onAbort();
+            // The terminal notification may have arrived before the listener was attached
+            checkRecords(community.exports);
+        });
+    }
+    /** Download the finished snapshot to destPath, verifying its sha256 against the export record. */
+    async _downloadAndVerify(record, destPath, signal, quiet, expectedOrigin) {
+        // The export download contract is GET <rpc-http-origin>/exports/<exportId> — refuse anything else
+        // so a misconfigured/compromised RPC server can't use the CLI to fetch arbitrary URLs
+        const downloadUrl = new URL(record.url);
+        if (downloadUrl.origin !== expectedOrigin || !downloadUrl.pathname.startsWith("/exports/")) {
+            this.error(`Refusing to download export from unexpected URL ${record.url} (expected ${expectedOrigin}/exports/<exportId>)`);
+        }
+        this._printProgress(quiet, `Downloading snapshot from ${downloadUrl}\n`);
+        const response = await fetch(downloadUrl, { signal });
+        if (!response.ok || !response.body) {
+            this.error(`Failed to download export from ${record.url}: HTTP ${response.status}`);
+        }
+        await fs.mkdir(path.dirname(destPath), { recursive: true });
+        // Download to a .partial file so an interrupted/corrupted download never clobbers destPath
+        const partialPath = destPath + ".partial";
+        const hash = createHash("sha256");
+        try {
+            await pipeline(Readable.fromWeb(response.body), async function* (source) {
+                for await (const chunk of source) {
+                    hash.update(chunk);
+                    yield chunk;
+                }
+            }, createWriteStream(partialPath));
+            const downloadedSha256 = hash.digest("hex");
+            if (record.sha256 && downloadedSha256 !== record.sha256) {
+                throw new Error(`sha256 mismatch for downloaded export: expected ${record.sha256} but downloaded file hashes to ${downloadedSha256}`);
+            }
+            await fs.rename(partialPath, destPath);
+        }
+        catch (e) {
+            await fs.rm(partialPath, { force: true }).catch(() => { });
+            throw e;
+        }
+        this._printProgress(quiet, `Verified sha256 (${record.sha256}) and saved snapshot${record.size ? ` (${record.size} bytes)` : ""}\n`);
+    }
+}

package/dist/cli/commands/daemon.d.ts

@@ -26,6 +26,7 @@ export default class Daemon extends Command {
         pkcRpcUrl: import("@oclif/core/interfaces").OptionFlag<import("url").URL, import("@oclif/core/interfaces").CustomOptions>;
         logPath: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         chainProviderUrls: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        allowPrivateKeyExport: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static examples: string[];
     private _setupLogger;

package/dist/cli/commands/daemon.js

@@ -6,7 +6,7 @@ import tcpPortUsed from "tcp-port-used";
 import { getLanIpV4Address, PKCLogger, setupDebugLogger, loadKuboConfigFile, parseMultiAddrKuboRpcToUrl, parseMultiAddrIpfsGatewayToUrl } from "../../util.js";
 import { startDaemonServer } from "../../webui/daemon-server.js";
 import { printBanner } from "../ascii-banner.js";
-import { loadChallengesIntoPKC } from "../../challenge-packages/challenge-utils.js";
+import { loadChallengesIntoPKC, formatChallengeNameVersion } from "../../challenge-packages/challenge-utils.js";
 import { migrateDataDirectory } from "../../common-utils/data-migration.js";
 import { createBsoResolvers, DEFAULT_PROVIDERS } from "../../common-utils/resolvers.js";
 import { pruneStaleStates, writeDaemonState, deleteDaemonState } from "../../common-utils/daemon-state.js";
@@ -83,6 +83,11 @@ export default class Daemon extends Command {
             description: "RPC URL(s) for .bso name resolution. Can be specified multiple times.",
             multiple: true,
             default: DEFAULT_PROVIDERS
+        }),
+        allowPrivateKeyExport: Flags.boolean({
+            description: "Allow RPC clients to request community exports that include the community signer's private key (`bitsocial community export --includePrivateKey`). Disable with --no-allowPrivateKeyExport when exposing the RPC to untrusted clients",
+            allowNo: true,
+            default: true
         })
     };
     static examples = [
@@ -91,6 +96,7 @@ export default class Daemon extends Command {
         "bitsocial daemon --pkcOptions.dataPath /tmp/bitsocial-datapath/",
         "bitsocial daemon --pkcOptions.kuboRpcClientsOptions[0] https://remoteipfsnode.com",
         "bitsocial daemon --chainProviderUrls https://mainnet.infura.io/v3/YOUR_KEY",
+        "bitsocial daemon --no-allowPrivateKeyExport",
     ];
     _setupLogger(Logger) {
         setupDebugLogger(Logger, { enableDefaultNamespace: true });
@@ -187,7 +193,8 @@ export default class Daemon extends Command {
         return { logFilePath, stdoutWrite, fileLogger };
     }
     async run() {
-        printBanner();
+        // Daemon output is often viewed through Docker/systemd logs where stdout is not a TTY.
+        printBanner({ forceColor: true });
         // Non-blocking update check — fire-and-forget, won't delay startup
         import("../../update/npm-registry.js")
             .then(({ fetchLatestVersion }) => fetchLatestVersion().then(async (latest) => {
@@ -268,7 +275,10 @@ export default class Daemon extends Command {
             let pendingKuboStart;
             // Kubo Node may fail randomly, we need to set a listener so when it exits because of an error we restart it
             let kuboProcess;
-            const keepKuboUp = async () => {
+            // Every kubo we've spawned that hasn't exited yet. Exit cleanup kills all of these,
+            // so a kubo that slipped out of kuboProcess tracking still dies with the daemon (issue #70)
+            const liveKuboPids = new Set();
+            const keepKuboUpOnce = async () => {
                 if (mainProcessExited)
                     return;
                 const kuboApiPort = Number(kuboRpcEndpoint.port);
@@ -276,6 +286,17 @@ export default class Daemon extends Command {
                     return; // already started, no need to intervene
                 const connectHostname = toConnectableHostname(kuboRpcEndpoint.hostname);
                 const isKuboApiPortTaken = await tcpPortUsed.check(kuboApiPort, connectHostname);
+                // Test hook: widens the window between the re-entrancy guard above and the pendingKuboStart
+                // assignment below, so tests can deterministically reproduce concurrent keepKuboUp entries
+                // (issue #70, see test/cli/daemon-kubo-restart-race.test.ts)
+                const portCheckDelayRaw = process.env["PKC_CLI_TEST_KEEPKUBOUP_PORTCHECK_DELAY_MS"];
+                const portCheckDelay = portCheckDelayRaw ? Number(portCheckDelayRaw) : 0;
+                if (Number.isFinite(portCheckDelay) && portCheckDelay > 0)
+                    await new Promise((resolve) => setTimeout(resolve, portCheckDelay));
+                // Re-check after the awaits above: the daemon may have begun shutting down, or another
+                // kubo may have been adopted in the meantime — spawning now would race it (issue #70)
+                if (mainProcessExited || kuboProcess || pendingKuboStart)
+                    return;
                 if (isKuboApiPortTaken) {
                     const connectableEndpoint = new URL(kuboRpcEndpoint.toString());
                     connectableEndpoint.hostname = connectHostname;
@@ -299,8 +320,15 @@ export default class Daemon extends Command {
                     }
                     throw new Error(`Cannot start IPFS daemon because the IPFS API port ${kuboRpcEndpoint.hostname}:${kuboApiPort} (configured as ${kuboRpcEndpoint.toString()}) is already in use.`);
                 }
+                let spawnedProcess;
                 const startPromise = startKuboNode(kuboRpcEndpoint, ipfsGatewayEndpoint, mergedPkcOptions.dataPath, (process) => {
+                    spawnedProcess = process;
                     kuboProcess = process;
+                    if (process.pid) {
+                        const pid = process.pid;
+                        liveKuboPids.add(pid);
+                        process.once("exit", () => liveKuboPids.delete(pid));
+                    }
                 });
                 pendingKuboStart = startPromise;
                 let startedProcess;
@@ -308,12 +336,15 @@ export default class Daemon extends Command {
                     startedProcess = await startPromise;
                 }
                 catch (error) {
-                    pendingKuboStart = undefined;
-                    if (!mainProcessExited)
+                    // Only clear state this attempt owns — it may track another attempt's healthy kubo (issue #70)
+                    if (pendingKuboStart === startPromise)
+                        pendingKuboStart = undefined;
+                    if (!mainProcessExited && spawnedProcess && kuboProcess === spawnedProcess)
                         kuboProcess = undefined;
                     throw error;
                 }
-                pendingKuboStart = undefined;
+                if (pendingKuboStart === startPromise)
+                    pendingKuboStart = undefined;
                 if (mainProcessExited) {
                     if (startedProcess?.pid && !startedProcess.killed) {
                         // Race condition: Kubo finished starting after mainProcessExited.
@@ -334,7 +365,8 @@ export default class Daemon extends Command {
                             /* best effort */
                         }
                     }
-                    kuboProcess = undefined;
+                    if (kuboProcess === startedProcess)
+                        kuboProcess = undefined;
                     return;
                 }
                 kuboProcess = startedProcess;
@@ -346,7 +378,8 @@ export default class Daemon extends Command {
                     // Restart Kubo process because it failed
                     if (!mainProcessExited) {
                         log(`Kubo node with pid (${currentProcess?.pid}) exited. Will attempt to restart it`);
-                        kuboProcess = undefined;
+                        if (kuboProcess === currentProcess)
+                            kuboProcess = undefined;
                         try {
                             await keepKuboUp();
                         }
@@ -360,6 +393,19 @@ export default class Daemon extends Command {
                 };
                 currentProcess.once("exit", onKuboExit);
             };
+            // Single-flight wrapper: keepKuboUp is invoked from independent places (the kubo exit
+            // handler and the watchdog interval). Concurrent callers must share one attempt —
+            // otherwise both can pass keepKuboUpOnce's re-entrancy guard during its awaits and
+            // spawn two kubo processes whose failure handling corrupts shared state (issue #70)
+            let keepKuboUpInFlight;
+            const keepKuboUp = () => {
+                if (!keepKuboUpInFlight) {
+                    keepKuboUpInFlight = keepKuboUpOnce().finally(() => {
+                        keepKuboUpInFlight = undefined;
+                    });
+                }
+                return keepKuboUpInFlight;
+            };
             let startedOwnRpc = false;
             let daemonServer;
             const createOrConnectRpc = async () => {
@@ -377,8 +423,10 @@ export default class Daemon extends Command {
                 // Load installed challenge packages before starting the RPC server
                 const loadedChallenges = await loadChallengesIntoPKC(mergedPkcOptions.dataPath);
                 if (loadedChallenges.length > 0)
-                    console.log(`Loaded challenge packages: ${loadedChallenges.join(", ")}`);
-                daemonServer = await startDaemonServer(pkcRpcUrl, ipfsGatewayEndpoint, mergedPkcOptions);
+                    console.log(`Loaded challenge packages: ${loadedChallenges.map(formatChallengeNameVersion).join(", ")}`);
+                daemonServer = await startDaemonServer(pkcRpcUrl, ipfsGatewayEndpoint, mergedPkcOptions, {
+                    allowPrivateKeyExport: flags.allowPrivateKeyExport
+                });
                 startedOwnRpc = true;
                 console.log(`pkc rpc: listening on ${pkcRpcUrl} (local connections only)`);
                 console.log(`pkc rpc: listening on ${pkcRpcUrl}${daemonServer.rpcAuthKey} (secret auth key for remote connections)`);
@@ -399,10 +447,6 @@ export default class Daemon extends Command {
                         console.log(`WebUI (${webui.name}${desc}): http://${remoteIpAddress}:${rpcPort}${webui.endpointRemote}`);
                 }
             };
-            // RPC port was already verified free above (fail-fast); only the kuboRpcClientsOptions branch skips local kubo.
-            if (!pkcOptionsFromFlag?.kuboRpcClientsOptions)
-                await keepKuboUp();
-            await createOrConnectRpc();
             let keepKuboUpInterval;
             const { asyncExitHook } = await import("exit-hook");
             const killKuboProcessGroup = (pid, signal) => {
@@ -424,14 +468,19 @@ export default class Daemon extends Command {
                 }
             };
             const killKuboProcess = async () => {
-                if (pendingKuboStart) {
-                    try {
-                        await pendingKuboStart;
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }
+                // Wait (bounded) for any in-flight start attempt so we kill the kubo it may still
+                // spawn. Both promises settle on all failure paths (issue #70), but a spawned kubo
+                // that wedges before "Daemon is ready" without exiting keeps them pending — the
+                // bound ensures shutdown still reaches the SIGINT/SIGKILL flow below, which kills
+                // it via kuboProcess (set in onSpawn) or the liveKuboPids sweep (PR #71 review).
+                const inFlightStarts = [keepKuboUpInFlight, pendingKuboStart]
+                    .filter((promise) => promise !== undefined)
+                    .map((promise) => promise.catch(() => { }));
+                if (inFlightStarts.length > 0)
+                    await Promise.race([
+                        Promise.all(inFlightStarts),
+                        new Promise((resolve) => setTimeout(resolve, 15_000).unref())
+                    ]);
                 if (kuboProcess?.pid && !kuboProcess.killed) {
                     const pid = kuboProcess.pid;
                     log("Attempting to kill kubo process with pid", pid);
@@ -461,6 +510,11 @@ export default class Daemon extends Command {
                         kuboProcess = undefined;
                     }
                 }
+                // Defense in depth: SIGKILL any spawned kubo that slipped out of kuboProcess
+                // tracking (e.g. via a state race) so nothing outlives the daemon (issue #70)
+                for (const pid of liveKuboPids)
+                    killKuboProcessGroup(pid, "SIGKILL");
+                liveKuboPids.clear();
             };
             asyncExitHook(async () => {
                 if (keepKuboUpInterval)
@@ -487,13 +541,62 @@ export default class Daemon extends Command {
             }, { wait: 120000 } // could take two minutes to shut down
             );
             // Emergency cleanup: if the process force-exits (e.g. double Ctrl+C),
-            // synchronously SIGKILL kubo's process group. This is a no-op if
-            // killKuboProcess() already ran (it sets kuboProcess = undefined).
+            // synchronously SIGKILL every live kubo's process group. This is a no-op if
+            // killKuboProcess() already ran (it clears kuboProcess and liveKuboPids).
             process.on("exit", () => {
                 if (kuboProcess?.pid) {
                     killKuboProcessGroup(kuboProcess.pid, "SIGKILL");
                 }
+                for (const pid of liveKuboPids)
+                    killKuboProcessGroup(pid, "SIGKILL");
             });
+            // Persistent signal guard (issue #70): exit-hook registers its SIGINT/SIGTERM handlers
+            // with process.once, so its listener vanishes from the listener list the moment a
+            // signal is dispatched. signal-exit (loaded by @pkcprotocol/proper-lock-file and other
+            // dependencies) re-raises the signal when every remaining listener is its own — which
+            // would kill the process while the async exit hook above is still shutting kubo down.
+            // A persistent non-signal-exit listener keeps that heuristic from ever firing.
+            // A repeated signal force-quits immediately (impatient Ctrl+C): process.exit triggers
+            // the emergency "exit" handler above, which SIGKILLs every live kubo.
+            let terminationSignalCount = 0;
+            for (const signal of ["SIGINT", "SIGTERM"]) {
+                process.on(signal, () => {
+                    terminationSignalCount++;
+                    if (terminationSignalCount >= 2) {
+                        log(`Received ${signal} again during shutdown, force-quitting`);
+                        process.exit(signal === "SIGINT" ? 130 : 143);
+                    }
+                });
+            }
+            // Test hook (issue #70): simulates a dependency registering a signal-exit handler
+            // AFTER the asyncExitHook above — what @pkcprotocol/proper-lock-file (and the
+            // signal-exit copies under ink/restore-cursor) do at module load. signal-exit
+            // re-raises the signal when every remaining listener belongs to the signal-exit
+            // family (`if (listeners.length === count) { ... process.kill(process.pid, s) }`),
+            // which kills the daemon while the async exit hook is still cleaning up kubo —
+            // exit-hook registers with process.once, so its listener is already gone by then.
+            if (process.env["PKC_CLI_TEST_SIMULATE_LATE_SIGNAL_EXIT"]) {
+                for (const signal of ["SIGINT", "SIGTERM"]) {
+                    // Real signal-exit copies only count each other as "family" (via a shared
+                    // global marker); any other listener makes them defer. Identify family by
+                    // source: signal-exit's dispatcher carries the "an exit is coming" comment.
+                    const isSignalExitFamily = (listener) => String(listener).includes("an exit is coming");
+                    const reRaiser = () => {
+                        const onlyFamilyLeft = process
+                            .listeners(signal)
+                            .every((listener) => listener === reRaiser || isSignalExitFamily(listener));
+                        if (onlyFamilyLeft) {
+                            process.removeListener(signal, reRaiser);
+                            process.kill(process.pid, signal);
+                        }
+                    };
+                    process.on(signal, reRaiser);
+                }
+            }
+            // RPC port was already verified free above (fail-fast); only the kuboRpcClientsOptions branch skips local kubo.
+            if (!pkcOptionsFromFlag?.kuboRpcClientsOptions)
+                await keepKuboUp();
+            await createOrConnectRpc();
             keepKuboUpInterval = setInterval(async () => {
                 if (mainProcessExited)
                     return;

package/dist/cli/commands/update/install.js

@@ -115,6 +115,7 @@ export default class Install extends Command {
         // Restart daemons with the new binary
         if (aliveDaemons.length > 0 && flags["restart-daemons"]) {
             await this._restartDaemons(aliveDaemons);
+            this.log("To see the daemon logs run `bitsocial logs --stdout`");
         }
     }
     async _restartDaemons(daemons) {

package/dist/common-utils/daemon-state.d.ts

@@ -3,6 +3,8 @@ export interface DaemonState {
     startedAt: string;
     argv: string[];
     pkcRpcUrl: string;
+    /** OS-reported process start time, used to detect PID reuse. Absent in legacy state files. */
+    procStartTime?: string;
 }
 /** Write a daemon state file atomically (write to .tmp then rename). */
 export declare function writeDaemonState(state: DaemonState): Promise<void>;
@@ -10,7 +12,7 @@ export declare function writeDaemonState(state: DaemonState): Promise<void>;
 export declare function readAllDaemonStates(): Promise<DaemonState[]>;
 /** Delete a specific daemon's state file. Ignores ENOENT. */
 export declare function deleteDaemonState(pid: number): Promise<void>;
-/** Delete state files for dead PIDs from disk. */
+/** Delete state files for dead or reused PIDs from disk. */
 export declare function pruneStaleStates(): Promise<void>;
-/** Read all states, delete stale files (dead PIDs) from disk, return only alive ones. */
+/** Read all states, delete stale files (dead or reused PIDs) from disk, return only alive ones. */
 export declare function getAliveDaemonStates(): Promise<DaemonState[]>;