@wrongstack/core 0.296.4 → 0.298.0

package/dist/security/permission-policy.d.ts

@@ -3,9 +3,35 @@ import type { InputReader } from '../types/input-reader.js';
 import type { PermissionDecision, PermissionPolicy, PermissionTrace } from '../types/permission.js';
 import type { Tool } from '../types/tool.js';
 import { type TrustPolicyDiagnostic } from './permission-policy-schema.js';
+/**
+ * Reason a persistent "always allow" cannot be recorded for this call, or
+ * `undefined` when it can (WS-046).
+ *
+ * A stored trust pattern is only ever consulted as
+ * `entry.allow && subject && matchesTrust(entry.allow, subject)`. When the tool
+ * produces no subject, that condition can never be true — so `trust()` with the
+ * fallback `pattern: tool.name` writes an entry that is dead on arrival.
+ *
+ * The user experience of that bug is the damaging part. They pick "always
+ * allow", are asked again on the very next identical call, conclude the feature
+ * is broken, and reach for the one thing that does work: a blanket
+ * `{"exec": {"auto": true}}`. A silent no-op does not just fail to help — it
+ * actively trains people into the widest possible grant.
+ *
+ * So the option is refused with a stated reason instead of accepted and
+ * discarded. Exported so a UI can hide the choice rather than offer one that
+ * cannot be honoured.
+ */
+export declare function alwaysAllowUnavailableReason(tool: Tool, input: unknown): string | undefined;
 export interface PermissionPolicyOptions {
     trustFile: string;
     yolo?: boolean | undefined;
+    /**
+     * Let YOLO auto-approve destructive shell commands too. Off by default: with
+     * YOLO on, `rm -rf`, git history rewrites and external publishes still ask
+     * (WS-008).
+     */
+    yoloDestructive?: boolean | undefined;
     promptDelegate?: (tool: Tool, input: unknown, suggestedPattern: string) => Promise<'yes' | 'no' | 'always' | 'deny'>;
     inputReader?: InputReader | undefined;
 }
