@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/tool-system/sandbox/index.js

@@ -17,7 +17,7 @@
  * when no sandbox is available.
  */
 import { accessSync, constants, realpathSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { SandboxUnavailableError } from "../../exceptions.js";
 /**
  * Detect which sandbox mechanisms are available on the current host. Used by
@@ -111,9 +111,14 @@ function warnAutoDowngrade() {
         `Set sandbox.mode=off in settings.json to silence, or CODE_SHELL_SANDBOX_QUIET=1.\n`);
 }
 export function defaultSandboxConfig(mode = "auto") {
+    // Temp roots are writable so tool-result spillover / scratch files land
+    // somewhere. POSIX: the canonical /tmp family. Windows has no OS sandbox
+    // backend (auto → off), so writableRoots is effectively unused there, but
+    // keep it host-correct by using the platform temp dir instead of /tmp.
+    const tmpRoots = process.platform === "win32" ? [tmpdir()] : ["/tmp", "/private/tmp", "/var/tmp"];
     return {
         mode,
-        writableRoots: ["${workspace}", "/tmp", "/private/tmp", "/var/tmp"],
+        writableRoots: ["${workspace}", ...tmpRoots],
         deniedReads: [
             "~/.ssh",
             "~/.aws",

package/dist/tool-system/sandbox/off.js

@@ -1,8 +1,14 @@
+import { resolveShellInvocation } from "../../runtime/spawn-common.js";
 export function createOffBackend() {
     return {
         name: "off",
         wrap(command, opts) {
-            return { file: opts.shell, args: ["-c", command] };
+            // "off" = no sandboxing; just run the command through the shell. Delegate
+            // to resolveShellInvocation for the PLATFORM-CORRECT flag instead of a
+            // hardcoded POSIX `-c`: on Windows cmd.exe needs `/c` (a bare `-c` is taken
+            // as a filename and cmd hangs in interactive mode until timeout — the
+            // "Bash never runs on Windows" beta regression). POSIX still gets `-c`.
+            return resolveShellInvocation(command, opts.shell);
         },
     };
 }

package/dist/tool-system/validate-tool-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Registration-time guard for tool path-policy metadata.
+ *
+ * A tool's `pathPolicy[].arg` names the input field that carries a file path
+ * (or, for apply_patch, the patch text). ToolExecutor reads `args[policy.arg]`
+ * to find the targets it must run through the path-permission layer. If that
+ * arg name is a typo (e.g. `"pat"` instead of `"path"`), the lookup yields
+ * `undefined`, the executor finds zero targets, and the tool runs with NO path
+ * protection and no error — a silent security failure (assessment §4.1).
+ *
+ * This validator catches that drift at registration time by asserting every
+ * declared `pathPolicy.arg` exists in the tool's `inputSchema.properties`.
+ */
+import type { RegisteredTool, ToolDefinition } from "../types.js";
+/** A tool-shaped object carrying the fields this validator inspects. */
+type ToolLike = Pick<RegisteredTool, "name" | "inputSchema"> & Partial<Pick<RegisteredTool, "pathPolicy">>;
+export interface ToolMetadataIssue {
+    tool: string;
+    arg: string;
+    reason: string;
+}
+/**
+ * Check a single tool's path-policy metadata against its schema. Returns one
+ * issue per `pathPolicy.arg` that is not a declared input property. Tools
+ * without a pathPolicy produce no issues.
+ */
+export declare function findToolMetadataIssues(tool: ToolLike): ToolMetadataIssue[];
+/**
+ * Assert a tool's path-policy metadata is consistent with its schema. Throws on
+ * the first drift. Call at registration time so a typo fails loud instead of
+ * silently disabling path protection.
+ */
+export declare function validateToolMetadata(tool: ToolLike): void;
+/** Validate a batch; returns every issue across all tools (does not throw). */
+export declare function collectToolMetadataIssues(tools: ReadonlyArray<ToolLike | ToolDefinition>): ToolMetadataIssue[];
+export {};

package/dist/tool-system/validate-tool-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * Registration-time guard for tool path-policy metadata.
+ *
+ * A tool's `pathPolicy[].arg` names the input field that carries a file path
+ * (or, for apply_patch, the patch text). ToolExecutor reads `args[policy.arg]`
+ * to find the targets it must run through the path-permission layer. If that
+ * arg name is a typo (e.g. `"pat"` instead of `"path"`), the lookup yields
+ * `undefined`, the executor finds zero targets, and the tool runs with NO path
+ * protection and no error — a silent security failure (assessment §4.1).
+ *
+ * This validator catches that drift at registration time by asserting every
+ * declared `pathPolicy.arg` exists in the tool's `inputSchema.properties`.
+ */
+/**
+ * Return the set of property names declared in a JSON-schema-ish object's
+ * `properties`. Tolerant of missing/malformed schema (returns empty set), so a
+ * tool with no declared properties is treated as "declares nothing" rather
+ * than throwing — the caller decides how to react.
+ */
+function schemaPropertyNames(inputSchema) {
+    const props = inputSchema?.properties;
+    if (!props || typeof props !== "object")
+        return new Set();
+    return new Set(Object.keys(props));
+}
+/**
+ * Check a single tool's path-policy metadata against its schema. Returns one
+ * issue per `pathPolicy.arg` that is not a declared input property. Tools
+ * without a pathPolicy produce no issues.
+ */
+export function findToolMetadataIssues(tool) {
+    const policies = tool.pathPolicy;
+    if (!policies || policies.length === 0)
+        return [];
+    const declared = schemaPropertyNames(tool.inputSchema);
+    const issues = [];
+    for (const policy of policies) {
+        if (!declared.has(policy.arg)) {
+            issues.push({
+                tool: tool.name,
+                arg: policy.arg,
+                reason: `pathPolicy.arg "${policy.arg}" is not a property of inputSchema (path-permission enforcement would silently no-op)`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Assert a tool's path-policy metadata is consistent with its schema. Throws on
+ * the first drift. Call at registration time so a typo fails loud instead of
+ * silently disabling path protection.
+ */
+export function validateToolMetadata(tool) {
+    const issues = findToolMetadataIssues(tool);
+    if (issues.length > 0) {
+        const first = issues[0];
+        throw new Error(`Invalid tool metadata for "${first.tool}": ${first.reason}`);
+    }
+}
+/** Validate a batch; returns every issue across all tools (does not throw). */
+export function collectToolMetadataIssues(tools) {
+    return tools.flatMap((t) => findToolMetadataIssues(t));
+}

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Core type definitions for the code-shell orchestration framework.
  */
+import type { GoalConfig } from "./engine/goal.js";
 export interface ContentBlock {
     type: "text" | "tool_use" | "tool_result" | "image" | "reasoning";
     text?: string;
@@ -52,8 +53,44 @@ export interface ToolResult {
     contentBlocks?: ContentBlock[];
     error?: string;
     isError?: boolean;
+    /**
+     * Set by tools that execute under the sandbox (Bash / background shell /
+     * worktree) so the UI can show whether THIS call was isolated. `backend`
+     * "off" means the command ran un-sandboxed (we surface it explicitly so the
+     * user sees "未隔离" rather than guessing from an absent badge); "seatbelt"
+     * / "bwrap" mean OS-level isolation applied. `network` is the policy that
+     * was in force (absent when off). Tools that don't touch the sandbox leave
+     * this undefined and the UI renders no badge.
+     */
+    sandbox?: {
+        backend: "off" | "seatbelt" | "bwrap";
+        network?: "allow" | "deny";
+    };
 }
 export type ToolSource = "builtin" | "mcp";
+export type ToolPathPolicyOperation = "read" | "write" | {
+    /** Argument whose value decides whether this invocation reads or writes. */
+    fromArg: string;
+    /** Values that classify the operation as a read. */
+    readValues?: string[];
+    /** Values that classify the operation as a write. */
+    writeValues?: string[];
+    /** Fallback when the argument is absent or does not match either list. */
+    default: "read" | "write";
+};
+export type ToolPathPolicy = {
+    kind: "arg";
+    /** Argument containing a file or directory path. */
+    arg: string;
+    operation: ToolPathPolicyOperation;
+    /** Use ctx.cwd when the argument is omitted. Useful for Glob/Grep roots. */
+    defaultToCwd?: boolean;
+} | {
+    kind: "apply_patch";
+    /** Argument containing the V4A patch text. */
+    arg: string;
+    operation: "write";
+};
 export interface RegisteredTool {
     name: string;
     description: string;
@@ -63,6 +100,18 @@ export interface RegisteredTool {
     permissionDefault: PermissionDecision;
     isConcurrencySafe?: boolean;
     isReadOnly?: boolean;
+    /**
+     * Declarative file-path safety metadata. ToolExecutor enforces this before
+     * dispatching the tool, so file access cannot depend on each tool handler
+     * remembering to call path-policy manually.
+     */
+    pathPolicy?: ToolPathPolicy[];
+    /**
+     * Explicitly marks a path-looking tool as intentionally outside the file
+     * policy layer. Used by tests/audits so new file tools fail closed unless
+     * they either declare pathPolicy or document an exemption.
+     */
+    pathPolicyExempt?: boolean;
     /**
      * Override the default tool execution timeout (ms).
      * Falls back to DEFAULT_TOOL_TIMEOUT_MS (120s) if unset.
@@ -70,7 +119,7 @@ export interface RegisteredTool {
      */
     timeoutMs?: number;
 }
-export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "turn_boundary" | "goal_progress" | "error";
+export type TranscriptEventType = "message" | "tool_use" | "tool_result" | "summary" | "content_replace" | "file_history" | "plan_operation" | "session_meta" | "subagent" | "turn_boundary" | "goal_progress" | "turn_stopped" | "error";
 export interface TranscriptEvent {
     id: string;
     type: TranscriptEventType;
@@ -96,8 +145,28 @@ export interface SessionState {
     startedAt: number;
     model: string;
     provider: string;
+    /**
+     * Legacy/model-scoped usage summary. Some flows reset this accounting window
+     * (for example model switches), so it must not drive whole-session metrics.
+     */
     tokenUsage: TokenUsage;
+    /**
+     * Monotonic prompt-cache counters for the whole session. These only increase
+     * from session start and are separate from the resettable tokenUsage window.
+     * Optional on legacy state.json files; SessionManager normalizes them on load.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
     turnCount: number;
+    /**
+     * Conversation-turn counter where ONE user message = one turn (incremented in
+     * engine.run before the message hits the LLM). Distinct from `turnCount`,
+     * which counts turn-loop iterations (a single user message can span many).
+     * Tags file-history snapshots so turn-level `/undo` can revert exactly what
+     * the last user message changed. Absent on legacy sessions → treated as 0.
+     */
+    turnSeq?: number;
     invokedSkills: string[];
     /**
      * Owning parent session for a sub-agent run; `null` explicitly marks a
@@ -114,8 +183,25 @@ export interface SessionState {
     status: SessionStatus;
     /** Short summary derived from the first user message */
     summary?: string;
+    /**
+     * LLM-generated one-line title (auxModel, after the first turn). Distinct from
+     * `summary` (the raw first-message fallback). Persisted so the sidebar shows
+     * it after a localStorage wipe / disk rebuild — without this it lived only in
+     * the renderer's localStorage index and was lost on reset.
+     */
+    title?: string;
     /** Persisted cost tracking state (survives process restart). */
     costState?: Record<string, unknown>;
+    /**
+     * Active persistent goal (CC `/goal` style). Set once, it survives across
+     * messages AND manual interrupts until the judge says it's met or the user
+     * clears it. Absent → no active goal. When a run supplies a new goal it
+     * REPLACES this (one active goal per session). The judge's `met` verdict and
+     * `agent/goalClear` both clear it. Persisted so it survives resume/refresh;
+     * on resume the objective carries over but the run-scoped turn/token/time
+     * baselines reset (matching CC). See engine.run goal-resolution.
+     */
+    activeGoal?: GoalConfig;
 }
 export interface TokenUsage {
     promptTokens: number;
@@ -155,6 +241,8 @@ export interface PermissionRule {
     reason?: string;
 }
 export interface ApprovalRequest {
+    /** Originating engine session. Hosts use this only to route the prompt UI. */
+    sessionId?: string;
     toolName: string;
     args: Record<string, unknown>;
     description: string;
@@ -168,11 +256,22 @@ export interface ApprovalRequest {
  *               survives restart for the current project. Not committed.
  */
 export type ApprovalScope = "once" | "session" | "project";
+/**
+ * Path granularity for a remembered file-tool grant (Write/Edit). Narrows the
+ * remembered rule so "allow Write src/foo.ts for this session" doesn't become
+ * "allow Write to ANY path".
+ *   "file" — only this exact file
+ *   "dir"  — this file's directory and its subdirectories
+ *   "tool" — every path (the legacy tool-wide behavior)
+ * Omitted → "tool" (back-compat). Ignored for non-file tools.
+ */
+export type ApprovalPathScope = "file" | "dir" | "tool";
 export type ApprovalResult = {
     approved: true;
     permanent?: boolean;
     always?: boolean;
     scope?: ApprovalScope;
+    pathScope?: ApprovalPathScope;
     /** Used by AskUserQuestion to carry the user's free-text answer. */ answer?: string;
 } | {
     approved: false;
@@ -206,6 +305,10 @@ export type StreamEvent = {
     type: "stream_request_start";
     turnNumber: number;
     agentId?: string;
+} | {
+    type: "steer_injected";
+    text: string;
+    id?: string;
 } | {
     type: "text_delta";
     text: string;
@@ -234,10 +337,22 @@ export type StreamEvent = {
     agentId?: string;
 } | {
     type: "goal_progress";
-    status: "not_met" | "met" | "exhausted";
+    status: "not_met" | "met" | "exhausted" | "approaching_limit";
     round: number;
     gaps?: string;
+    /** For "approaching_limit": turns left before the maxTurns cap (TODO 3.1). */
+    turnsRemaining?: number;
+    /** For "approaching_limit": consecutive blocks left before maxStopBlocks (TODO 3.1). */
+    stopBlocksRemaining?: number;
+    /** For "approaching_limit": which ceiling is closest — drives UI copy + extend default. */
+    nearest?: "turns" | "stopBlocks";
     agentId?: string;
+} | {
+    type: "goal_set";
+    objective: string;
+    replaced: boolean;
+} | {
+    type: "goal_cleared";
 } | {
     type: "error";
     error: string;
@@ -249,6 +364,12 @@ export type StreamEvent = {
     type: "task_update";
     tasks: TaskInfo[];
     agentId?: string;
+} | {
+    type: "memory_recalled";
+    name: string;
+    scope: "user" | "dream";
+    location: "global" | "project";
+    agentId?: string;
 } | {
     type: "thinking_delta";
     text: string;
@@ -259,6 +380,12 @@ export type StreamEvent = {
     name?: string;
     description: string;
     agentType?: string;
+} | {
+    type: "agent_backgrounded";
+    agentId: string;
+    name?: string;
+    description: string;
+    agentType?: string;
 } | {
     type: "agent_end";
     agentId: string;
@@ -267,18 +394,61 @@ export type StreamEvent = {
     text?: string;
     error?: string;
     agentType?: string;
+} | {
+    type: "agent_heartbeat";
+    agentIds: string[];
+    ts: number;
 } | {
     type: "tool_summary";
     summary: string;
 } | {
     type: "context_compact";
-    strategy: "micro" | "summary" | "window" | "snip" | "emergency";
+    strategy: "micro" | "summary" | "window" | "snip" | "emergency" | "compacted";
     before: number;
     after: number;
     agentId?: string;
 } | {
     type: "usage_update";
     promptTokens: number;
+    /**
+     * Provider-reported prompt-cache counts, forwarded so the UI can show a
+     * cache hit rate in the context-ring tooltip. Present only when the LLM
+     * response carried them (authoritative-usage emits); omitted on the
+     * message-estimate emits that fire between LLM calls. See
+     * docs/todo/prompt-cache-optimization.md.
+     */
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    /**
+     * Prompt-cache metrics for the current turn only. These are reset at the
+     * start of each turn-loop iteration and sum every LLM response in that
+     * turn, including max-token continuations.
+     */
+    singleTurnPromptTokens?: number;
+    singleTurnCacheReadTokens?: number;
+    singleTurnCacheCreationTokens?: number;
+    singleTurnCacheHitRate?: number;
+    /**
+     * Whole-session monotonic prompt-cache counters/rate. Unlike the legacy
+     * session* fields below, these are not derived from the resettable
+     * tokenUsage accounting window.
+     */
+    cumulativePromptTokens?: number;
+    cumulativeCacheReadTokens?: number;
+    cumulativeCacheCreationTokens?: number;
+    cumulativeCacheHitRate?: number;
+    /**
+     * SESSION-CUMULATIVE cache counts (sum across every LLM response this
+     * session, across runs and turns), emitted from the engine's turn
+     * boundary off the persisted session.state.tokenUsage. Distinct from the
+     * per-response cacheReadTokens/cacheCreationTokens above: those drive the
+     * live context reading, these drive the "本会话累计命中率" tooltip. Reset
+     * to 0 on a model switch. Present only on the cumulative (turn-boundary)
+     * emit; omitted on per-response / estimate emits.
+     */
+    sessionCacheReadTokens?: number;
+    sessionCacheCreationTokens?: number;
+    sessionPromptTokens?: number;
     agentId?: string;
 } | {
     type: "background_agent_completed";
@@ -286,6 +456,15 @@ export type StreamEvent = {
     name?: string;
     description: string;
     status: "completed" | "failed";
+    /**
+     * What kind of background work this was. Lets UIs localize the
+     * completion toast (e.g. a shell shows "命令完成" not the raw English
+     * description, which is written for the agent's wakeup notification).
+     * Absent for legacy sub-agent notifications (treated as "agent").
+     */
+    workKind?: "agent" | "shell" | "video" | "cc";
+    /** For workKind === "shell": the command that ran (for a friendly label). */
+    command?: string;
     /** Final assistant text (status === "completed" only). */
     finalText?: string;
     /** Error message (status === "failed" only). */
@@ -317,6 +496,23 @@ export interface LLMConfig {
     apiKey?: string;
     baseUrl?: string;
     maxTokens?: number;
+    /** Per-model context window size used by hosts to seed Engine.maxContextTokens. */
+    maxContextTokens?: number;
+    /**
+     * Shell command whose stdout is the auth token (TODO 7.2). Resolved at
+     * client-build time when `apiKey` is absent. The trimmed first line of
+     * stdout becomes the bearer token.
+     */
+    authCommand?: string;
+    /**
+     * Extra HTTP headers for every request to this model's provider (TODO 7.2).
+     * A value `$ENV_VAR` is resolved from the environment at build time.
+     */
+    httpHeaders?: Record<string, string>;
+    /** OpenAI `service_tier` request param, passed through verbatim (TODO 7.2). */
+    serviceTier?: string;
+    /** OpenAI reasoning `summary` control ("auto"|"concise"|"detailed") (TODO 7.2). */
+    reasoningSummary?: string;
     /**
      * Default reasoning/thinking setting for this model. Per-call
      * `options.reasoning` (e.g. summarize sub-calls) overrides this.
@@ -331,6 +527,12 @@ export interface LLMConfig {
      * ("openai" or "anthropic") that picks which client class to use.
      */
     providerKind?: string;
+    /**
+     * Catalog-driven extra request-body fields (temperature/top_p/thinking etc),
+     * already wire-mapped from the connection's paramValues. Merged into the
+     * request body, each key filtered by the model's rejectedParams.
+     */
+    extraBody?: Record<string, unknown>;
 }
 /**
  * ClientDefaults — runtime knobs that apply regardless of which model is
@@ -347,11 +549,16 @@ export interface ClientDefaults {
     /** Max retry attempts for transient errors. Default 3. */
     retryMaxAttempts?: number;
     /**
-     * OpenAI-style detail hint sent on every image_url part. Anthropic
-     * ignores this. Defaults to "high" (OpenAI's own default) when
-     * unset; "low" is 85-tokens-per-image fixed.
+     * Provider-agnostic image clarity level. Drives the renderer-side
+     * downscale (long-edge cap: low→~1024 / standard→~1568 / high→~2576)
+     * so BOTH providers save tokens before send. On the OpenAI path it
+     * also maps to the wire `detail` hint (low→low, standard/high→high);
+     * Anthropic has no such param and saves purely via the downscale.
+     * Defaults to "high" (full fidelity) when unset.
+     *
+     * Legacy "original" values from older settings are migrated to "high".
      */
-    imageDetail?: "low" | "high" | "original";
+    imageDetail?: "low" | "standard" | "high";
 }
 export interface LLMResponse {
     text: string;
@@ -377,6 +584,28 @@ export interface MCPServerConfig {
     url?: string;
     transport?: MCPTransport;
     headers?: Record<string, string>;
+    /**
+     * (stdio) NAMES of env vars to forward from the parent process to the
+     * spawned server. The value is read from `process.env` at connect time —
+     * the secret itself is never stored in config. Explicit `env` overrides.
+     */
+    envVars?: string[];
+    /**
+     * (HTTP) NAME of an env var whose value is sent as
+     * `Authorization: Bearer <value>`. Read from `process.env` at connect time.
+     */
+    bearerTokenEnvVar?: string;
+    /**
+     * (HTTP) Map of header-name → env-var-NAME. Each header's value is read
+     * from the named env var at connect time, keeping secrets out of config.
+     */
+    envHeaders?: Record<string, string>;
+    /**
+     * (HTTP) id of a stored credential (CredentialStore) to use as the Bearer
+     * token. Resolved at connect time via a resolver passed to buildHttpHeaders;
+     * the secret is never stored in the MCP config. Wins over bearerTokenEnvVar.
+     */
+    credentialRef?: string;
     /**
      * Toggle a server off without deleting its config (mirrors Codex's
      * `enabled` field). Absent or `true` → connected; only the literal
@@ -386,6 +615,21 @@ export interface MCPServerConfig {
      */
     enabled?: boolean;
 }
+/**
+ * User-supplied supplement for a PLUGIN-provided MCP server, keyed by the
+ * server's `<plugin>:<server>` name. Stored globally under
+ * `settings.mcpServerOverrides` and layered onto the plugin's config at merge
+ * time (see mergePluginMcpServers). Only env/credential fields are allowed —
+ * command/args/url/transport stay owned by the plugin manifest so a plugin
+ * update is never shadowed by a stale user copy.
+ */
+export interface MCPServerOverride {
+    env?: Record<string, string>;
+    envVars?: string[];
+    credentialRef?: string;
+    bearerTokenEnvVar?: string;
+    envHeaders?: Record<string, string>;
+}
 /**
  * Shell-hook configuration entry from settings.json. Each entry binds
  * a hook event to a shell command. The command runs as a child process
@@ -429,6 +673,7 @@ export interface Settings {
         maxTokens: number;
         compactAtRatio: number;
         summarizeAtRatio: number;
+        microcompactFloorRatio: number;
     };
     session: {
         storageDir: string;

package/dist/updater.js

@@ -33,6 +33,7 @@ import { dirname, join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { resolveShellInvocation } from "./runtime/spawn-common.js";
 import { gt } from "./utils/semver.js";
 const execFileAsync = promisify(execFile);
 const PACKAGE_NAME = "@cjhyy/code-shell";
@@ -282,7 +283,7 @@ function launchDetachedInstall(version) {
     try {
         // Avoid `mkdirSync recursive` failures if dir exists.
         try {
-            const fs = require("node:fs");
+            const fs = createRequire(import.meta.url ?? __filename)("node:fs");
             fs.mkdirSync(configDir(), { recursive: true });
             fs.writeFileSync(lockPath, String(process.pid), { encoding: "utf8", flag: "wx" });
         }
@@ -290,7 +291,7 @@ function launchDetachedInstall(version) {
             if (errnoCode(err) === "EEXIST") {
                 // Lock held — check freshness; if stale, take over.
                 try {
-                    const fs = require("node:fs");
+                    const fs = createRequire(import.meta.url ?? __filename)("node:fs");
                     const s = fs.statSync(lockPath);
                     if (Date.now() - s.mtimeMs < LOCK_TIMEOUT_MS)
                         return; // fresh — back off
@@ -309,7 +310,7 @@ function launchDetachedInstall(version) {
     catch {
         return;
     }
-    const fs = require("node:fs");
+    const fs = createRequire(import.meta.url ?? __filename)("node:fs");
     const logFd = fs.openSync(getUpdateLogPath(), "a");
     try {
         fs.writeSync(logFd, `\n[${new Date().toISOString()}] code-shell auto-update: installing ${PACKAGE_NAME}@${version} (pid=${process.pid})\n`);
@@ -318,13 +319,23 @@ function launchDetachedInstall(version) {
         // ignore
     }
     // Wrap install + lock cleanup in a tiny shell so the lock file is removed
-    // even if npm fails. `-c` style runs as a single child, detached from us.
-    const cmd = [
-        `npm install -g ${PACKAGE_NAME}@${shellEscape(version)}`,
-        `; rm -f ${shellEscape(lockPath)}`,
-    ].join(" ");
+    // even if npm fails. Cross-platform: POSIX sequences with `; rm -f`, Windows
+    // cmd.exe with `& del /f /q` (no `sh`/`rm` there). resolveShellInvocation
+    // picks the shell binary + flag (/c vs -c) per platform.
+    const isWin = process.platform === "win32";
+    // cmd.exe doesn't understand POSIX single-quote escaping. version is a semver
+    // from npm (no shell metachars) so it needs no quoting on cmd; the lock path
+    // gets double quotes (cmd-native). POSIX keeps shellEscape on both.
+    const installPkg = isWin
+        ? `npm install -g ${PACKAGE_NAME}@${version}`
+        : `npm install -g ${PACKAGE_NAME}@${shellEscape(version)}`;
+    const cleanup = isWin
+        ? `& del /f /q "${lockPath}"`
+        : `; rm -f ${shellEscape(lockPath)}`;
+    const cmd = `${installPkg} ${cleanup}`;
+    const { file: shellFile, args: shellArgs } = resolveShellInvocation(cmd);
     try {
-        const child = spawn("sh", ["-c", cmd], {
+        const child = spawn(shellFile, shellArgs, {
             detached: true,
             stdio: ["ignore", logFd, logFd],
             cwd: homedir(),

package/dist/utils/envUtils.d.ts

@@ -36,16 +36,7 @@ export declare function getDefaultVertexRegion(): string;
  * Check if bash commands should maintain project working directory.
  */
 export declare function shouldMaintainProjectWorkingDir(): boolean;
-/**
- * Check if running on Homespace (ant-internal cloud environment).
- */
-export declare function isRunningOnHomespace(): boolean;
 /**
  * Get the Vertex AI region for a specific model.
  */
 export declare function getVertexRegionForModel(model: string | undefined): string | undefined;
-/**
- * Stub: Check if running inside a protected namespace.
- * Always returns false in Code Shell (Anthropic-internal feature).
- */
-export declare function isInProtectedNamespace(): boolean;