@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/automation/scheduler.js

@@ -14,6 +14,22 @@ import { isCronExpression, parseCronExpression, nextCronTime } from "./cron-expr
  * normal timer jitter, while still catching a multi-minute/hour sleep drift.
  */
 const CRON_MISFIRE_GRACE_MS = 90_000;
+/**
+ * Largest delay a Node/Electron timer accepts (2^31 - 1 ms, ~24.8 days).
+ *
+ * Above this, `setTimeout` does not wait longer — it warns
+ * (`TimeoutOverflowWarning`) and clamps the delay to **1ms**, so a long
+ * schedule fired instantly instead of far in the future. `armAt()` sleeps in
+ * chunks no larger than this.
+ */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Hard ceiling on a schedule interval: ~10 years. Anything beyond this is far
+ * more likely a unit mistake (passing microseconds, or a raw epoch timestamp as
+ * "milliseconds from now") than a real intent, and `nextRun` bookkeeping should
+ * not silently carry a nonsense value.
+ */
+const MAX_SCHEDULE_INTERVAL_MS = 10 * 365 * 24 * 60 * 60 * 1000;
 /**
  * True when a cron timer fired too far past its scheduled instant to be a
  * legitimate on-time run — i.e. the host slept through the scheduled time and
@@ -39,6 +55,7 @@ export class CronScheduler {
     runningControllers = new Map();
     nextId = 1;
     onExecute;
+    onJobEvent;
     /** Optional persistence backend. When set, every create/delete/pause/resume
      *  writes the full job set to disk so jobs survive a restart. */
     store;