@@ -45,9 +71,13 @@ export declare class DefaultPermissionPolicy implements PermissionPolicy {
     /** Pre-compiled wildcard patterns — rebuilt on reload for O(1) lookup. */
     private wildcardEntries;
     /**
-     * Evaluate-result cache. Keyed by `tool.name::subject` so repeated calls
-     * with the same tool+input skip namespace matching, subject computation,
-     * and pattern matching (matchAny).
+     * Evaluate-result cache. Keyed by `tool.name::subject::permissionFingerprint`
+     * so repeated calls with the same tool+input skip namespace matching,
+     * subject computation, and pattern matching (matchAny). The fingerprint
+     * suffix covers the `Tool` fields `evaluate()` reads (`permission`,
+     * `riskTier`, `mutating`, `capabilities`), so a tool redefined via
+     * `ToolRegistry.wrap()` misses the cache instead of inheriting a stale
+     * verdict.
      *
      * Cleared on any state change (reload, trust, deny, yolo toggle) because
      * the result depends on the full policy state. The write-tool smart-bypass
@@ -63,7 +93,29 @@ export declare class DefaultPermissionPolicy implements PermissionPolicy {
     private _evalCache;
     private policyDiagnostics;
     private policyInvalid;
+    /**
+     * When true, YOLO also auto-approves clearly destructive shell commands.
+     *
+     * WS-008: `isClearlyDestructiveBashCommand` was exported and heavily tested
+     * but called from zero production modules, so YOLO returned `auto` for
+     * everything — including `rm -rf`, git history rewrites, and external
+     * publishes. The `'yolo_destructive'` decision source, the getter/setter on
+     * PermissionPolicy, and the TUI branch that reads it all existed; only the
+     * gate itself was missing. Defaults to false: destructive commands still ask,
+     * even in YOLO.
+     */
+    private yoloDestructive;
     constructor(opts: PermissionPolicyOptions);
+    /** Allow YOLO to cover destructive shell commands too (off by default). */
+    setYoloDestructive(enabled: boolean): void;
+    /** Whether YOLO currently extends to destructive shell commands. */
+    getYoloDestructive(): boolean;
+    /**
+     * True when YOLO is on but this specific call is a destructive shell command
+     * the user has not opted to auto-approve. Shared by `evaluate()` and the
+     * explain/trace path so the two cannot drift.
+     */
+    private yoloBlockedAsDestructive;
     /**
      * Replace (or clear) the interactive prompt delegate at runtime.
      * Used by the CLI to switch from inline prompts (REPL) to event-driven

package/dist/security/secret-vault.d.ts

@@ -24,6 +24,14 @@ export declare class DefaultSecretVault implements RotatableSecretVault {
     private readonly logger;
     private key?;
     private _keyVersion;
+    /**
+     * Pending key-file hardening promises (Windows ACL restrictions via icacls).
+     * Tracked so async callers can `flushHardening()` before returning, ensuring
+     * a short-lived CLI process does not exit before the hardening resolves.
+     * Sync-only callers (encrypt/decrypt lazy-load) leave these pending —
+     * hardening remains best-effort in that case.
+     */
+    private pendingHardening;
     constructor(opts: SecretVaultOptions);
     /**
      * Emit a structured warning. Uses the configured Logger when available;
@@ -31,6 +39,15 @@ export declare class DefaultSecretVault implements RotatableSecretVault {
      * during early boot.
      */
     private logWarn;
+    /**
+     * Schedule best-effort key-file hardening and track the promise so async
+     * callers can await it via `flushHardening()` before returning. Rejections
+     * are swallowed here (the helper already warns on failure) so a rejection
+     * can never become an unhandled one.
+     */
+    private scheduleKeyHardening;
+    /** Flush all pending key-file hardening promises. */
+    flushHardening(): Promise<void>;
     /** Current key version. Starts at 1; incremented by rotateKey(). */
     get keyVersion(): number;
     isEncrypted(value: string): boolean;

package/dist/security/totp.d.ts

@@ -0,0 +1,86 @@
+/**
+ * RFC 6238 TOTP (Time-Based One-Time Password) implementation.
+ *
+ * Zero external dependencies — uses `node:crypto` for HMAC-SHA1 and
+ * implements RFC 4648 base32 encoding/decoding inline.
+ *
+ * Used by the HQ 2FA system to generate and verify authenticator codes.
+ * The TOTP secret is stored vault-encrypted in `auth.json`; this module
+ * deals only with the cryptographic primitives, not persistence.
+ *
+ * @module security/totp
+ */
+/**
+ * RFC 4648 base32 encode (no padding). Used to encode TOTP secrets for
+ * authenticator apps (Google Authenticator, Authy, 1Password, etc.).
+ */
+export declare function base32Encode(buffer: Buffer): string;
+/**
+ * RFC 4648 base32 decode. Tolerates whitespace and lowercase input
+ * (authenticator apps sometimes normalize). Throws on truly invalid chars.
+ */
+export declare function base32Decode(input: string): Buffer;
+/**
+ * Generate a random TOTP secret (20 bytes of entropy → 32 base32 chars).
+ * This is the recommended secret length per RFC 6238 §5.1.
+ */
+export declare function generateTotpSecret(byteLength?: number): string;
+/**
+ * HOTP (RFC 4226) core: compute a single OTP from a counter value.
+ */
+export declare function hotp(secret: Buffer, counter: number, digits?: number): string;
+/**
+ * Compute the TOTP counter for a given timestamp.
+ * T = floor(unixSeconds / stepSeconds)
+ */
+export declare function totpCounter(unixSeconds: number, stepSeconds?: number): number;
+/**
+ * Generate a TOTP code for the current time.
+ *
+ * @param secretBase32 - base32-encoded secret (from `generateTotpSecret`)
+ * @param atMs - epoch milliseconds; defaults to `Date.now()`. Exposed for tests.
+ * @param stepSeconds - time step in seconds; defaults to 30 (RFC 6238 default).
+ * @param digits - number of digits in the code; defaults to 6.
+ */
+export declare function generateTotp(secretBase32: string, atMs?: number, stepSeconds?: number, digits?: number): string;
+/**
+ * Verify a TOTP code with a ±window tolerance. Uses constant-time string
+ * comparison on each attempt.
+ *
+ * @param code - the code entered by the user
+ * @param secretBase32 - base32-encoded secret
+ * @param atMs - epoch milliseconds; defaults to `Date.now()`
+ * @param window - number of steps before/after the current step to accept.
+ *   0 = exact step only; 1 = ±30s (default); 2 = ±60s.
+ * @returns `true` if the code matches any step within the window.
+ */
+export declare function verifyTotp(code: string, secretBase32: string, atMs?: number, window?: number, stepSeconds?: number, digits?: number): boolean;
+/**
+ * Build an `otpauth://` URI for QR-code provisioning (RFC 6238 / Google Auth).
+ *
+ * Format: `otpauth://totp/<label>?secret=<base32>&issuer=<issuer>&algorithm=SHA1&digits=6&period=30`
+ *
+ * The URI is used to render a QR code in the settings page. Authenticator
+ * apps scan it and store the secret.
+ */
+export declare function buildOtpAuthUri(secretBase32: string, account: string, issuer?: string, stepSeconds?: number, digits?: number): string;
+/**
+ * Generate a batch of single-use recovery codes. Each code is a 16-char
+ * hex string with a hyphen separator in the middle for readability.
+ *
+ * Format: `xxxxxxxx-xxxxxxxx` (8 hex chars, hyphen, 8 hex chars)
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+/**
+ * Hash a recovery code with SHA-256 for storage. Recovery codes are
+ * single-use; storing only the hash means a leaked `auth.json` cannot
+ * reveal unused codes.
+ */
+export declare function hashRecoveryCode(code: string): string;
+/**
+ * Constant-time comparison of a recovery code against a list of stored
+ * SHA-256 hashes. Returns `true` on match. Callers MUST remove the matched
+ * hash from the store after a successful verification (single-use).
+ */
+export declare function verifyRecoveryCode(code: string, storedHashes: string[]): boolean;
+//# sourceMappingURL=totp.d.ts.map

package/dist/skills/frontmatter.d.ts

@@ -10,12 +10,23 @@
 export interface ParsedSkillFrontmatter {
     name?: string | undefined;
     description?: string | undefined;
+    /**
+     * Optional explicit "Use when…" trigger (WrongStack extension). When present
+     * it is used verbatim as the skill's trigger in the available-skills list;
+     * otherwise the trigger falls back to the first sentence of `description`.
+     */
+    trigger?: string | undefined;
     /** WrongStack extension; informational only. */
     version?: string | undefined;
     license?: string | undefined;
     compatibility?: string | undefined;
     metadata?: Record<string, string> | undefined;
-    /** `allowed-tools` (spec, experimental) → split on whitespace. */
+    /**
+     * `allowed-tools` (agentskills.io spec, experimental) → split on whitespace.
+     * INFORMATIONAL ONLY: WrongStack parses and can surface this list but does NOT
+     * enforce it — the `skill` tool's permissions/capabilities are fixed and never
+     * consult this field, so it neither grants nor restricts any tool.
+     */
     allowedTools?: string[] | undefined;
 }
 /**

package/dist/skills/github-fetcher.d.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'node:stream';
 export interface ParsedRef {
     owner: string;
     repo: string;
@@ -12,6 +13,8 @@ export interface DownloadResult {
     /** Temp directory containing the extracted repo. Caller must clean up. */
     tempDir: string;
 }
