@cjhyy/code-shell-core 0.8.8 → 0.8.10

package/dist/session/session-manager.d.ts

@@ -108,7 +108,7 @@ export declare class SessionManager {
      * Create a session. `qchat-` sessions stay process-local; ordinary sessions
      * materialize state.json + transcript.jsonl before return.
      */
-    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin, kind?: SessionKind): SessionBundle;
+    create(cwd: string, model: string, provider: string, explicitSessionId?: string, parentSessionId?: string | null, origin?: import("../types.js").SessionOrigin, kind?: SessionKind, ephemeral?: boolean): SessionBundle;
     /** Whether a persisted or process-local session exists. */
     exists(sessionId: string): boolean;
     /**
@@ -236,6 +236,8 @@ export declare class SessionManager {
      * workspace/profile metadata.
      */
     readSessionState(sessionId: string): SessionState | undefined;
+    /** Whether a live or persisted Session is explicitly process-local. */
+    isEphemeralSession(sessionId: string): boolean;
     /**
      * Merge a field-level state update into the latest persisted snapshot.
      *
@@ -288,6 +290,7 @@ export declare class SessionManager {
      */
     saveStateOrUpdateFields(state: SessionState, partial: SessionStateFieldPatch): boolean;
     private saveStateAttempt;
+    private writeStateAtomically;
     private acquireStateLock;
     /** Recover only the old implementation's regular-file orphan lock. */
     private prepareLegacyStateLock;

package/dist/session/session-manager.js

@@ -1,7 +1,7 @@
 /**
  * Session lifecycle manager.
  */
