@cjhyy/code-shell-server 0.9.22 → 0.9.25

package/dist/serve/settings-recovery-cli.js

@@ -0,0 +1,128 @@
+import { parseArgs } from "node:util";
+const HELP = `Usage: code-shell-settings-recovery <inspect|repair|restore> [options]
+
+Offline administrator recovery for a stopped project's settings.
+Stop the project and all its workers before repair or restore.
+This command does not start a server, authenticate remote users or stop workers.
+
+Options:
+  --project <directory>        Actual project directory (default: current directory)
+  --scope <project|local>      Configuration layer (default: project)
+  --from <file>                Complete reviewed JSON candidate (inspect or repair)
+  --expected-revision <sha256> Revision returned by inspect (repair or restore)
+  --candidate-sha256 <sha256>  Candidate hash returned by inspect (repair)
+  --backup-id <id>             Backup returned by repair/restore (restore)
+  -h, --help                   Show this help without reading configuration
+
+Inspection reports metadata and hashes, never configuration values.
+Repair preserves original bytes before replacement. Restore also backs up current
+bytes; restoring a damaged original restores that fault too. Keep backups private.
+`;
+export function parseSettingsRecoveryArgs(argv, cwd) {
+    const invalid = () => new Error("Invalid recovery arguments; use --help for usage.");
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            tokens: true,
+            options: {
+                project: { type: "string" },
+                scope: { type: "string" },
+                from: { type: "string" },
+                "expected-revision": { type: "string" },
+                "candidate-sha256": { type: "string" },
+                "backup-id": { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch {
+        // Parser errors can reflect unrecognized argument values. Do not echo them.
+        throw invalid();
+    }
+    const { values, positionals, tokens } = parsed;
+    const names = new Set();
+    for (const token of tokens ?? []) {
+        if (token.kind !== "option")
+            continue;
+        if (names.has(token.name))
+            throw invalid();
+        names.add(token.name);
+    }
+    const action = positionals[0];
+    if (positionals.length > 1 || (action && !["inspect", "repair", "restore"].includes(action)))
+        throw invalid();
+    if (values.help)
+        return { action: "help" };
+    if (!action)
+        throw invalid();
+    const allowed = new Set(["project", "scope"]);
+    if (action === "inspect" || action === "repair")
+        allowed.add("from");
+    if (action !== "inspect")
+        allowed.add("expected-revision");
+    if (action === "repair")
+        allowed.add("candidate-sha256");
+    if (action === "restore")
+        allowed.add("backup-id");
+    for (const name of names)
+        if (!allowed.has(name))
+            throw invalid();
+    const value = (name, required = false) => {
+        const result = values[name];
+        if (result === undefined && !required)
+            return undefined;
+        if (typeof result !== "string" || !result.trim())
+            throw invalid();
+        return result;
+    };
+    const scope = value("scope") ?? "project";
+    if (scope !== "project" && scope !== "local")
+        throw invalid();
+    const target = { cwd: value("project") ?? cwd(), scope };
+    if (action === "inspect")
+        return { action, ...target, candidatePath: value("from") };
+    const expectedRevision = value("expected-revision", true);
+    if (!/^[a-f0-9]{64}$/.test(expectedRevision))
+        throw invalid();
+    if (action === "repair") {
+        const candidateSha256 = value("candidate-sha256", true);
+        if (!/^[a-f0-9]{64}$/.test(candidateSha256))
+            throw invalid();
+        return {
+            action,
+            ...target,
+            candidatePath: value("from", true),
+            expectedRevision,
+            candidateSha256,
+        };
+    }
+    return { action: "restore", ...target, backupId: value("backup-id", true), expectedRevision };
+}
+export async function runSettingsRecoveryCli(argv = process.argv.slice(2), io = {}) {
+    const write = io.write ?? ((text) => process.stdout.write(text));
+    const error = io.error ?? ((text) => process.stderr.write(text));
+    try {
+        const args = parseSettingsRecoveryArgs(argv, io.cwd ?? (() => process.cwd()));
+        if (args.action === "help") {
+            write(HELP);
+            return 0;
+        }
+        // Load only the reviewed Host recovery operations, after argument validation.
+        // In particular, do not start serve/bootstrap or require TUI/model setup.
+        const core = await import("@cjhyy/code-shell-core/internal");
+        const result = args.action === "inspect"
+            ? core.inspectProjectSettingsRecovery(args)
+            : args.action === "repair"
+                ? core.repairProjectSettings(args)
+                : core.restoreProjectSettings(args);
+        write(JSON.stringify(result, null, 2) + "\n");
+        return 0;
+    }
+    catch (cause) {
+        error(`[settings-recovery] ${cause instanceof Error ? cause.message : "Recovery failed"}\n`);
+        return 1;
+    }
+}

package/dist/session-http-responses.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from "node:http";
+/** Response lifetimes are session-owned; accepted background work is not. */
+export declare function createSessionHttpResponses(): {
+    track(sessionId: string, response: ServerResponse): void;
+    cancelOwner: (sessionId: string) => void;
+    clear(): void;
+};

package/dist/session-http-responses.js

@@ -0,0 +1,40 @@
+/** Response lifetimes are session-owned; accepted background work is not. */
+export function createSessionHttpResponses() {
+    const owners = new Map();
+    function cancelOwner(sessionId) {
+        const responses = owners.get(sessionId);
+        if (!responses)
+            return;
+        for (const [response, release] of responses) {
+            release();
+            response.destroy();
+        }
+    }
+    return {
+        track(sessionId, response) {
+            if (response.destroyed || response.writableFinished)
+                return;
+            let responses = owners.get(sessionId);
+            if (!responses)
+                owners.set(sessionId, (responses = new Map()));
+            const owned = responses;
+            const release = () => {
+                response.off("finish", release);
+                response.off("close", release);
+                owned.delete(response);
+                if (owned.size === 0)
+                    owners.delete(sessionId);
+            };
+            owned.set(response, release);
+            // A handler may return before its stream finishes. Follow the actual
+            // response, so revocation still aborts the upstream pipeline and its files.
+            response.once("finish", release);
+            response.once("close", release);
+        },
+        cancelOwner,
+        clear() {
+            for (const sessionId of owners.keys())
+                cancelOwner(sessionId);
+        },
+    };
+}

package/dist/sessions-service.d.ts

@@ -39,9 +39,11 @@ export interface DiskSessionMeta {
     cwd: string;
     title: string;
     updatedAt: number;
-    /** Sub-agents are returned only by an explicit parentSessionId query. */
+    /** Durable creation time, when supplied by the engine's state schema. */
+    createdAt?: number;
+    /** Sub-agents require an explicit parent query or the host's includeSubagents scan. */
     origin: "desktop" | "automation" | "subagent";
-    /** Present only when listing the direct children of a session. */
+    /** Present for direct-child queries and the host's complete task scan. */
     parentSessionId?: string;
     /** Normalized durable status for Pet/display consumers. */
     status?: "active" | "paused" | "completed" | "failed" | "cancelled";
@@ -68,6 +70,8 @@ export declare function listDiskSessions(opts: {
     limit: number;
     cursor?: string;
     includeArchived?: boolean;
+    /** Host read models may include children; ordinary sidebar queries stay top-level. */
+    includeSubagents?: boolean;
     parentSessionId?: string;
 }, baseDir?: string): Promise<ListDiskSessionsResult>;
 /**

package/dist/sessions-service.js

@@ -279,7 +279,7 @@ export async function listDiskSessions(opts, baseDir = sessionsRoot()) {
             if (state.parentSessionId !== parentSessionId)
                 continue;
         }
-        else if (state.parentSessionId) {
+        else if (state.parentSessionId && !opts.includeSubagents) {
             continue;
         }
         // Only desktop + automation belong in the desktop sidebar. Targeted
@@ -288,7 +288,7 @@ export async function listDiskSessions(opts, baseDir = sessionsRoot()) {
         const origin = state.origin;
         if (origin !== "desktop" &&
             origin !== "automation" &&
-            !(parentSessionId !== undefined && origin === "subagent")) {
+            !((parentSessionId !== undefined || opts.includeSubagents) && origin === "subagent")) {
             continue;
         }
         // Skip sessions whose project root has been deleted. Listing them led the
@@ -300,7 +300,21 @@ export async function listDiskSessions(opts, baseDir = sessionsRoot()) {
         const cwdStr = typeof state.cwd === "string" ? state.cwd : "";
         // A child transcript remains useful after its temporary worktree is gone;
         // targeted reads do not rebuild projects in the sidebar.
-        if (parentSessionId === undefined && cwdStr && !(await pathExists(cwdStr)))
+        const childParentId = typeof state.parentSessionId === "string" && state.parentSessionId
+            ? state.parentSessionId
+            : undefined;
+        if (childParentId &&
+            (!SAFE_ID.test(childParentId) ||
+                childParentId.length > 128 ||
+                childParentId.includes("..") ||
+                childParentId === "."))
+            continue;
+        if (state.parentSessionId && !childParentId)
+            continue;
+        if (parentSessionId === undefined &&
+            !(opts.includeSubagents && childParentId) &&
+            cwdStr &&
+            !(await pathExists(cwdStr)))
             continue;
         // Archived sessions are hidden from the default catalog. Filtering happens
         // before the push (like every other skip above), so the mtime cursor —
@@ -328,8 +342,13 @@ export async function listDiskSessions(opts, baseDir = sessionsRoot()) {
             title: (typeof state.title === "string" && state.title ? state.title : undefined) ??
                 (typeof state.summary === "string" && state.summary ? state.summary : id),
             updatedAt: mtime,
+            ...(typeof state.startedAt === "number" &&
+                Number.isFinite(state.startedAt) &&
+                state.startedAt >= 0
+                ? { createdAt: state.startedAt }
+                : {}),
             origin,
-            ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+            ...(childParentId ? { parentSessionId: childParentId } : {}),
             status: state.status === "active" || state.status === "paused" || state.status === "completed"
                 ? state.status
                 : state.status === "aborted_streaming" || state.status === "aborted_tools"

package/dist/worker-bridge-core.d.ts

@@ -159,6 +159,11 @@ export declare class WorkerBridgeCore {
      * to map onto its own semantics.
      */
     request(method: string, params: unknown, options: WorkerRequestOptions): Promise<WorkerRpcOutcome>;
+    /** Request shutdown and retain ownership until this exact child exits.
+     * Does not resolve merely because SIGTERM was sent; an uncooperative child
+     * remains owned so a caller cannot start competing work prematurely.
+     */
+    stopAndWait(): Promise<void>;
     /** Graceful shutdown: SIGTERM the worker (no-op when none is alive). */
     kill(): void;
 }

package/dist/worker-bridge-core.js

@@ -365,6 +365,29 @@ export class WorkerBridgeCore {
             }
         });
     }