+/** Stream a gzip payload to disk while enforcing its decompressed byte budget. */
+export declare function writeBoundedGzipStream(source: Readable, outputPath: string, maxBytes: number, maxCompressedBytes?: number): Promise<number>;
 /**
  * Resolve a GitHub auth token, if one is configured.
  *
@@ -35,4 +38,49 @@ export declare function resolveGitHubToken(env?: NodeJS.ProcessEnv): string | un
  * must remove it (the installer does this in a `finally`).
  */
 export declare function downloadGitHubTarball(parsed: ParsedRef): Promise<DownloadResult>;
+/**
+ * Read a tar header's 12-byte size field (WS-056).
+ */
+declare function readTarSize(buf: Buffer, start: number): number;
+/**
+ * Minimal POSIX tar extractor. Handles the ustar format produced by GitHub.
+ * Only extracts regular files and directories — symlinks and special entries
+ * are skipped for security.
+ */
+declare function extractTar(buf: Buffer, destDir: string): Promise<void>;
+/**
+ * Read a tar header's 12-byte size field (WS-056).
+ *
+ * This was `parseInt(readTarString(...), 8) || 0`, which is wrong in a way
+ * that matters more than a wrong number.
+ *
+ * GNU tar encodes a size that does not fit 11 octal digits in "base-256":
+ * the high bit of the first byte is set and the remaining bytes are a
+ * big-endian binary integer. Read as an octal STRING that is binary garbage,
+ * so `parseInt` returned `NaN` and `|| 0` quietly turned it into a size of 0.
+ *
+ * A size of 0 does not merely mis-report the entry — it DESYNCHRONISES the
+ * parser. The loop advances by `512 + ceil(size / 512) * 512`, so a zero size
+ * advances one block and the entry's own DATA is then parsed as the next tar
+ * header. From that point every "entry" is attacker-chosen content that was
+ * never visible as a file, and the extractor writes whatever those synthetic
+ * headers name. The zip-slip guard still holds, so this is not a path out of
+ * `destDir` — but it is arbitrary file creation inside it from data no
+ * inspection of the archive's real entry list would show.
+ *
+ * So: parse base-256 properly, and treat a size that is neither valid octal
+ * nor valid base-256 as fatal. Continuing from an unknown size is exactly the
+ * desync; refusing to extract is the only safe response.
+ */
+/**
+ * Internal seam for the per-file coverage suite (mirrors
+ * `protocolHandlerCoverage` in the ACP handler). `extractTar` and
+ * `readTarSize` are the security-relevant halves of this module and are
+ * otherwise unreachable from a test without performing a real download.
+ */
+export declare const githubFetcherCoverage: {
+    extractTar: typeof extractTar;
+    readTarSize: typeof readTarSize;
+};
+export {};
 //# sourceMappingURL=github-fetcher.d.ts.map