-import { closeSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { closeSync, chmodSync, existsSync, mkdirSync, lstatSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -148,26 +148,34 @@ function adoptCompatibilityGoalMutation(state) {
 // disk. The storage root remains part of the key to preserve identity/data-root
 // isolation.
 const processLocalSessionBundles = new Map();
-const FORK_COPY_EVENT_TYPES = new Set([
-    "message",
-    "tool_use",
-    "tool_result",
-    "summary",
-    "context_transfer",
-    "range_archive",
-    "content_replace",
-    "subagent",
-    "external_file_changes",
-    "goal_progress",
-    "turn_boundary",
-    "turn_stopped",
-    "error",
-]);
-const FORK_SKIP_EVENT_TYPES = new Set([
-    "session_meta",
-    "file_history",
-    "plan_operation",
-]);
+/**
+ * Every known transcript event must make an explicit fork decision. The
+ * `satisfies` constraint turns new TranscriptEventType additions into a
+ * compile-time error instead of a quick-chat failure discovered at runtime.
+ * The runtime fallback below still rejects unknown events from newer or
+ * malformed persisted transcripts.
+ */
+const FORK_EVENT_POLICY = {
+    message: "copy",
+    tool_use: "copy",
+    tool_result: "copy",
+    summary: "copy",
+    context_transfer: "copy",
+    range_archive: "copy",
+    content_replace: "copy",
+    file_history: "skip",
+    plan_operation: "skip",
+    session_meta: "skip",
+    subagent: "copy",
+    external_file_changes: "copy",
+    turn_boundary: "copy",
+    // Idempotency receipts belong to the source session and never contribute to
+    // model context. Copying them could replay a source response in the child.
+    run_result: "skip",
+    goal_progress: "copy",
+    turn_stopped: "copy",
+    error: "copy",
+};
 const FORK_STAGING_NAME = /^\.pending-fork-[A-Za-z0-9_.-]+-[A-Za-z0-9_-]{8}$/;
 const FORK_STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const FORK_STAGING_CLEANUP_LIMIT = 32;
@@ -296,7 +304,9 @@ export class SessionManager {
                 resolveCapabilities()
                     .map((capability) => capability.sessionWorkspace)
                     .find((candidate) => candidate !== undefined);
-        mkdirSync(this.sessionsDir, { recursive: true });
+        mkdirSync(this.sessionsDir, { recursive: true, mode: 0o700 });
+        if (process.platform !== "win32")
+            chmodSync(this.sessionsDir, 0o700);
         this.cleanupStaleForkStaging();
     }
     processLocalKey(sessionId) {
@@ -366,7 +376,7 @@ export class SessionManager {
      * Create a session. `qchat-` sessions stay process-local; ordinary sessions
      * materialize state.json + transcript.jsonl before return.
      */
-    create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work") {
+    create(cwd, model, provider, explicitSessionId, parentSessionId, origin, kind = "work", ephemeral = false) {
         // External callers may pass any string; nanoid output is trusted. Either
         // way the ID gets joined into a filesystem path, so the public entry
         // point validates before that join.
@@ -394,7 +404,7 @@ export class SessionManager {
             // new top-level session (key present, null) apart from a legacy session
             // (key absent) and from a sub-agent (key present, non-empty string).
             parentSessionId: parentSessionId ?? null,
-            ...(sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
+            ...(ephemeral || sessionId.startsWith("qchat-") ? { ephemeral: true } : {}),
             ...(origin ? { origin } : {}),
         };
         if (isEphemeralSessionState(state)) {
@@ -410,13 +420,16 @@ export class SessionManager {
                 startedAt: state.startedAt,
                 kind,
             });
+            if (transcript.flushFailed()) {
+                throw new SessionError(`Failed to persist initial transcript for ${sessionId}`);
+            }
             const bundle = { state, transcript };
             this.storeProcessLocalBundle(bundle);
             return bundle;
         }
         const sessionDir = join(this.sessionsDir, sessionId);
         try {
-            mkdirSync(sessionDir);
+            mkdirSync(sessionDir, { mode: 0o700 });
         }
         catch (err) {
             if (err.code === "EEXIST") {
@@ -426,20 +439,26 @@ export class SessionManager {
         }
         // Atomic write (tmp+rename) like saveState, so a crash during this one-time
         // create can't leave a torn state.json that resume() then fails to parse.
-        const stateTarget = join(sessionDir, "state.json");
-        const stateTmp = `${stateTarget}.${process.pid}.${Date.now()}.create.tmp`;
-        writeFileSync(stateTmp, JSON.stringify(state, null, 2), "utf-8");
-        renameSync(stateTmp, stateTarget);
-        const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
-        transcript.append("session_meta", {
-            sessionId,
-            cwd,
-            model,
-            provider,
-            startedAt: state.startedAt,
-            kind,
-        });
-        return { state, transcript };
+        try {
+            const stateTarget = join(sessionDir, "state.json");
+            this.writeStateAtomically(stateTarget, state, "create");
+            const transcript = new Transcript(join(sessionDir, "transcript.jsonl"));
+            transcript.append("session_meta", {
+                sessionId,
+                cwd,
+                model,
+                provider,
+                startedAt: state.startedAt,
+                kind,
+            });
+            return { state, transcript };
+        }
+        catch (error) {
+            // A failed first materialization must not reserve the session id forever
+            // with an empty/partial directory.
+            rmSync(sessionDir, { recursive: true, force: true });
+            throw error;
+        }
     }
     /** Whether a persisted or process-local session exists. */
     exists(sessionId) {
@@ -1017,6 +1036,10 @@ export class SessionManager {
             throw new SessionError(`Session state is corrupt for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
         }
         const transcriptFile = join(sessionDir, "transcript.jsonl");
+        if (process.platform !== "win32") {
+            chmodSync(sessionDir, 0o700);
+            chmodSync(stateFile, 0o600);
+        }
         const transcript = Transcript.loadFromFile(transcriptFile);
         state.kind = normalizedSessionKind(state.kind);
         state.status = "active";
@@ -1049,6 +1072,10 @@ export class SessionManager {
             return undefined;
         }
     }
+    /** Whether a live or persisted Session is explicitly process-local. */
+    isEphemeralSession(sessionId) {
+        return this.readSessionState(sessionId)?.ephemeral === true;
+    }
     /**
      * Merge a field-level state update into the latest persisted snapshot.
      *
@@ -1357,9 +1384,7 @@ export class SessionManager {
                 state.title = persisted.title;
             }
             state.stateRevision = (persistedRevision ?? incomingRevision ?? 0) + 1;
-            const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-            writeFileSync(tmp, JSON.stringify(stateForPersistence(state), null, 2), "utf-8");
-            renameSync(tmp, target);
+            this.writeStateAtomically(target, stateForPersistence(state));
             return { ok: true };
         }
         finally {
@@ -1371,6 +1396,24 @@ export class SessionManager {
             }
         }
     }
+    writeStateAtomically(target, state, label = "state") {
+        const tmp = `${target}.${process.pid}.${nanoid(8)}.${label}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(state, null, 2), {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
+            renameSync(tmp, target);
+        }
+        finally {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                // Preserve the original write/rename error; cleanup is best effort.
+            }
+        }
+    }
     acquireStateLock(target) {
         const lockPath = `${target}.lock`;
         for (let attempt = 0; attempt <= SESSION_STATE_LOCK_RETRY_DELAYS_MS.length; attempt++) {
@@ -1569,7 +1612,10 @@ export class SessionManager {
         return this.freezeForkSnapshot(sourceSessionId, sourceState, parsed.events, throughEventId, snapshotMode);
     }
     freezeForkSnapshot(sourceSessionId, sourceState, events, throughEventId, snapshotMode) {
-        const sourceEvents = structuredClone([...events]);
+        // Both process-local and disk readers provide a snapshot array. Fork
+        // selection is synchronous, so keep event references here and clone once
+        // when the independently-owned target transcript is constructed below.
+        const sourceEvents = [...events];
         let frozen = sourceEvents;
         const effectiveCursor = snapshotMode === "completed" ? sourceState.completedThroughEventId : throughEventId;
         if (snapshotMode === "completed" && effectiveCursor === undefined) {
@@ -1600,12 +1646,13 @@ export class SessionManager {
         }
         const copiedEvents = [];
         for (const event of frozen) {
-            if (FORK_SKIP_EVENT_TYPES.has(event.type))
+            const policy = FORK_EVENT_POLICY[event.type];
+            if (policy === "skip")
                 continue;
-            if (!FORK_COPY_EVENT_TYPES.has(event.type)) {
+            if (policy !== "copy") {
                 throw new SessionError(`Unsupported transcript event in fork: ${String(event.type)}`);
             }
-            copiedEvents.push(structuredClone(event));
+            copiedEvents.push(event);
         }
         validateForkToolPairs(copiedEvents);
         return { sourceState: structuredClone(sourceState), copiedEvents };
@@ -1628,7 +1675,7 @@ export class SessionManager {
         const stagingDir = join(this.sessionsDir, `.pending-fork-${targetSessionId}-${nanoid(8)}`);
         let published = false;
         try {
-            mkdirSync(stagingDir);
+            mkdirSync(stagingDir, { mode: 0o700 });
             writeFileSync(join(stagingDir, "state.json"), JSON.stringify(state, null, 2), {
                 encoding: "utf-8",
                 mode: 0o600,

package/dist/session/transcript.js

@@ -2,10 +2,36 @@
  * Transcript — JSONL event log (NOT chat history).
  * toMessages() derives Message[] from events for sending to LLM.
  */
-import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { nanoid } from "nanoid";
 import { logger } from "../logging/logger.js";
+function appendTranscriptLine(filePath, data) {
+    // Use one append-mode descriptor so concurrent OS writers cannot overwrite
+    // one another. Also repair the record boundary after a crash-torn final line;
+    // otherwise the next valid event is concatenated to the fragment and both
+    // are discarded on replay.
+    const fd = openSync(filePath, "a+", 0o600);
+    try {
+        if (process.platform !== "win32")
+            fchmodSync(fd, 0o600);
+        const size = fstatSync(fd).size;
+        let prefix = "";
+        if (size > 0) {
+            const lastByte = Buffer.allocUnsafe(1);
+            readSync(fd, lastByte, 0, 1, size - 1);
+            if (lastByte[0] !== 0x0a)
+                prefix = "\n";
+        }
+        appendFileSync(fd, prefix + data, "utf-8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const defaultTranscriptWriter = (filePath, data) => {
+    appendTranscriptLine(filePath, data);
+};
 const CONTEXT_EVENT_TYPES = new Set([
     "message",
     "tool_use",
@@ -68,7 +94,7 @@ export class Transcript {
     getFilePath() {
         return this.filePath;
     }
-    constructor(filePath, writer = appendFileSync, options = {}) {
+    constructor(filePath, writer = defaultTranscriptWriter, options = {}) {
         this.filePath = filePath;
         this.writer = writer;
         this.persistent = options.persistent !== false;
@@ -76,7 +102,11 @@ export class Transcript {
             return;
         mkdirSync(dirname(filePath), { recursive: true });
         if (!existsSync(filePath)) {
-            writeFileSync(filePath, "", "utf-8");
+            writeFileSync(filePath, "", { encoding: "utf-8", mode: 0o600 });
+        }
+        else if (process.platform !== "win32") {
+            // Tighten transcripts created by older releases on first use.
+            chmodSync(filePath, 0o600);
         }
     }
     /** A process-local transcript that never creates or appends a file. */

package/dist/session/undo-target.d.ts

@@ -55,12 +55,21 @@ export declare function latestTurnUndoTargets(snapshots: FileSnapshot[]): FileSn
  * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
  * undone state (i.e. nothing newer happened since the undo). Otherwise [].
  *
- * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
- * exists only for a turn that was undone and not yet redone). R is redoable iff
- * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
- * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
- * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
- * is the sole evidence and is honoured as long as nothing newer superseded it.
+ * Rule: let R = the LOWEST turnSeq present in `redoRecords` (a RedoRecord exists
+ * only for a turn that was undone and not yet redone). Undo walks BACKWARD down
+ * the turn stack, so after `undo(2); undo(1)` both records are pending and the
+ * one to re-apply first is turn 1 — the most recently undone, i.e. the lowest.
+ * Selecting the greatest instead replayed turns out of order: `redo` jumped
+ * straight to turn 2, skipping turn 1's state entirely and stranding turn 1's
+ * record forever (its snapshots stay `undone`, so it never becomes selectable).
+ * With two files that also produced a state that never existed — turn 1 still
+ * reverted while turn 2 was applied.
+ *
+ * R is redoable iff NO snapshot belongs to a strictly newer LIVE (non-undone)
+ * turn — a fresh edit after the undo supersedes the redo and invalidates it
+ * (spec: "新轮使 redo 失效"). Created-only turns have no pre-turn snapshot, so
+ * the RedoRecord itself is the sole evidence and is honoured as long as nothing
+ * newer superseded it.
  *
  * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
  */

package/dist/session/undo-target.js

@@ -114,25 +114,42 @@ export function latestTurnUndoTargets(snapshots) {
  * `redoLatestTurn` should re-apply — but ONLY when that turn is still the latest
  * undone state (i.e. nothing newer happened since the undo). Otherwise [].
  *
- * Rule: let R = the greatest turnSeq present in `redoRecords` (a RedoRecord
- * exists only for a turn that was undone and not yet redone). R is redoable iff
- * NO snapshot belongs to a strictly newer LIVE (non-undone) turn — a fresh edit
- * after the undo supersedes the redo and invalidates it (spec: "新轮使 redo
- * 失效"). Created-only turns have no pre-turn snapshot, so the RedoRecord itself
- * is the sole evidence and is honoured as long as nothing newer superseded it.
+ * Rule: let R = the LOWEST turnSeq present in `redoRecords` (a RedoRecord exists
+ * only for a turn that was undone and not yet redone). Undo walks BACKWARD down
+ * the turn stack, so after `undo(2); undo(1)` both records are pending and the
+ * one to re-apply first is turn 1 — the most recently undone, i.e. the lowest.
+ * Selecting the greatest instead replayed turns out of order: `redo` jumped
+ * straight to turn 2, skipping turn 1's state entirely and stranding turn 1's
+ * record forever (its snapshots stay `undone`, so it never becomes selectable).
+ * With two files that also produced a state that never existed — turn 1 still
+ * reverted while turn 2 was applied.
+ *
+ * R is redoable iff NO snapshot belongs to a strictly newer LIVE (non-undone)
+ * turn — a fresh edit after the undo supersedes the redo and invalidates it
+ * (spec: "新轮使 redo 失效"). Created-only turns have no pre-turn snapshot, so
+ * the RedoRecord itself is the sole evidence and is honoured as long as nothing
+ * newer superseded it.
  *
  * Empty `redoRecords` → []. fs-free so /redo's target decision is unit-testable.
  */
 export function latestRedoTargets(redoRecords, snapshots) {
     if (redoRecords.length === 0)
         return [];
+    // The most recently undone turn is the LOWEST pending one (undo pops the
+    // stack from the top down), and it is the next one to re-apply.
+    let nextRedoTurn = Infinity;
+    for (const r of redoRecords) {
+        if (r.turnSeq < nextRedoTurn)
+            nextRedoTurn = r.turnSeq;
+    }
+    // Supersession is still judged against the NEWEST pending redo turn: a live
+    // snapshot newer than that is a fresh edit made after the undo, which
+    // invalidates the whole pending redo chain rather than just one turn.
     let maxRedoTurn = -Infinity;
     for (const r of redoRecords) {
         if (r.turnSeq > maxRedoTurn)
             maxRedoTurn = r.turnSeq;
     }
-    // If any LIVE snapshot belongs to a strictly newer turn, the redo turn is no
-    // longer the latest undone state → not redoable.
     for (const s of snapshots) {
         if (s.undone)
             continue;
@@ -140,5 +157,5 @@ export function latestRedoTargets(redoRecords, snapshots) {
         if (k > maxRedoTurn)
             return [];
     }
-    return redoRecords.filter((r) => r.turnSeq === maxRedoTurn);
+    return redoRecords.filter((r) => r.turnSeq === nextRedoTurn);
 }

package/dist/settings/manager.d.ts

@@ -145,24 +145,43 @@ export declare class SettingsManager {
      * cache invalidation mirror saveUserSetting.
      */
     saveProjectSetting(key: string, value: unknown, cwd: string): void;
+    /**
+     * Persist a machine-private setting for one project. The local layer has
+     * higher precedence than the shared project layer and lives at
+     * `${cwd}/.code-shell/settings.local.json`, matching the file already read
+     * by {@link load}. It is useful for MCP endpoints or policy that should not
+     * be shared with collaborators.
+     */
+    saveLocalSetting(key: string, value: unknown, cwd: string): void;
     /**
      * Delete a single dotted key from the PROJECT-level config file. Used to
      * express "inherit" — we don't persist the literal "inherit"; we remove the
      * override key. No-ops if the file or any intermediate segment is absent.
      */
     deleteProjectSetting(key: string, cwd: string): void;
+    /** Delete one dotted key from the machine-private project settings layer. */
+    deleteLocalSetting(key: string, cwd: string): void;
+    /** Delete one dotted key from the user settings layer. */
+    deleteUserSetting(key: string): void;
+    private deleteSettingFromFile;
     /**
      * Read ONE scope's raw settings file, validated but UNMERGED. Capability
      * overlay math needs the project overlay and the user/global baseline
      * separately — the merged get() collapses provenance and can't express
      * tri-state inheritance. user → ~/.code-shell/settings.json, project →
-     * ${cwd}/.code-shell/settings.json. Only keys actually present in the file
-     * are returned (defaults are not synthesized), so an absent file → {}.
+     * ${cwd}/.code-shell/settings.json, local →
+     * ${cwd}/.code-shell/settings.local.json. Only keys actually present in the
+     * file are returned (defaults are not synthesized), so an absent file → {}.
      */
-    getForScope(scope: "user" | "project", cwd?: string): Partial<ValidatedSettings>;
+    getForScope(scope: "user" | "project" | "local", cwd?: string): Partial<ValidatedSettings>;
     private projectSettingsPath;
+    private localSettingsPath;
+    private validateProjectCwd;
+    /** Resolve the project root once and refuse a linked/non-directory state root. */
+    private tryProjectSettingsPath;
     private readJsonObject;
     private atomicWriteJson;
+    private writeBackup;
     /**
      * Read-modify-write a settings file under a cross-process lock.
      *