+    /** Request shutdown and retain ownership until this exact child exits.
+     * Does not resolve merely because SIGTERM was sent; an uncooperative child
+     * remains owned so a caller cannot start competing work prematurely.
+     */
+    async stopAndWait() {
+        const child = this.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return;
+        await new Promise((resolve) => {
+            const done = () => {
+                child.off("exit", done);
+                child.off("error", spawnFailed);
+                resolve();
+            };
+            const spawnFailed = () => {
+                if (!child.pid)
+                    done();
+            };
+            child.once("exit", done);
+            child.on("error", spawnFailed);
+            child.kill("SIGTERM");
+        });
+    }
     /** Graceful shutdown: SIGTERM the worker (no-op when none is alive). */
     kill() {
         this.log("kill", { pid: this.child?.pid });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-server",
-  "version": "0.9.22",
+  "version": "0.9.25",
   "description": "CodeShell server transport layer — mobile remote HTTP/WS host, pairing, passcode gate, tunnel, rooms, uploads, and session/attachment services. Electron-free; precursor of the auth gateway.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,14 @@
       "types": "./dist/index.worker.d.ts",
       "import": "./dist/index.worker.js"
     },
+    "./remote-relay": {
+      "types": "./dist/index.remote-relay.d.ts",
+      "import": "./dist/index.remote-relay.js"
+    },
+    "./auth": {
+      "types": "./dist/index.auth.d.ts",
+      "import": "./dist/index.auth.js"
+    },
     "./mobile-remote": {
       "types": "./dist/index.mobile-remote.d.ts",
       "import": "./dist/index.mobile-remote.js"
@@ -40,7 +48,8 @@
     }
   },
   "bin": {
-    "code-shell-serve": "./dist/bin/code-shell-serve.js"
+    "code-shell-serve": "./dist/bin/code-shell-serve.js",
+    "code-shell-settings-recovery": "./dist/bin/code-shell-settings-recovery.js"
   },
   "files": [
     "dist"
@@ -51,13 +60,13 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-capability-coding": "0.9.22",
-    "@cjhyy/code-shell-core": "0.9.22",
-    "@cjhyy/code-shell-web": "0.9.22",
+    "@cjhyy/code-shell-capability-coding": "0.9.25",
+    "@cjhyy/code-shell-core": "0.9.25",
+    "@cjhyy/code-shell-web": "0.9.25",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@types/ws": "^8.18.1",
     "ws": "^8.21.0",
-    "@cjhyy/code-shell-link": "0.9.22"
+    "@cjhyy/code-shell-link": "0.9.25"
   },
   "engines": {
     "node": ">=20.10"