package/dist/skills/index.js

@@ -40,7 +40,7 @@ function securityScoreToTier(score) {
 }
 
 // src/skills/frontmatter.ts
-var SCALAR_KEYS = /* @__PURE__ */ new Set(["name", "description", "version", "license", "compatibility"]);
+var SCALAR_KEYS = /* @__PURE__ */ new Set(["name", "description", "trigger", "version", "license", "compatibility"]);
 function parseSkillFrontmatter(raw) {
   const text = normalizeLineEndings(raw);
   if (!text.startsWith("---")) return {};
@@ -144,6 +144,7 @@ function validateSkillName(name, parentDirName) {
 }
 
 // src/skills/github-fetcher.ts
+import { createWriteStream } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -341,6 +342,14 @@ var SKILL_LIMITS = {
    * Consumer: `downloadGitHubTarball`.
    */
   MAX_TARBALL_SIZE: 50 * 1024 * 1024,
+  /**
+   * Maximum size of a GitHub skill tarball after gzip decompression. The
+   * compressed download limit alone does not protect against highly
+   * compressible archives expanding until the process runs out of memory.
+   *
+   * Consumer: `downloadGitHubTarball`.
+   */
+  MAX_UNCOMPRESSED_TARBALL_SIZE: 64 * 1024 * 1024,
   /**
    * Default total char budget for skill bodies injected in eager mode when
    * `config.skills.eagerMaxChars` is unset. ~6k tokens. Skills are injected
@@ -352,6 +361,17 @@ var SKILL_LIMITS = {
    * `skillEagerMaxChars`).
    */
   EAGER_DEFAULT_MAX_CHARS: 24e3,
+  /**
+   * Default total char budget for compact (token-saving) skill bodies injected
+   * by `buildCompactSkillBodiesText`. Mirrors the eager ceiling so compact mode
+   * can never inject more total skill text than eager mode. Before this bound
+   * existed, compact mode injected EVERY skill's compact body with no cap, so
+   * the section grew linearly with the number of installed skills. Skills past
+   * the budget overflow to a name list the agent loads via the `skill` tool.
+   *
+   * Consumer: `buildCompactSkillBodiesText` (default for its `budget` param).
+   */
+  COMPACT_DEFAULT_MAX_CHARS: 24e3,
   /**
    * Auto-compact body limits (the token-saving fallback used when a skill has
    * no hand-crafted `SKILL.save.md`). The Overview and Rules sections are
@@ -404,6 +424,46 @@ function parseSkillRef(input) {
   }
   return { owner: expectDefined(parts[0]), repo: expectDefined(parts[1]), ref };
 }
+async function writeBoundedGzipStream(source, outputPath, maxBytes, maxCompressedBytes = SKILL_LIMITS.MAX_TARBALL_SIZE) {
+  let compressedBytes = 0;
+  let writtenBytes = 0;
+  await pipeline(
+    source,
+    async function* (chunks) {
+      for await (const chunk of chunks) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        compressedBytes += buffer.byteLength;
+        if (compressedBytes > maxCompressedBytes) {
+          throw new WrongStackError({
+            message: `Compressed tarball too large. Max: ${maxCompressedBytes / 1024 / 1024}MB`,
+            code: ERROR_CODES.UNKNOWN,
+            subsystem: "general",
+            context: { compressedBytes, maxBytes: maxCompressedBytes }
+          });
+        }
+        yield buffer;
+      }
+    },
+    createGunzip(),
+    async function* (chunks) {
+      for await (const chunk of chunks) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        writtenBytes += buffer.byteLength;
+        if (writtenBytes > maxBytes) {
+          throw new WrongStackError({
+            message: `Uncompressed tarball too large. Max: ${maxBytes / 1024 / 1024}MB`,
+            code: ERROR_CODES.UNKNOWN,
+            subsystem: "general",
+            context: { uncompressedBytes: writtenBytes, maxBytes }
+          });
+        }
+        yield buffer;
+      }
+    },
+    createWriteStream(outputPath, { flags: "wx" })
+  );
+  return writtenBytes;
+}
 function resolveGitHubToken(env = process.env) {
   const raw = env["WRONGSTACK_GITHUB_TOKEN"] ?? env["GITHUB_TOKEN"] ?? env["GH_TOKEN"];
   if (!raw) return void 0;
@@ -490,15 +550,14 @@ async function downloadGitHubTarball(parsed) {
       });
     }
     const nodeStream = Readable.fromWeb(response.body);
-    const gunzip = createGunzip();
-    const chunks = [];
-    await pipeline(nodeStream, gunzip, async (source) => {
-      for await (const chunk of source) {
-        chunks.push(Buffer.from(chunk));
-      }
-    });
-    const tarBuf = Buffer.concat(chunks);
-    await extractTar(tarBuf, tempDir);
+    const tarPath = path.join(tempDir, ".wrongstack-download.tar");
+    await writeBoundedGzipStream(nodeStream, tarPath, SKILL_LIMITS.MAX_UNCOMPRESSED_TARBALL_SIZE);
+    const tarBuf = await fs.readFile(tarPath);
+    try {
+      await extractTar(tarBuf, tempDir);
+    } finally {
+      await fs.rm(tarPath, { force: true });
+    }
     return { tempDir };
   } catch (err) {
     await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {
@@ -506,6 +565,44 @@ async function downloadGitHubTarball(parsed) {
     throw err;
   }
 }
+function readTarSize(buf, start) {
+  const first = buf[start] ?? 0;
+  if ((first & 128) !== 0) {
+    if (first === 255) {
+      throw new Error("tar: negative base-256 size field");
+    }
+    let value = first & 127;
+    for (let i = start + 1; i < start + 12; i++) {
+      value = value * 256 + (buf[i] ?? 0);
+      if (!Number.isSafeInteger(value)) {
+        throw new Error("tar: base-256 size exceeds the safe integer range");
+      }
+    }
+    return value;
+  }
+  const text = readTarString(buf, start, 12).trim();
+  if (text === "") return 0;
+  if (!/^[0-7]+$/.test(text)) {
+    throw new Error(`tar: unparseable size field ${JSON.stringify(text)}`);
+  }
+  const parsed = Number.parseInt(text, 8);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new Error("tar: size field out of range");
+  }
+  return parsed;
+}
+function readTarString(buf, start, maxLen) {
+  let end = start;
+  while (end < start + maxLen && end < buf.length && buf[end] !== 0) {
+    end++;
+  }
+  return buf.subarray(start, end).toString("utf8");
+}
+function stripTopDir(p) {
+  const idx = p.indexOf("/");
+  if (idx === -1) return "";
+  return p.slice(idx + 1);
+}
 async function extractTar(buf, destDir) {
   let offset = 0;
   while (offset + 512 <= buf.length) {
@@ -513,7 +610,7 @@ async function extractTar(buf, destDir) {
     if (header.every((b) => b === 0)) break;
     const name = readTarString(buf, offset, 100);
     const prefix = readTarString(buf, offset + 345, 155);
-    const size = Number.parseInt(readTarString(buf, offset + 124, 12).trim(), 8) || 0;
+    const size = readTarSize(buf, offset + 124);
     const typeflag = buf[offset + 156] ?? 0;
     const fullPath = prefix ? `${prefix}/${name}` : name;
     const relPath = stripTopDir(fullPath);
@@ -542,18 +639,6 @@ async function extractTar(buf, destDir) {
     offset += 512 + Math.ceil(size / 512) * 512;
   }
 }
-function readTarString(buf, start, maxLen) {
-  let end = start;
-  while (end < start + maxLen && end < buf.length && buf[end] !== 0) {
-    end++;
-  }
-  return buf.subarray(start, end).toString("utf8");
-}
-function stripTopDir(p) {
-  const idx = p.indexOf("/");
-  if (idx === -1) return "";
-  return p.slice(idx + 1);
-}
 
 // src/skills/manifest-store.ts
 import * as fs2 from "node:fs/promises";
@@ -968,6 +1053,10 @@ function defaultEditor() {
 // src/skills/skill-installer.ts
 import * as fs4 from "node:fs/promises";
 import * as path4 from "node:path";
+function isInside(resolved, destDir) {
+  const root = path4.resolve(destDir);
+  return resolved === root || resolved.startsWith(root + path4.sep);
+}
 var MAX_SKILL_FILE_SIZE = SKILL_LIMITS.MAX_SKILL_FILE_SIZE;
 var SkillInstaller = class {
   opts;
@@ -1028,7 +1117,7 @@ var SkillInstaller = class {
           const srcPath = path4.join(skill.baseDir, file);
           const destPath = path4.join(destDir, file);
           const resolved2 = path4.resolve(destPath);
-          if (!resolved2.startsWith(path4.resolve(destDir))) {
+          if (!isInside(resolved2, destDir)) {
             throw new FsError({
               message: `Path traversal detected in skill file: ${file}`,
               code: ERROR_CODES.FS_DELETE_FAILED,
@@ -1125,7 +1214,7 @@ var SkillInstaller = class {
         const srcPath = path4.join(srcSkillDir, file);
         const destPath = path4.join(destDir, file);
         const resolved = path4.resolve(destPath);
-        if (!resolved.startsWith(path4.resolve(destDir))) {
+        if (!isInside(resolved, destDir)) {
           throw new FsError({
             message: `Path traversal detected in skill file: ${file}`,
             code: ERROR_CODES.FS_DELETE_FAILED,
@@ -1339,9 +1428,31 @@ var SkillInstaller = class {
   /**
    * Remove all files for an installed skill.
    */
+  /**
+   * Delete an installed skill's directory.
+   *
+   * The containment check is not ceremonial: this is a `recursive: true,
+   * force: true` delete whose target is built from a skill NAME taken from
+   * manifest frontmatter. `path.join` normalises `..`, so a crafted name
+   * escapes `targetDir` and takes the recursive delete with it. This file
+   * already had `isInside` and applied it on the copy path but not here.
+   *
+   * The strict-subdirectory requirement matters separately: `isInside` allows
+   * equality by design, and an empty or `.` name resolves `skillDir` to
+   * `targetDir` itself — deleting every installed skill (WS-097).
+   */
   async removeSkillFiles(name, scope) {
     const targetDir = scope === "project" ? this.opts.projectSkillsDir : this.opts.globalSkillsDir;
-    const skillDir = path4.join(targetDir, name);
+    const root = path4.resolve(targetDir);
+    const skillDir = path4.resolve(path4.join(targetDir, name));
+    if (skillDir === root || !isInside(skillDir, root)) {
+      throw new FsError({
+        message: `Refusing to delete skill files outside the skills directory: ${name}`,
+        code: ERROR_CODES.FS_DELETE_FAILED,
+        path: skillDir,
+        context: { reason: "path_traversal", skillName: name, scope }
+      });
+    }
     await fs4.rm(skillDir, { recursive: true, force: true });
   }
   /**

package/dist/skills/limits.d.ts

@@ -51,6 +51,14 @@ export declare const SKILL_LIMITS: {
      * Consumer: `downloadGitHubTarball`.
      */
     readonly MAX_TARBALL_SIZE: number;
+    /**
+     * Maximum size of a GitHub skill tarball after gzip decompression. The
+     * compressed download limit alone does not protect against highly
+     * compressible archives expanding until the process runs out of memory.
+     *
+     * Consumer: `downloadGitHubTarball`.
+     */
+    readonly MAX_UNCOMPRESSED_TARBALL_SIZE: number;
     /**
      * Default total char budget for skill bodies injected in eager mode when
      * `config.skills.eagerMaxChars` is unset. ~6k tokens. Skills are injected
@@ -62,6 +70,17 @@ export declare const SKILL_LIMITS: {
      * `skillEagerMaxChars`).
      */
     readonly EAGER_DEFAULT_MAX_CHARS: 24000;
+    /**
+     * Default total char budget for compact (token-saving) skill bodies injected
+     * by `buildCompactSkillBodiesText`. Mirrors the eager ceiling so compact mode
+     * can never inject more total skill text than eager mode. Before this bound
+     * existed, compact mode injected EVERY skill's compact body with no cap, so
+     * the section grew linearly with the number of installed skills. Skills past
+     * the budget overflow to a name list the agent loads via the `skill` tool.
+     *
+     * Consumer: `buildCompactSkillBodiesText` (default for its `budget` param).
+     */
+    readonly COMPACT_DEFAULT_MAX_CHARS: 24000;
     /**
      * Auto-compact body limits (the token-saving fallback used when a skill has
      * no hand-crafted `SKILL.save.md`). The Overview and Rules sections are

package/dist/skills/skill-installer.d.ts

@@ -109,6 +109,19 @@ export declare class SkillInstaller {
     /**
      * Remove all files for an installed skill.
      */
+    /**
+     * Delete an installed skill's directory.
+     *
+     * The containment check is not ceremonial: this is a `recursive: true,
+     * force: true` delete whose target is built from a skill NAME taken from
+     * manifest frontmatter. `path.join` normalises `..`, so a crafted name
+     * escapes `targetDir` and takes the recursive delete with it. This file
+     * already had `isInside` and applied it on the copy path but not here.
+     *
+     * The strict-subdirectory requirement matters separately: `isInside` allows
+     * equality by design, and an empty or `.` name resolves `skillDir` to
+     * `targetDir` itself — deleting every installed skill (WS-097).
+     */
     private removeSkillFiles;
     /**
      * Invalidate the skill loader's cache so newly installed skills appear.

package/dist/storage/file-session-writer.d.ts

@@ -39,10 +39,29 @@ export declare class FileSessionWriter implements SessionWriter {
     private lastAppendWarnAt;
     private readonly secretScrubber?;
     private readonly checkpointCas?;
+    /** Mutable slot for onAppend callback — constructor opts seed it, setOnAppend replaces it. */
+    private _onAppend;
+    /** Implements SessionWriter.onAppend — public getter/setter for direct property access. */
+    get onAppend(): ((event: SessionEvent) => void) | undefined;
+    set onAppend(cb: ((event: SessionEvent) => void) | undefined);
+    /** Mutable slot for onAppendBatch callback. */
+    private _onAppendBatch;
+    /** Implements SessionWriter.onAppendBatch — public getter/setter for direct property access. */
+    get onAppendBatch(): ((events: SessionEvent[]) => void) | undefined;
+    set onAppendBatch(cb: ((events: SessionEvent[]) => void) | undefined);
     private readonly onCloseCb?;
     private readonly resolveNameCb?;
     /** Implements SessionWriter.traceId — propagated from ContextInit.traceId. */
     traceId: string | undefined;
+    /**
+     * Set or replace the onAppend callback. Used by telemetry bridges that
+     * receive the writer as an already-constructed dependency.
+     */
+    setOnAppend(cb: ((event: SessionEvent) => void) | undefined): void;
+    /**
+     * Set or replace the onAppendBatch callback.
+     */
+    setOnAppendBatch(cb: ((events: SessionEvent[]) => void) | undefined): void;
     private writeBuffer;
     private writeBufferBytes;
     private flushTimer;
@@ -107,6 +126,10 @@ export declare class FileSessionWriter implements SessionWriter {
         filePath?: string | undefined;
         secretScrubber?: SecretScrubber | undefined;
         checkpointCas?: SessionCheckpointCas | undefined;
+        /** Called synchronously after each event is scrubbed + observed, before it enters the write buffer. */
+        onAppend?: ((event: SessionEvent) => void) | undefined;
+        /** Batch variant called after all events in the batch have been scrubbed + observed. */
+        onAppendBatch?: ((events: SessionEvent[]) => void) | undefined;
         /** Existing cumulative summary when reopening a persisted session. */
         initialSummary?: SessionSummary | undefined;
         /** Called on close() with the finalized summary for index/sidecar writes. */