@@ -70,6 +87,24 @@ export class CronScheduler {
     setExecutor(fn) {
         this.onExecute = fn;
     }
+    /**
+     * Observe job execution lifecycle
+     * (job_start → job_end | job_stopped | job_cancelled | job_error). Hosts
+     * wire this to their notification surface so scheduled runs — especially
+     * failures, which `fire()` otherwise swallows — are no longer silent.
+     * Listener errors are swallowed; observation never affects scheduling.
+     */
+    setJobEventListener(listener) {
+        this.onJobEvent = listener;
+    }
+    emitJobEvent(event) {
+        try {
+            this.onJobEvent?.(event);
+        }
+        catch {
+            /* observers must not affect the tick loop */
+        }
+    }
     /**
      * Abort the in-flight run of `jobId`, if any. Aborts the AbortSignal handed
      * to the executor (which Engine.run cooperates with — it resolves with
@@ -268,6 +303,7 @@ export class CronScheduler {
                     ...(opts?.permissionLevel !== undefined ? { permissionLevel: opts.permissionLevel } : {}),
                     ...(opts?.once === true ? { once: true } : {}),
                     ...(opts?.resumeSessionId !== undefined ? { resumeSessionId: opts.resumeSessionId } : {}),
+                    ...(opts?.templateSource !== undefined ? { templateSource: opts.templateSource } : {}),
                 };
                 this.refreshNextRunForDisplay(job);
                 return { jobs: [...jobs, job], result: job };
@@ -289,6 +325,7 @@ export class CronScheduler {
             ...(opts?.permissionLevel !== undefined ? { permissionLevel: opts.permissionLevel } : {}),
             ...(opts?.once === true ? { once: true } : {}),
             ...(opts?.resumeSessionId !== undefined ? { resumeSessionId: opts.resumeSessionId } : {}),
+            ...(opts?.templateSource !== undefined ? { templateSource: opts.templateSource } : {}),
         };
         this.jobs.set(id, job);
         this.arm(job);
@@ -525,22 +562,53 @@ export class CronScheduler {
             this.armInterval(job, intervalMs, nextRun);
         }
     }
+    /**
+     * Wait until an ABSOLUTE instant, in `setTimeout`-safe chunks.
+     *
+     * Node/Electron timers take a 32-bit signed delay: anything above
+     * 2,147,483,647ms (~24.8 days) does NOT wait longer — it emits
+     * `TimeoutOverflowWarning` and is coerced to **1ms**. A `30d` interval or a
+     * monthly cron therefore fired almost immediately and then kept re-firing,
+     * because the next absolute target was still out of range.
+     *
+     * So never hand a raw long delay to setTimeout. Sleep at most
+     * MAX_TIMER_DELAY_MS at a time and re-check the clock; only run `onDue` once
+     * the real instant has arrived. Chunked waiting also self-corrects for clock
+     * drift and sleep/wake, since each hop recomputes from `Date.now()`.
+     */
+    armAt(jobId, scheduledFor, onDue) {
+        const step = () => {
+            const remaining = scheduledFor - Date.now();
+            if (remaining <= 0) {
+                this.timers.delete(jobId);
+                onDue();
+                return;
+            }
+            const timer = setTimeout(step, Math.min(remaining, MAX_TIMER_DELAY_MS));
+            this.timers.set(jobId, timer);
+        };
+        step();
+    }
     armInterval(job, intervalMs, scheduledFor) {
         job.nextRun = scheduledFor;
-        const delay = Math.max(0, scheduledFor - Date.now());
-        const timer = setTimeout(() => {
-            this.timers.delete(job.id);
+        this.armAt(job.id, scheduledFor, () => {
             const rearm = () => {
                 if (!this.executionEnabled || !job.enabled || !this.jobs.has(job.id))
                     return;
                 this.armInterval(job, intervalMs, this.nextIntervalRunAfter(scheduledFor, intervalMs, Date.now()));
             };
+            // Interval jobs get the same misfire semantics cron already had: if we
+            // wake far PAST the target (host slept through it), skip this occurrence
+            // and re-arm on the next absolute slot instead of firing late.
+            if (isCronMisfire(scheduledFor, Date.now())) {
+                rearm();
+                return;
+            }
             void this.fire(job, rearm).then((ran) => {
                 if (!ran)
                     rearm();
             });
-        }, delay);
-        this.timers.set(job.id, timer);
+        });
     }
     nextIntervalRunAfter(scheduledFor, intervalMs, now) {
         let next = scheduledFor + intervalMs;
@@ -560,9 +628,7 @@ export class CronScheduler {
         }
         job.nextRun = next;
         const scheduledFor = next;
-        const delay = Math.max(0, next - Date.now());
-        const timer = setTimeout(() => {
-            this.timers.delete(job.id);
+        this.armAt(job.id, scheduledFor, () => {
             // Misfire guard for sleep/wake drift. A setTimeout pauses while the host
             // sleeps, then fires the instant the machine wakes — which can be hours
             // off the scheduled wall-clock (observed: a `0 9 * * *` job running at
@@ -586,8 +652,7 @@ export class CronScheduler {
                 if (!ran)
                     rearm();
             });
-        }, delay);
-        this.timers.set(job.id, timer);
+        });
     }
     clearTimer(id) {
         const t = this.timers.get(id);
@@ -626,11 +691,33 @@ export class CronScheduler {
         afterStats();
         // Persist updated run stats so runCount/lastRun/nextRun survive a restart.
         this.persistRunStats(job);
+        const startedAt = Date.now();
+        this.emitJobEvent({ type: "job_start", job });
         try {
-            await this.onExecute?.(job, controller.signal);
+            const outcome = await this.onExecute?.(job, controller.signal);
+            this.emitJobEvent({
+                type: controller.signal.aborted
+                    ? "job_cancelled"
+                    : outcome?.stoppedReason
+                        ? "job_stopped"
+                        : "job_end",
+                job,
+                durationMs: Date.now() - startedAt,
+                ...(outcome?.stoppedReason ? { reason: outcome.stoppedReason } : {}),
+            });
         }
-        catch {
-            // Job execution failed — continue scheduling.
+        catch (err) {
+            // Cancellation is an owner decision, not a job failure. A transport may
+            // reject on AbortSignal instead of resolving, so classify from the
+            // scheduler-owned signal on both terminal paths.
+            this.emitJobEvent({
+                type: controller.signal.aborted ? "job_cancelled" : "job_error",
+                job,
+                durationMs: Date.now() - startedAt,
+                ...(controller.signal.aborted
+                    ? {}
+                    : { error: err instanceof Error ? err.message : String(err) }),
+            });
         }
         finally {
             // The executor may have recorded lastRunId on the job. Persist only run
@@ -651,13 +738,15 @@ export class CronScheduler {
     }
 }
 /** Validate a schedule string (interval or cron expr) without scheduling. Throws on invalid. */
-function validateSchedule(schedule, timezone) {
+export function validateSchedule(schedule, timezone) {
+    // A supplied timezone must always be a real IANA zone, even for interval
+    // schedules where it is currently display-only. Persisting inert garbage
+    // would later become executable if the schedule is edited to cron.
+    if (timezone !== undefined) {
+        new Intl.DateTimeFormat("en-US", { timeZone: timezone });
+    }
     if (isCronExpression(schedule)) {
         parseCronExpression(schedule); // throws on bad fields
-        // Validate timezone is acceptable to Intl (throws RangeError if not).
-        if (timezone !== undefined) {
-            new Intl.DateTimeFormat("en-US", { timeZone: timezone });
-        }
         return;
     }
     parseSchedule(schedule); // throws on bad interval
@@ -671,6 +760,17 @@ function validateSchedule(schedule, timezone) {
  * 10 minutes (review-2026-05-30).
  */
 export function parseSchedule(schedule) {
+    // Reject anything that is not a finite, safe, in-range interval. Long values
+    // are no longer an overflow hazard (armAt sleeps in chunks), but a value that
+    // cannot survive arithmetic — beyond Number.MAX_SAFE_INTEGER, or an absurd
+    // "10 years from now" — is a caller mistake, not a schedule. Failing here
+    // keeps `nextRun` and the re-arm math meaningful.
+    const accept = (ms) => {
+        if (!Number.isSafeInteger(ms) || ms <= 0 || ms > MAX_SCHEDULE_INTERVAL_MS) {
+            throw new Error(`Invalid schedule: ${JSON.stringify(schedule)}. Interval must be between 1ms and ${MAX_SCHEDULE_INTERVAL_MS}ms (~10 years).`);
+        }
+        return ms;
+    };
     const match = schedule.match(/^(\d+)(s|m|h|d)$/);
     if (match) {
         const value = parseInt(match[1], 10);
@@ -680,13 +780,13 @@ export function parseSchedule(schedule) {
         if (value > 0) {
             switch (match[2]) {
                 case "s":
-                    return value * 1000;
+                    return accept(value * 1000);
                 case "m":
-                    return value * 60 * 1000;
+                    return accept(value * 60 * 1000);
                 case "h":
-                    return value * 60 * 60 * 1000;
+                    return accept(value * 60 * 60 * 1000);
                 case "d":
-                    return value * 24 * 60 * 60 * 1000;
+                    return accept(value * 24 * 60 * 60 * 1000);
             }
         }
     }
@@ -695,7 +795,7 @@ export function parseSchedule(schedule) {
     if (/^\d+$/.test(schedule)) {
         const ms = parseInt(schedule, 10);
         if (ms > 0)
-            return ms;
+            return accept(ms);
     }
     throw new Error(`Invalid schedule: ${JSON.stringify(schedule)}. Use "30s"/"5m"/"1h"/"1d" or a positive number of milliseconds.`);
 }

package/dist/automation/store.d.ts

@@ -12,8 +12,12 @@
  * with a stale in-memory snapshot.
  */
 import type { CronJob } from "./scheduler.js";
-/** Default global location. Mirrors FileRunStore's `~/.code-shell/...` layout. */
-export declare function defaultCronStorePath(): string;
+/**
+ * Default global location. Mirrors FileRunStore's `~/.code-shell/...` layout.
+ * An explicit `root` (a `~/.code-shell`-equivalent data root) overrides the
+ * default; absent → today's behavior byte-for-byte.
+ */
+export declare function defaultCronStorePath(root?: string): string;
 export declare class CronStore {
     private readonly file;
     constructor(file?: string);

package/dist/automation/store.js

@@ -16,9 +16,13 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { logger } from "../logging/logger.js";
 import { lockSync } from "../utils/lockfile.js";
-/** Default global location. Mirrors FileRunStore's `~/.code-shell/...` layout. */
-export function defaultCronStorePath() {
-    return join(homedir(), ".code-shell", "cron.json");
+/**
+ * Default global location. Mirrors FileRunStore's `~/.code-shell/...` layout.
+ * An explicit `root` (a `~/.code-shell`-equivalent data root) overrides the
+ * default; absent → today's behavior byte-for-byte.
+ */
+export function defaultCronStorePath(root) {
+    return join(root ?? join(homedir(), ".code-shell"), "cron.json");
 }
 export class CronStore {
     file;

package/dist/capabilities/index.d.ts

@@ -0,0 +1,109 @@
+import type { AgentPreset } from "../preset/index.js";
+import type { BuiltinTool } from "../tool-system/builtin/index.js";
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
+import type { SessionManager } from "../session/session-manager.js";
+import type { ArtifactKind, ArtifactRole } from "../run/types.js";
+import type { HookEventName } from "../hooks/events.js";
+import type { HookHandler } from "../hooks/registry.js";
+/**
+ * A host-installable slice of agent behavior.
+ *
+ * Core owns the lifecycle and execution contracts; product packages contribute
+ * tools, presets, and prompt text through this boundary. Modules are plain data
+ * so a host can compose them per Engine without mutating process-global state.
+ */
+export interface CapabilityModule {
+    id: string;
+    tools?: readonly BuiltinTool[];
+    presets?: readonly AgentPreset[];
+    /** Preset selected when this capability is installed and the host did not choose one. */
+    defaultPreset?: string;
+    promptSections?: Readonly<Record<string, string>>;
+    /** Volatile, capability-owned context appended after the cacheable prompt prefix. */
+    dynamicContextProviders?: readonly CapabilityDynamicContextProvider[];
+    /** Optional project boundary for layered instruction discovery. */
+    instructionBoundary?: CapabilityInstructionBoundaryFinder;
+    /** Runtime services exposed only to this capability's tools. */
+    createToolService?(host: CapabilityToolServiceHost): unknown;
+    /** Capability-specific run artifact recognition. */
+    artifactDetectors?: readonly CapabilityArtifactDetector[];
+    /** Pre-mutation snapshot targets for capability-owned compound file tools. */
+    fileHistory?: readonly CapabilityFileHistoryContribution[];
+    /** Optional validation for persisted product-specific workspace pointers. */
+    sessionWorkspace?: SessionWorkspaceCapability;
+    /** Trusted in-process handlers joined to this Engine's normal hook chain. */
+    engineHooks?: readonly CapabilityEngineHookContribution[];
+    adjustToolSelection?(names: Set<string>, context: CapabilityToolSelectionContext): void;
+}
+export interface CapabilityEngineHookContribution {
+    event: HookEventName;
+    handler: HookHandler;
+    priority?: number;
+    name?: string;
+}
+export interface ResolvedCapabilityEngineHook extends CapabilityEngineHookContribution {
+    capabilityId: string;
+    priority: number;
+    name: string;
+}
+export interface CapabilityDynamicContext {
+    cwd: string;
+    preset: AgentPreset;
+}
+export type CapabilityDynamicContextProvider = (context: CapabilityDynamicContext) => string | undefined | Promise<string | undefined>;
+export type CapabilityInstructionBoundaryFinder = (cwd: string) => string | null;
+/** Generic host services from which a capability may build its private tool service. */
+export interface CapabilityToolServiceHost {
+    readonly isSubAgent: boolean;
+    readonly settings: {
+        get(): unknown;
+        getForScope(scope: "user" | "project", cwd?: string): unknown;
+    };
+    resolveSandbox(cwd: string): Promise<SandboxBackend>;
+    readShellEnv(cwd?: string): Record<string, string> | undefined;
+    getSessionManager(): SessionManager;
+}
+export interface CapabilityArtifact {
+    kind: ArtifactKind;
+    role: ArtifactRole;
+    title: string;
+    locator: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CapabilityArtifactDetectionContext {
+    toolName: string;
+    args: Record<string, unknown>;
+    resultText?: string;
+}
+export type CapabilityArtifactDetector = (context: CapabilityArtifactDetectionContext) => CapabilityArtifact | readonly CapabilityArtifact[] | undefined;
+export interface CapabilityToolSelectionContext {
+    preset: string;
+    host?: string;
+}
+export interface SessionWorkspaceCapability {
+    validateRoot(root: string): Promise<boolean>;
+    branchExists(mainRoot: string, branch: string): Promise<boolean>;
+}
+export interface CapabilityFileHistoryContribution {
+    toolName: string;
+    resolveTargets(args: Record<string, unknown>, cwd: string): readonly string[];
+}
+/**
+ * Install a capability at a process composition root (CLI/desktop worker).
+ * Library consumers should prefer EngineConfig.capabilities for isolation.
+ */
+export declare function registerCapability(capability: CapabilityModule): void;
+/** Primarily useful for isolated hosts and tests that own their process. */
+export declare function unregisterCapability(id: string): void;
+export declare function listRegisteredCapabilities(): CapabilityModule[];
+/** Merge process-installed and per-Engine modules, rejecting ambiguous IDs. */
+export declare function resolveCapabilities(local?: readonly CapabilityModule[]): CapabilityModule[];
+export declare function composeToolCatalog(coreTools: readonly BuiltinTool[], capabilities: readonly CapabilityModule[], extensionModules?: readonly {
+    catalogTools?: readonly BuiltinTool[];
+}[]): BuiltinTool[];
+export declare function composePromptSections(capabilities: readonly CapabilityModule[]): Record<string, string>;
+export declare function composeDynamicContextProviders(capabilities: readonly CapabilityModule[]): CapabilityDynamicContextProvider[];
+export declare function composeArtifactDetectors(capabilities: readonly CapabilityModule[]): CapabilityArtifactDetector[];
+/** Normalize code hooks with deterministic names and a product-module priority. */
+export declare function composeCapabilityEngineHooks(capabilities: readonly CapabilityModule[]): ResolvedCapabilityEngineHook[];
+export declare function resolveInstructionBoundary(cwd: string, capabilities: readonly CapabilityModule[]): string | null;

package/dist/capabilities/index.js

@@ -0,0 +1,80 @@
+const installedCapabilities = new Map();
+/**
+ * Install a capability at a process composition root (CLI/desktop worker).
+ * Library consumers should prefer EngineConfig.capabilities for isolation.
+ */
+export function registerCapability(capability) {
+    const existing = installedCapabilities.get(capability.id);
+    if (existing === capability)
+        return;
+    if (existing)
+        throw new Error(`Capability '${capability.id}' is already registered`);
+    installedCapabilities.set(capability.id, capability);
+}
+/** Primarily useful for isolated hosts and tests that own their process. */
+export function unregisterCapability(id) {
+    installedCapabilities.delete(id);
+}
+export function listRegisteredCapabilities() {
+    return [...installedCapabilities.values()];
+}
+/** Merge process-installed and per-Engine modules, rejecting ambiguous IDs. */
+export function resolveCapabilities(local = []) {
+    const resolved = new Map(installedCapabilities);
+    for (const capability of local) {
+        const existing = resolved.get(capability.id);
+        if (existing && existing !== capability) {
+            throw new Error(`Capability '${capability.id}' was provided more than once`);
+        }
+        resolved.set(capability.id, capability);
+    }
+    return [...resolved.values()];
+}
+export function composeToolCatalog(coreTools, capabilities, extensionModules = []) {
+    const catalog = new Map();
+    for (const tool of [
+        ...coreTools,
+        ...capabilities.flatMap((capability) => [...(capability.tools ?? [])]),
+        ...extensionModules.flatMap((module) => [...(module.catalogTools ?? [])]),
+    ]) {
+        const name = tool.definition.name;
+        if (catalog.has(name))
+            throw new Error(`Tool '${name}' is contributed more than once`);
+        catalog.set(name, tool);
+    }
+    return [...catalog.values()];
+}
+export function composePromptSections(capabilities) {
+    const sections = {};
+    for (const capability of capabilities) {
+        for (const [name, content] of Object.entries(capability.promptSections ?? {})) {
+            if (name in sections)
+                throw new Error(`Prompt section '${name}' is contributed more than once`);
+            sections[name] = content;
+        }
+    }
+    return sections;
+}
+export function composeDynamicContextProviders(capabilities) {
+    return capabilities.flatMap((capability) => [...(capability.dynamicContextProviders ?? [])]);
+}
+export function composeArtifactDetectors(capabilities) {
+    return capabilities.flatMap((capability) => [...(capability.artifactDetectors ?? [])]);
+}
+/** Normalize code hooks with deterministic names and a product-module priority. */
+export function composeCapabilityEngineHooks(capabilities) {
+    return capabilities.flatMap((capability) => (capability.engineHooks ?? []).map((hook, index) => ({
+        ...hook,
+        capabilityId: capability.id,
+        priority: hook.priority ?? 20,
+        name: `capability:${capability.id}:${hook.name ?? `${hook.event}:${index}`}`,
+    })));
+}
+export function resolveInstructionBoundary(cwd, capabilities) {
+    for (const capability of capabilities) {
+        const boundary = capability.instructionBoundary?.(cwd);
+        if (boundary)
+            return boundary;
+    }
+    return null;
+}

package/dist/capability-control/disabled-lists.d.ts

@@ -11,6 +11,7 @@
  * fold through here so "project on overrides global off" holds everywhere.
  */
 import { SettingsManager } from "../settings/manager.js";
+import type { CapabilityOverrides } from "../settings/schema.js";
 export interface EffectiveDisabledLists {
     disabledSkills: string[];
     disabledPlugins: string[];
@@ -22,4 +23,4 @@ export interface EffectiveDisabledLists {
  * Compute the effective disabled lists for `cwd`. Never throws — any read
  * error falls back to empty lists (same contract as Engine.readDisabledLists).
  */
-export declare function computeEffectiveDisabledLists(sm: SettingsManager, cwd: string | undefined): EffectiveDisabledLists;
+export declare function computeEffectiveDisabledLists(sm: SettingsManager, cwd: string | undefined, explicitProfileOverrides?: CapabilityOverrides): EffectiveDisabledLists;

package/dist/capability-control/disabled-lists.js

@@ -13,20 +13,18 @@
 import { noRepoDir } from "../settings/manager.js";
 import { scanSkills } from "../skills/scanner.js";
 import { readInstalledPlugins } from "../plugins/installedPlugins.js";
-import { effectiveDisabledList, whitelistDisabledList } from "./overlay.js";
+import { effectiveDisabledList, effectiveProjectOverrides, whitelistDisabledList, } from "./overlay.js";
 /**
  * Compute the effective disabled lists for `cwd`. Never throws — any read
  * error falls back to empty lists (same contract as Engine.readDisabledLists).
  */
-export function computeEffectiveDisabledLists(sm, cwd) {
+export function computeEffectiveDisabledLists(sm, cwd, explicitProfileOverrides) {
     try {
         const settings = sm.get();
         // Read the project overlay UNMERGED (getForScope), not the merged get(),
         // so tri-state inheritance survives. No cwd / no overlay → the baseline
         // is returned unchanged (zero regression).
-        const overrides = cwd
-            ? sm.getForScope("project", cwd).capabilityOverrides
-            : undefined;
+        const overrides = effectiveProjectOverrides(sm, cwd, explicitProfileOverrides);
         // no-repo "conversation" scope: INVERT skill/plugin filtering to a
         // whitelist (default-all-off, only explicit "on" survives). Only this
         // fixed cwd flips; every real project keeps the denylist below. agent/

package/dist/capability-control/overlay.d.ts

@@ -12,8 +12,9 @@
  * See docs/superpowers/specs/2026-06-01-project-scoped-capabilities-and-session-isolation-design.md
  */
 import type { CapabilityOverride, CapabilityOverrides } from "../settings/schema.js";
+import type { SettingsManager } from "../settings/manager.js";
 import type { CapabilityDescriptor } from "./types.js";
-/** Buckets in capabilityOverrides: "skills" | "plugins" | "agents" | "mcp" | "builtin". */
+/** Buckets in capabilityOverrides. */
 export type OverrideBucket = keyof NonNullable<CapabilityOverrides>;
 /** Apply a tri-state override to a baseline. inherit/garbage → baseline. */
 export declare function applyOverride(globalEnabled: boolean, override?: CapabilityOverride): boolean;
@@ -62,3 +63,15 @@ export declare function effectiveBuiltinLists(globalEnabled: string[], globalDis
     enabledBuiltinTools: string[];
     disabledBuiltinTools: string[];
 };
+/**
+ * 合并两层三态 overlay：`top`（用户手写 capabilityOverrides）按 key 赢过
+ * `base`（profile.overrides 快照）。Pet visibility 属于 host/project 策略，
+ * 不可由 portable profile 注入；只保留 top 的直接项目设置。
+ */
+export declare function mergeCapabilityOverrides(base: CapabilityOverrides | undefined, top: CapabilityOverrides | undefined): CapabilityOverrides | undefined;
+/**
+ * 项目 overrides 的唯一读取咽喉：profile 快照垫底、用户手写覆盖。
+ * 所有折叠消费方（engine / disabled-lists / capability service）必须
+ * 经这里读，不得再直接 getForScope().capabilityOverrides。
+ */
+export declare function effectiveProjectOverrides(settings: Pick<SettingsManager, "getForScope">, cwd: string | undefined, explicitProfileOverrides?: CapabilityOverrides): CapabilityOverrides | undefined;

package/dist/capability-control/overlay.js

@@ -114,3 +114,43 @@ export function effectiveBuiltinLists(globalEnabled, globalDisabled, bucket) {
         disabledBuiltinTools: [...disabled],
     };
 }
+const PROFILE_MERGED_OVERRIDE_BUCKETS = [
+    "skills",
+    "plugins",
+    "agents",
+    "mcp",
+    "builtin",
+    "pluginHooks",
+];
+/**
+ * 合并两层三态 overlay：`top`（用户手写 capabilityOverrides）按 key 赢过
+ * `base`（profile.overrides 快照）。Pet visibility 属于 host/project 策略，
+ * 不可由 portable profile 注入；只保留 top 的直接项目设置。
+ */
+export function mergeCapabilityOverrides(base, top) {
+    const merged = {};
+    for (const bucket of PROFILE_MERGED_OVERRIDE_BUCKETS) {
+        const combined = { ...(base?.[bucket] ?? {}), ...(top?.[bucket] ?? {}) };
+        if (Object.keys(combined).length > 0)
+            merged[bucket] = combined;
+    }
+    if (top?.pet && Object.keys(top.pet).length > 0)
+        merged.pet = { ...top.pet };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * 项目 overrides 的唯一读取咽喉：profile 快照垫底、用户手写覆盖。
+ * 所有折叠消费方（engine / disabled-lists / capability service）必须
+ * 经这里读，不得再直接 getForScope().capabilityOverrides。
+ */
+export function effectiveProjectOverrides(settings, cwd, explicitProfileOverrides) {
+    if (!cwd)
+        return undefined;
+    try {
+        const scoped = settings.getForScope("project", cwd);
+        return mergeCapabilityOverrides(explicitProfileOverrides ?? scoped.profile?.overrides, scoped.capabilityOverrides);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/capability-control/service.js

@@ -13,7 +13,7 @@
  */
 import { CapabilityNotFoundError } from "./types.js";
 import { projectBuiltin, projectMcp, projectSkills, projectPlugins, projectAgents, } from "./project.js";
-import { applyOverride, bucketForKind, overrideTokenForId, overrideFor } from "./overlay.js";
+import { applyOverride, bucketForKind, effectiveProjectOverrides, overrideTokenForId, overrideFor, } from "./overlay.js";
 export class CapabilityService {
     deps;
     constructor(deps) {
@@ -59,19 +59,21 @@ export class CapabilityService {
                 disabledAgents: s.disabledAgents ?? [],
             }),
         ];
-        const overrides = cwd
+        const userOverrides = cwd
             ? this.deps.settings.getForScope("project", cwd).capabilityOverrides
             : undefined;
+        const foldedOverrides = cwd ? effectiveProjectOverrides(this.deps.settings, cwd) : undefined;
         return base.map((d) => {
             const globalEnabled = d.enabled;
             const token = overrideTokenForId(d.id);
-            const ov = cwd ? overrideFor(overrides, d.kind, token) : undefined;
+            const ov = cwd ? overrideFor(foldedOverrides, d.kind, token) : undefined;
+            const userOverride = cwd ? overrideFor(userOverrides, d.kind, token) : undefined;
             const enabled = applyOverride(globalEnabled, ov);
             return {
                 ...d,
                 enabled,
                 globalEnabled,
-                projectOverride: ov,
+                projectOverride: userOverride,
                 effectiveSource: ov ? "project" : cwd ? "default" : "user",
             };
         });

package/dist/cli/agent-server-stdio.d.ts

@@ -37,7 +37,7 @@ import { type ValidatedSettings } from "../settings/schema.js";
  * reached session engines (slice arrived with only permissionMode+cwd).
  */
 export declare function resolveSessionAgentConfig(slice: EngineConfigSlice, settings: ValidatedSettings): {
-    preset: string;
+    preset: string | undefined;
     customSystemPrompt: string | undefined;
     appendSystemPrompt: string | undefined;
 };