@code-yeongyu/senpi 2026.10.16-3 → 2026.10.16-4

package/dist/core/retry-fallback/circuit-probes.js

@@ -23,6 +23,9 @@ export class CircuitProbes {
     governs(selector) {
         return this.circuits?.governs(selector) ?? false;
     }
+    isExhausted(selector) {
+        return this.circuits?.isExhausted(selector) ?? false;
+    }
     admit(selector) {
         const admission = this.circuits?.admit(selector) ?? { kind: "closed" };
         if (admission.kind === "probe" && this.token?.selector !== selector) {

package/dist/core/retry-fallback/circuit.d.ts

@@ -29,6 +29,8 @@ export interface CircuitOpenRequest {
     retryAfterMs?: number;
     /** The reset window a usage limit named for itself; when present it alone sets the open. */
     resetWindowMs?: number;
+    /** The failure is a verdict for every session: the entry is spent (billing, quota, an account limit). A provider-named wait is not. */
+    exhausted?: boolean;
 }
 export interface ProbeToken {
     readonly selector: string;
@@ -63,6 +65,7 @@ export declare class FallbackCircuitBreaker {
     releaseOwnersWithPrefix(prefix: string): void;
     close(selector: string): void;
     has(selector: string): boolean;
+    isExhausted(selector: string): boolean;
     sweep(now: number): void;
 }
 /**
@@ -80,6 +83,8 @@ export interface FallbackCircuitAccess {
     /** Whether the breaker holds any state for the selector, i.e. it, not a session cooldown, governs recovery. */
     governs(selector: string): boolean;
     isOpen(selector: string, lane?: CircuitLane): boolean;
+    /** Whether the open circuit records a verdict every session should act on: the entry is spent. */
+    isExhausted(selector: string): boolean;
     admit(selector: string, lane?: CircuitLane): CircuitAdmission;
     release(token: ProbeToken): void;
     releaseAll(): void;

package/dist/core/retry-fallback/circuit.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { parseRetryAfterMsMarker } from "@earendil-works/pi-ai/utils/retry-hint";
 import { usageLimitReset } from "../credential-pool/reset-time.js";
+import { isHealthExhaustionFailure } from "./circuit-probes.js";
 import { usageLimitScope } from "./usage-limit.js";
 /**
  * Fallback-chain circuit breaker. An entry that fails out of a configured chain
@@ -34,8 +35,14 @@ export class FallbackCircuitBreaker {
     }
     open(selector, request) {
         const previous = this.circuits.get(selector);
-        const consecutiveOpens = (previous?.consecutiveOpens ?? 0) + 1;
-        const cooldownMs = Math.min(request.cooldownMs * 2 ** (consecutiveOpens - 1), request.maxCooldownMs);
+        // A failure while the circuit is still open (concurrent sessions failing together) belongs to
+        // the same open episode: it takes no backoff step. Only a failure once the open has elapsed, a
+        // failed half-open probe, advances it (senpi#3467).
+        const sameEpisode = previous !== undefined && request.now < previous.openUntil;
+        const consecutiveOpens = (previous?.consecutiveOpens ?? 0) + (sameEpisode ? 0 : 1);
+        const cooldownMs = sameEpisode
+            ? previous.cooldownMs
+            : Math.min(request.cooldownMs * 2 ** (consecutiveOpens - 1), request.maxCooldownMs);
         const retryAfterMs = request.retryAfterMs;
         const hinted = retryAfterMs !== undefined && Number.isFinite(retryAfterMs) && retryAfterMs > 0
             ? request.now + retryAfterMs
@@ -53,7 +60,7 @@ export class FallbackCircuitBreaker {
         const hintedUntil = Math.min(retryFloorUntil, request.now + request.maxCooldownMs);
         const openUntil = resetWindowMs !== undefined && Number.isFinite(resetWindowMs) && resetWindowMs > 0
             ? Math.max(request.now + Math.min(resetWindowMs, request.maxCooldownMs), hintedUntil)
-            : Math.max(request.now + cooldownMs, hintedUntil);
+            : Math.max(sameEpisode ? previous.openUntil : request.now + cooldownMs, hintedUntil);
         this.circuits.set(selector, {
             openUntil,
             retryFloorUntil,
@@ -61,6 +68,7 @@ export class FallbackCircuitBreaker {
             cooldownMs,
             maxCooldownMs: request.maxCooldownMs,
             probe: undefined,
+            exhausted: request.exhausted === true || (sameEpisode && previous.exhausted),
         });
         return openUntil;
     }
@@ -111,6 +119,9 @@ export class FallbackCircuitBreaker {
     has(selector) {
         return this.circuits.has(selector);
     }
+    isExhausted(selector) {
+        return this.circuits.get(selector)?.exhausted === true;
+    }
     sweep(now) {
         for (const [selector, circuit] of this.circuits) {
             if (!circuit.probe && now >= circuit.openUntil + circuit.maxCooldownMs)
@@ -137,10 +148,22 @@ export function createFallbackCircuitAccess(deps) {
                 : undefined;
             const resetWindowMs = reset !== undefined && (reset.kind === "absolute" || reset.ms >= cooldownMs) ? reset.ms : undefined;
             deps.breaker.sweep(now);
-            const openUntil = deps.breaker.open(selector, { now, cooldownMs, maxCooldownMs, retryAfterMs, resetWindowMs });
+            // Only a verdict that the entry is spent for everyone (billing, quota, an account usage limit) moves
+            // sessions that never failed on it. A slow request, an overload or a rate limit with a Retry-After is
+            // this session's view: siblings keep their model and find out on their own request (senpi#3467).
+            const exhausted = message !== undefined && (isHealthExhaustionFailure(message) || usageLimitScope(message) === "account");
+            const openUntil = deps.breaker.open(selector, {
+                now,
+                cooldownMs,
+                maxCooldownMs,
+                retryAfterMs,
+                resetWindowMs,
+                exhausted,
+            });
             deps.logger.info("circuit_opened", { selector, durationMs: openUntil - now, retryAfterMs, resetWindowMs });
         },
         governs: (selector) => enabled() && deps.breaker.has(selector),
+        isExhausted: (selector) => enabled() && deps.breaker.isExhausted(selector),
         isOpen: (selector, lane = "turn") => enabled() && deps.breaker.isOpen(selector, deps.now(), laneOwner(deps.owner(), lane)),
         admit: (selector, lane = "turn") => enabled() ? deps.breaker.admit(selector, deps.now(), laneOwner(deps.owner(), lane)) : { kind: "closed" },
         release: (token) => deps.breaker.release(token),

package/dist/core/retry-fallback/controller.d.ts

@@ -10,6 +10,7 @@ export declare class RetryFallbackController {
     private lastExhaustedChainKey;
     private heldForNetworkBlip;
     private blipModel;
+    private readonly ownFailures;
     private readonly unusable;
     readonly probes: CircuitProbes;
     private canonicalCache;
@@ -56,6 +57,8 @@ export declare class RetryFallbackController {
     notifyCompactionApplied(): boolean;
     /** A user-driven model change abandons the fallback window entirely. */
     clearForManualModelChange(model: Model<Api>): void;
+    /** A response this session got from `selector` succeeded: the entry serves it again (senpi#3467). */
+    noteServed(selector: string): void;
     /**
      * Records a failure that makes the entry unusable for every session - billing
      * or quota exhaustion, or a transient failure that spent its budget or failed a
@@ -63,10 +66,12 @@ export declare class RetryFallbackController {
      */
     noteHealthFailure(model: Model<Api>, thinkingLevel: ThinkingLevel | undefined, failure: CircuitFailure): void;
     /**
-     * Turn-boundary skip: when the current entry's circuit was opened by this or a
-     * sibling session, move to the next closed entry without spending a request on
-     * it. With no closed entry left the current one stays and probes, so the chain
-     * never refuses a turn; a half-open current entry is claimed for this session.
+     * Turn-boundary skip: when the current entry's circuit is open because this session
+     * saw it fail (and has not been served by it since), or because its account is spent
+     * for everyone, move to the next closed entry without spending a request on it. A
+     * sibling's bare failure or Retry-After never moves this session (senpi#3467). With no
+     * closed entry left the current one stays and probes, so the chain never refuses a
+     * turn; a half-open current entry is claimed for this session.
      */
     rerouteAroundOpenCircuit(): Promise<boolean>;
     tryFallback(reason: FallbackReason, failure: {

package/dist/core/retry-fallback/controller.js

@@ -11,6 +11,9 @@ export class RetryFallbackController {
         this.triedSelectors = new Set();
         // A fallback forced by a network blip serves out its turn; only the next turn boundary reverts it.
         this.heldForNetworkBlip = false;
+        // Entries this session itself saw fail out of a chain: only these (or an entry spent for everyone)
+        // may move the session off its model at a turn boundary (senpi#3467).
+        this.ownFailures = new Set();
         this.deps = deps;
         this.probes = new CircuitProbes(deps.circuits);
         this.unusable = new UnusableEntries(deps.cooldowns);
@@ -159,11 +162,17 @@ export class RetryFallbackController {
         }
         this.state = undefined;
         this.heldForNetworkBlip = false;
+        this.ownFailures.delete(formatSelector(model));
         this.deps.cooldowns.clearModel(formatSelector(model));
         this.unusable.clear(model);
         this.probes.release();
         this.deps.circuits?.close(formatSelector(model));
     }
+    /** A response this session got from `selector` succeeded: the entry serves it again (senpi#3467). */
+    noteServed(selector) {
+        this.ownFailures.delete(selector);
+        this.probes.accept(selector);
+    }
     /**
      * Records a failure that makes the entry unusable for every session - billing
      * or quota exhaustion, or a transient failure that spent its budget or failed a
@@ -176,21 +185,29 @@ export class RetryFallbackController {
         // A pure network fault is the transport's, not the model's: it never opens the shared circuit (senpi#3306).
         if (isPureNetworkTransient(failure.errorMessage))
             return;
+        this.ownFailures.add(formatSelector(model));
         this.probes.noteFailure(formatSelector(model), failure);
     }
     /**
-     * Turn-boundary skip: when the current entry's circuit was opened by this or a
-     * sibling session, move to the next closed entry without spending a request on
-     * it. With no closed entry left the current one stays and probes, so the chain
-     * never refuses a turn; a half-open current entry is claimed for this session.
+     * Turn-boundary skip: when the current entry's circuit is open because this session
+     * saw it fail (and has not been served by it since), or because its account is spent
+     * for everyone, move to the next closed entry without spending a request on it. A
+     * sibling's bare failure or Retry-After never moves this session (senpi#3467). With no
+     * closed entry left the current one stays and probes, so the chain never refuses a
+     * turn; a half-open current entry is claimed for this session.
      */
     async rerouteAroundOpenCircuit() {
         const current = this.deps.getCurrentSelector();
         if (!this.deps.circuits || !current)
             return false;
         const currentBase = formatSelector(current.model);
+        // A half-open entry is still claimed as this session's single probe whoever opened it.
         if (this.probes.admit(currentBase) !== "open")
             return false;
+        // Another session's bare failure says this entry was slow for that session, not that it is
+        // down for this one: a session that never failed on it keeps its model and finds out itself.
+        if (!this.ownFailures.has(currentBase) && !this.probes.isExhausted(currentBase))
+            return false;
         const candidate = this.nextCandidate(false, true);
         if (!candidate || candidate.circuitOpen)
             return false;

package/dist/core/settings-manager.d.ts

@@ -4,6 +4,7 @@ import type { RetryPolicyProfile } from "@earendil-works/pi-ai/utils/retry-profi
 import type { TuiMode as RendererTuiMode, ScrollViewScrollbar, TerminalCapabilities, WheelScrollLines } from "@earendil-works/pi-tui";
 import type { CompactionModelSelector, CompactionSettings } from "./compaction-settings-access.ts";
 import { type ResolvedCompactionSettings } from "./compaction-settings-resolver.ts";
+import type { ContextFileLimits } from "./context-files.ts";
 import { type FallbackCircuitSettings, type ResolvedFallbackCircuitSettings } from "./retry-fallback/circuit.ts";
 import { type ResolvedHintPolicySettings, type ResolvedRetryFallbackSettings, type RetrySettings as RetrySettingsConfig } from "./retry-fallback/settings.ts";
 import { parseSettingsJson } from "./settings-json.ts";
@@ -68,6 +69,7 @@ export interface Settings {
     compaction?: CompactionSettings & {
         model?: string;
     };
+    contextFiles?: ContextFileLimits;
     branchSummary?: BranchSummarySettings;
     retry?: RetrySettingsConfig;
     fallback?: FallbackCircuitSettings;
@@ -167,6 +169,8 @@ export declare function getSettingsPath(cwd: string, agentDir: string, scope: Se
 export declare function getInMemorySettingsPath(scope: SettingsScope): string;
 export interface SettingsManagerCreateOptions {
     projectTrusted?: boolean;
+    /** The project trust exists only because the session runs Full access (senpi#3414): leaving it withdraws the trust. */
+    trustFromFullAccess?: boolean;
 }
 export interface SettingsStorage {
     withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
@@ -281,6 +285,17 @@ export declare class SettingsManager {
     getTodoFirstTurnPlan(): TodoFirstTurnPlan;
     getTodoTurnEndBackstop(): boolean;
     isProjectTrusted(): boolean;
+    /**
+     * True when this session's project trust came only from its Full access preset (never asked, never
+     * saved): leaving Full access withdraws it, and going back restores it (senpi#3414, #3420).
+     */
+    private trustFromFullAccess;
+    isTrustFromFullAccess(): boolean;
+    /** True when a Full-access-only trust was withdrawn in this session and Full access may restore it. */
+    canRestoreFullAccessTrust(): boolean;
+    /** Counts project-trust changes; a reload compares it before installing what it loaded (#3420). */
+    private trustEpoch;
+    getTrustEpoch(): number;
     setProjectTrusted(trusted: boolean): void;
     reload(): Promise<void>;
     getSelectedSettingsSources(): SettingsSourceSelection[];

package/dist/core/settings-manager.js

@@ -465,6 +465,13 @@ export class SettingsManager {
         this.selectedSources = new Map();
         this.sourceListeners = [];
         this.providerSettingsListeners = new Set();
+        /**
+         * True when this session's project trust came only from its Full access preset (never asked, never
+         * saved): leaving Full access withdraws it, and going back restores it (senpi#3414, #3420).
+         */
+        this.trustFromFullAccess = false;
+        /** Counts project-trust changes; a reload compares it before installing what it loaded (#3420). */
+        this.trustEpoch = 0;
         this.storage = storage;
         this.globalSettings = initialGlobal;
         this.projectSettings = initialProject;
@@ -506,7 +513,9 @@ export class SettingsManager {
         if (projectLoad.error) {
             initialErrors.push(toSettingsError("project", projectLoad.error, settingsPaths.project));
         }
-        return new SettingsManager(storage, globalLoad.settings, projectLoad.settings, globalLoad.error, projectLoad.error, initialErrors, projectTrusted, initialSources, settingsPaths);
+        const manager = new SettingsManager(storage, globalLoad.settings, projectLoad.settings, globalLoad.error, projectLoad.error, initialErrors, projectTrusted, initialSources, settingsPaths);
+        manager.trustFromFullAccess = options.trustFromFullAccess === true;
+        return manager;
     }
     /** Create an in-memory SettingsManager (no file I/O) */
     static inMemory(settings = {}, options = {}) {
@@ -734,11 +743,22 @@ export class SettingsManager {
     isProjectTrusted() {
         return this.projectTrusted;
     }
+    isTrustFromFullAccess() {
+        return this.trustFromFullAccess && this.projectTrusted;
+    }
+    /** True when a Full-access-only trust was withdrawn in this session and Full access may restore it. */
+    canRestoreFullAccessTrust() {
+        return this.trustFromFullAccess && !this.projectTrusted;
+    }
+    getTrustEpoch() {
+        return this.trustEpoch;
+    }
     setProjectTrusted(trusted) {
         if (this.projectTrusted === trusted) {
             return;
         }
         this.projectTrusted = trusted;
+        this.trustEpoch += 1;
         this.modifiedProjectFields.clear();
         this.modifiedProjectNestedFields.clear();
         if (!trusted) {

package/dist/core/skills-prompt.d.ts

@@ -0,0 +1,18 @@
+import type { ResourceDiagnostic } from "./diagnostics.ts";
+import type { Skill } from "./skills.ts";
+export declare const COMPACT_SKILL_CATALOG_COUNT = 100;
+export declare const COMPACT_SKILL_CATALOG_DESCRIPTION_BYTES: number;
+export declare const MAX_SKILL_CATALOG_BYTES: number;
+/** A catalog this large is listed by name plus a one-line description, since it rides on every request. */
+export declare function isLargeSkillCatalog(skills: readonly Skill[]): boolean;
+export declare function warnIfLargeSkillCatalog(skills: readonly Skill[]): ResourceDiagnostic[];
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via /skill:name commands).
+ */
+export declare function formatSkillsForPrompt(skills: Skill[], fileReadTool?: "read" | "bash"): string;
+//# sourceMappingURL=skills-prompt.d.ts.map

package/dist/core/skills-prompt.js

@@ -0,0 +1,131 @@
+export const COMPACT_SKILL_CATALOG_COUNT = 100;
+export const COMPACT_SKILL_CATALOG_DESCRIPTION_BYTES = 64 * 1024;
+export const MAX_SKILL_CATALOG_BYTES = 48 * 1024;
+const ONE_LINE_DESCRIPTION_MAX_CHARS = 160;
+/** A catalog this large is listed by name plus a one-line description, since it rides on every request. */
+export function isLargeSkillCatalog(skills) {
+    if (skills.length > COMPACT_SKILL_CATALOG_COUNT)
+        return true;
+    const bytes = skills.reduce((sum, skill) => sum + Buffer.byteLength(skill.description, "utf8"), 0);
+    return bytes > COMPACT_SKILL_CATALOG_DESCRIPTION_BYTES;
+}
+export function warnIfLargeSkillCatalog(skills) {
+    const catalog = buildSkillCatalog(skills, "read");
+    if (!catalog.compact && !catalog.namesOnly)
+        return [];
+    return [
+        {
+            type: "warning",
+            category: "size-limit",
+            message: catalog.namesOnly
+                ? `The skills section is limited to ${MAX_SKILL_CATALOG_BYTES / 1024} KiB: descriptions were dropped and ${catalog.omitted} skills were omitted. Remove unused skills to shrink every request.`
+                : `The skills catalog uses one-line descriptions to limit request size (above ${COMPACT_SKILL_CATALOG_COUNT} skills, ${COMPACT_SKILL_CATALOG_DESCRIPTION_BYTES / 1024} KiB of descriptions, or ${MAX_SKILL_CATALOG_BYTES / 1024} KiB rendered). Remove unused skills to shrink every request.`,
+        },
+    ];
+}
+function buildSkillCatalog(skills, fileReadTool) {
+    const visible = skills.filter((skill) => !skill.disableModelInvocation);
+    const compact = isLargeSkillCatalog(visible);
+    const options = { fileReadTool, compact, namesOnly: false, omitted: 0 };
+    const prompt = renderSkills(visible, options);
+    if (Buffer.byteLength(prompt) <= MAX_SKILL_CATALOG_BYTES)
+        return { prompt, compact, namesOnly: false, omitted: 0 };
+    const compactPrompt = compact ? prompt : renderSkills(visible, { ...options, compact: true });
+    if (Buffer.byteLength(compactPrompt) <= MAX_SKILL_CATALOG_BYTES) {
+        return { prompt: compactPrompt, compact: true, namesOnly: false, omitted: 0 };
+    }
+    const minimal = { ...options, namesOnly: true };
+    const namesPrompt = renderSkills(visible, minimal);
+    if (Buffer.byteLength(namesPrompt) <= MAX_SKILL_CATALOG_BYTES) {
+        return { prompt: namesPrompt, compact, namesOnly: true, omitted: 0 };
+    }
+    let low = 0;
+    let high = visible.length;
+    while (low < high) {
+        const count = Math.ceil((low + high) / 2);
+        const candidate = renderSkills(visible.slice(0, count), { ...minimal, omitted: visible.length - count });
+        if (Buffer.byteLength(candidate) <= MAX_SKILL_CATALOG_BYTES)
+            low = count;
+        else
+            high = count - 1;
+    }
+    const omitted = visible.length - low;
+    return {
+        prompt: renderSkills(visible.slice(0, low), { ...minimal, omitted }),
+        compact,
+        namesOnly: true,
+        omitted,
+    };
+}
+function oneLineDescription(description) {
+    const firstLine = description.trim().split("\n", 1)[0]?.trim() ?? "";
+    return firstLine.length <= ONE_LINE_DESCRIPTION_MAX_CHARS
+        ? firstLine
+        : `${firstLine.slice(0, ONE_LINE_DESCRIPTION_MAX_CHARS - 1).trimEnd()}…`;
+}
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via /skill:name commands).
+ */
+// Skill roots share long absolute prefixes across every skill under them; rendering
+// that prefix per skill bills it once per skill. The roots table pays it once per
+// distinct root and each location becomes a short alias/relative path. A one-line
+// rule tells the model to expand aliases by joining them back to the root.
+// `fileReadTool` lets a bash-only tool set still load skills: the loading rule names
+// the tool the session actually has.
+export function formatSkillsForPrompt(skills, fileReadTool = "read") {
+    return buildSkillCatalog(skills, fileReadTool).prompt;
+}
+function renderSkills(visibleSkills, options) {
+    if (visibleSkills.length === 0 && options.omitted === 0) {
+        return "";
+    }
+    const rootByPath = new Map();
+    for (const skill of visibleSkills) {
+        const dir = skill.filePath.split("/").slice(0, -2).join("/"); // parent of <name>/SKILL.md
+        if (!rootByPath.has(dir))
+            rootByPath.set(dir, `r${rootByPath.size}`);
+    }
+    const lines = [
+        "\n\nThe following skills provide specialized instructions for specific tasks.",
+        options.fileReadTool === "read"
+            ? "Use the read tool to load a skill's file when its description matches the task and its instructions would change the work; keyword overlap or mere availability is not a reason."
+            : "Use bash to load a skill's file when its description matches the task and its instructions would change the work; keyword overlap or mere availability is not a reason.",
+        "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+        "",
+        "<skill_roots>",
+    ];
+    for (const [dir, alias] of rootByPath) {
+        lines.push(`  <${alias}>${escapeXml(dir)}</${alias}>`);
+    }
+    lines.push("</skill_roots>", "A location's `rN/` prefix expands to the matching root above.", "", "<available_skills>");
+    for (const skill of visibleSkills) {
+        const dir = skill.filePath.split("/").slice(0, -2).join("/");
+        const alias = rootByPath.get(dir);
+        const relative = skill.filePath.startsWith(`${dir}/`) ? skill.filePath.slice(dir.length + 1) : skill.filePath;
+        lines.push("  <skill>");
+        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+        if (!options.namesOnly) {
+            lines.push(`    <description>${escapeXml(options.compact ? oneLineDescription(skill.description) : skill.description)}</description>`);
+        }
+        lines.push(`    <location>${escapeXml(`${alias}/${relative}`)}</location>`);
+        lines.push("  </skill>");
+    }
+    if (options.omitted > 0)
+        lines.push(`  <omitted_skills>${options.omitted}</omitted_skills>`);
+    lines.push("</available_skills>");
+    return lines.join("\n");
+}
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+//# sourceMappingURL=skills-prompt.js.map

package/dist/core/skills.d.ts

@@ -1,5 +1,6 @@
 import type { ResourceDiagnostic } from "./diagnostics.ts";
 import { type SourceInfo } from "./source-info.ts";
+export { formatSkillsForPrompt } from "./skills-prompt.ts";
 export interface SkillFrontmatter {
     name?: string;
     description?: string;
@@ -39,15 +40,6 @@ export interface LoadSkillsFromDirOptions {
  * - recurse into subdirectories to find SKILL.md
  */
 export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult;
-/**
- * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
- *
- * Skills with disableModelInvocation=true are excluded from the prompt
- * (they can only be invoked explicitly via /skill:name commands).
- */
-export declare function formatSkillsForPrompt(skills: Skill[], fileReadTool?: "read" | "bash"): string;
 export interface LoadSkillsOptions {
     /** Working directory for project-local skills. */
     cwd: string;

package/dist/core/skills.js

@@ -6,6 +6,7 @@ import { parseFrontmatter } from "../utils/frontmatter.js";
 import { canonicalizePath, resolvePath } from "../utils/paths.js";
 import { readSkillMarkdownSource, shouldSkipSkillWalkDirectoryName } from "./skill-discovery.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
+export { formatSkillsForPrompt } from "./skills-prompt.js";
 /** Max name length per spec */
 const MAX_NAME_LENGTH = 64;
 /** Max description length per spec */
@@ -266,65 +267,6 @@ function loadSkillFromFile(filePath, source) {
         diagnostics,
     };
 }
-/**
- * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
- *
- * Skills with disableModelInvocation=true are excluded from the prompt
- * (they can only be invoked explicitly via /skill:name commands).
- */
-// Skill roots share long absolute prefixes across every skill under them; rendering
-// that prefix per skill bills it once per skill. The roots table pays it once per
-// distinct root and each location becomes a short alias/relative path. A one-line
-// rule tells the model to expand aliases by joining them back to the root.
-// `fileReadTool` lets a bash-only tool set still load skills: the loading rule names
-// the tool the session actually has.
-export function formatSkillsForPrompt(skills, fileReadTool = "read") {
-    const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
-    if (visibleSkills.length === 0) {
-        return "";
-    }
-    const rootByPath = new Map();
-    for (const skill of visibleSkills) {
-        const dir = skill.filePath.split("/").slice(0, -2).join("/"); // parent of <name>/SKILL.md
-        if (!rootByPath.has(dir))
-            rootByPath.set(dir, `r${rootByPath.size}`);
-    }
-    const lines = [
-        "\n\nThe following skills provide specialized instructions for specific tasks.",
-        fileReadTool === "read"
-            ? "Use the read tool to load a skill's file when its description matches the task and its instructions would change the work; keyword overlap or mere availability is not a reason."
-            : "Use bash to load a skill's file when its description matches the task and its instructions would change the work; keyword overlap or mere availability is not a reason.",
-        "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
-        "",
-        "<skill_roots>",
-    ];
-    for (const [dir, alias] of rootByPath) {
-        lines.push(`  <${alias}>${escapeXml(dir)}</${alias}>`);
-    }
-    lines.push("</skill_roots>", "A location's `rN/` prefix expands to the matching root above.", "", "<available_skills>");
-    for (const skill of visibleSkills) {
-        const dir = skill.filePath.split("/").slice(0, -2).join("/");
-        const alias = rootByPath.get(dir);
-        const relative = skill.filePath.startsWith(`${dir}/`) ? skill.filePath.slice(dir.length + 1) : skill.filePath;
-        lines.push("  <skill>");
-        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
-        lines.push(`    <description>${escapeXml(skill.description)}</description>`);
-        lines.push(`    <location>${escapeXml(`${alias}/${relative}`)}</location>`);
-        lines.push("  </skill>");
-    }
-    lines.push("</available_skills>");
-    return lines.join("\n");
-}
-function escapeXml(str) {
-    return str
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&apos;");
-}
 /**
  * Load skills from all configured locations.
  * Returns skills and any validation diagnostics.

package/dist/core/trust-manager.d.ts

@@ -17,13 +17,22 @@ export declare function getProjectTrustParentPath(cwd: string): string | undefin
 export declare function getProjectTrustOptions(cwd: string, options?: {
     includeSessionOnly?: boolean;
 }): ProjectTrustOption[];
+/**
+ * The project `.agents/skills` directories for `cwd`, nearest first: one per folder from cwd up to
+ * the git root (or the filesystem root), stopping below the user's home. Home and every folder
+ * above it are never a project; `~/.agents/skills` is the user's own global skills. The ONE walk
+ * both the trust check and the loader use, over the same spelling and the same git root (#3420
+ * review): paths stay as spelled (resources are compared as strings), and each folder's real path
+ * decides whether it is home or above, so a symlink can't carry the walk past home either way.
+ */
+export declare function projectAgentsSkillDirs(cwd: string): string[];
 /**
  * Returns true when cwd has project-local resources that must be gated by
  * project trust: trust-requiring entries under the project config dir or the
- * legacy cwd/.pi dir (whose resources are also discovered), or .agents/skills in
- * cwd or one of its ancestors. Returns false when no such project resources
- * exist. The user/global ~/.agents/skills directory is always treated as a
- * trusted user resource and is ignored here, even when cwd is $HOME.
+ * legacy cwd/.pi dir (whose resources are also discovered), or a project
+ * `.agents/skills` (`projectAgentsSkillDirs`, the same walk the loader uses).
+ * The user's home and every folder above it are never a project: their config
+ * dirs and .agents/skills are the user's own global resources (#2465).
  */
 export declare function hasTrustRequiringProjectResources(cwd: string): boolean;
 export declare class ProjectTrustStore {