@wrongstack/core 0.299.0 → 0.301.0

package/dist/security/index.js

@@ -47,6 +47,8 @@ var ToolCapabilities = {
   NET_OUTBOUND: "net.outbound",
   /** Can mutate in-memory session todos only. */
   SESSION_TODO: "session.todo",
+  /** Can park after-task `<nextsteps>` suggestions for the current turn. */
+  SESSION_NEXTSTEPS: "session.nextsteps",
   /** Can mutate in-memory session mode only. */
   SESSION_MODE: "session.mode",
   /** Can inspect registered tool metadata. */
@@ -712,22 +714,22 @@ var UNSAFE_PROPERTY_NAMES = /* @__PURE__ */ new Set(["__proto__", "prototype", "
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function error(diagnostics, code, path6, message) {
-  diagnostics.push({ severity: "error", code, path: path6, message });
+function error(diagnostics, code, path9, message) {
+  diagnostics.push({ severity: "error", code, path: path9, message });
 }
-function validateStringList(value, path6, diagnostics, limits) {
+function validateStringList(value, path9, diagnostics, limits) {
   if (!Array.isArray(value)) {
-    error(diagnostics, limits.listErrorCode, path6, `must be an array of strings`);
+    error(diagnostics, limits.listErrorCode, path9, `must be an array of strings`);
     return void 0;
   }
   if (value.length > limits.maxItems) {
-    error(diagnostics, limits.tooManyCode, path6, `must contain at most ${limits.maxItems} ${limits.itemLabel}s`);
+    error(diagnostics, limits.tooManyCode, path9, `must contain at most ${limits.maxItems} ${limits.itemLabel}s`);
     return void 0;
   }
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const [index, entry] of value.entries()) {
-    const itemPath = `${path6}[${index}]`;
+    const itemPath = `${path9}[${index}]`;
     if (typeof entry !== "string" || entry.length === 0 || entry.length > limits.maxChars) {
       error(
         diagnostics,
@@ -1467,6 +1469,7 @@ function numericValue(value) {
 
 // src/security/permission-policy.ts
 import * as fs from "node:fs/promises";
+import * as path6 from "node:path";
 
 // src/utils/atomic-write.ts
 import {
@@ -1767,19 +1770,19 @@ var UNSAFE_PROPERTY_NAMES2 = /* @__PURE__ */ new Set(["__proto__", "prototype",
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function error2(diagnostics, code, path6, message) {
-  diagnostics.push({ severity: "error", code, path: path6, message });
+function error2(diagnostics, code, path9, message) {
+  diagnostics.push({ severity: "error", code, path: path9, message });
 }
-function validatePatterns(value, path6, diagnostics) {
+function validatePatterns(value, path9, diagnostics) {
   if (!Array.isArray(value)) {
-    error2(diagnostics, "invalid_pattern_list", path6, "must be an array of strings");
+    error2(diagnostics, "invalid_pattern_list", path9, "must be an array of strings");
     return void 0;
   }
   if (value.length > TRUST_POLICY_LIMITS.maxPatternsPerRule) {
     error2(
       diagnostics,
       "too_many_patterns",
-      path6,
+      path9,
       `must contain at most ${TRUST_POLICY_LIMITS.maxPatternsPerRule} patterns`
     );
     return void 0;
@@ -1787,7 +1790,7 @@ function validatePatterns(value, path6, diagnostics) {
   const patterns = [];
   const seen = /* @__PURE__ */ new Set();
   for (const [index, pattern] of value.entries()) {
-    const itemPath = `${path6}[${index}]`;
+    const itemPath = `${path9}[${index}]`;
     if (typeof pattern !== "string" || pattern.length === 0 || pattern.length > TRUST_POLICY_LIMITS.maxPatternChars) {
       error2(
         diagnostics,
@@ -2201,6 +2204,19 @@ var AutoApprovePermissionPolicy = class _AutoApprovePermissionPolicy {
   }
 };
 
+// src/security/permission-helpers.ts
+import { realpathSync } from "node:fs";
+import * as path5 from "node:path";
+
+// src/utils/wstack-paths.ts
+import * as os from "node:os";
+import * as path4 from "node:path";
+function wstackGlobalRoot() {
+  const fromEnv = process.env["WRONGSTACK_HOME"];
+  if (fromEnv && fromEnv.trim().length > 0) return path4.resolve(fromEnv);
+  return path4.join(os.homedir(), ".wrongstack");
+}
+
 // src/security/permission-helpers.ts
 function matchesTrust(patterns, subject) {
   return patterns.includes(subject) || matchAny(patterns, subject);
@@ -2272,9 +2288,51 @@ var SHELL_READ_VERBS = /* @__PURE__ */ new Set([
 function stripShellQuotes(value) {
   return value.replace(/^['"]|['"]$/g, "");
 }
+var AGENT_STATE_SENSITIVE_BASENAMES = /^(?:config\.json|config\.local\.json|trust\.json|auth\.json|\.key)$/i;
+function unescapeGlobSubject(value) {
+  return value.replace(/\\([*?[\]])/g, "$1");
+}
+function normalizeForCompare(value) {
+  const forward = unescapeGlobSubject(value).replace(/\\/g, "/").replace(/\/+$/, "");
+  return process.platform === "win32" ? forward.toLowerCase() : forward;
+}
+function realpathOfNearestExisting(p) {
+  let probe = p;
+  const tail = [];
+  for (; ; ) {
+    try {
+      return tail.length === 0 ? realpathSync(probe) : path5.join(realpathSync(probe), ...tail);
+    } catch {
+      const parent = path5.dirname(probe);
+      if (parent === probe) return p;
+      tail.unshift(path5.basename(probe));
+      probe = parent;
+    }
+  }
+}
+var agentStateRootRealCache = /* @__PURE__ */ new Map();
+function isInsideAgentStateRoot(absPath) {
+  const lexicalRoot = normalizeForCompare(path5.resolve(wstackGlobalRoot()));
+  if (!lexicalRoot) return false;
+  const target = normalizeForCompare(absPath);
+  if (target === lexicalRoot || target.startsWith(`${lexicalRoot}/`)) return true;
+  let realRoot = agentStateRootRealCache.get(lexicalRoot);
+  if (realRoot === void 0) {
+    realRoot = normalizeForCompare(realpathOfNearestExisting(path5.resolve(wstackGlobalRoot())));
+    agentStateRootRealCache.set(lexicalRoot, realRoot);
+  }
+  if (!realRoot || realRoot === lexicalRoot) return false;
+  const realTarget = normalizeForCompare(realpathOfNearestExisting(absPath));
+  return realTarget === realRoot || realTarget.startsWith(`${realRoot}/`);
+}
+function isProtectedAgentStatePath(absPath) {
+  if (!isInsideAgentStateRoot(absPath)) return false;
+  return AGENT_STATE_SENSITIVE_BASENAMES.test(path5.basename(normalizeForCompare(absPath)));
+}
 function pathLooksSensitive(rawPath) {
   const normalized = stripShellQuotes(rawPath).replace(/\\/g, "/");
-  return SENSITIVE_READ_PATHS.some((pattern) => pattern.test(normalized));
+  if (SENSITIVE_READ_PATHS.some((pattern) => pattern.test(normalized))) return true;
+  return isProtectedAgentStatePath(normalized);
 }
 function inputPathLooksSensitive(input) {
   if (!input || typeof input !== "object") return false;
@@ -2298,6 +2356,34 @@ function shellCommandReadsSensitivePath(command) {
 }
 
 // src/security/permission-policy.ts
+function fsWriteTargetPaths(input) {
+  const out = [];
+  if (!input || typeof input !== "object") return out;
+  const obj = input;
+  for (const key of [
+    "path",
+    "file_path",
+    "file",
+    "filePath",
+    "files",
+    "target",
+    "targetPath",
+    "out",
+    "directory",
+    "cwd",
+    "template"
+  ]) {
+    const value = obj[key];
+    if (typeof value === "string") {
+      if (value.length > 0) out.push(value);
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === "string" && item.length > 0) out.push(item);
+      }
+    }
+  }
+  return out;
+}
 var DefaultPermissionPolicy = class {
   policy = {};
   loaded = false;
@@ -2383,6 +2469,30 @@ var DefaultPermissionPolicy = class {
   getYoloDestructive() {
     return this.yoloDestructive;
   }
+  /**
+   * True when this call is an FS_WRITE whose target lands inside WrongStack's
+   * own state root.
+   *
+   * FS_WRITE tools disagree on where the target path lives: write/edit use
+   * `path`, replace/format/git `files` (string OR array), patch `directory`,
+   * design `out`, scaffold writes under `cwd`/`template`. Checking only
+   * `path`/`file_path` let a state-root write merely switch tools, so every
+   * path-bearing key is inspected.
+   *
+   * Shared by the YOLO carve-out and the eval-cache guard so the two cannot
+   * drift: the carve-out scans all path keys while the cache key fingerprints
+   * only the subject key, so the cache must consult the same predicate or a
+   * secondary state-root key can be replayed a cached `auto`.
+   */
+  hasAgentStateWriteTarget(tool, input, ctx) {
+    if (!hasCapability(tool, ToolCapabilities.FS_WRITE)) return false;
+    for (const targetPath of fsWriteTargetPaths(input)) {
+      const base = ctx.workingDir ?? ctx.cwd;
+      const resolved = base ? path6.resolve(base, targetPath) : path6.resolve(targetPath);
+      if (isInsideAgentStateRoot(resolved)) return true;
+    }
+    return false;
+  }
   /**
    * 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
@@ -2390,6 +2500,7 @@ var DefaultPermissionPolicy = class {
    */
   yoloBlockedAsDestructive(tool, input, ctx) {
     if (!this.yolo || this.yoloDestructive) return false;
+    if (this.hasAgentStateWriteTarget(tool, input, ctx)) return true;
     const isShellSurface = tool.name === "bash" || tool.name === "exec" || (tool.capabilities ?? []).includes("shell.arbitrary");
     if (!isShellSurface) return false;
     const command = getInputString(input, "command") ?? shellCommandLineFromInput(input);
@@ -2496,7 +2607,7 @@ var DefaultPermissionPolicy = class {
     const subject = subjectForToolInput(tool.name, input, tool.subjectKey);
     const cacheKey = `${tool.name}::${subject ?? tool.name}`;
     const evalKey = `${cacheKey}::${permissionFingerprint(tool)}`;
-    if (tool.name !== "write") {
+    if (tool.name !== "write" && !this.hasAgentStateWriteTarget(tool, input, ctx)) {
       const cached = this._evalCache.get(evalKey);
       if (cached !== void 0) return cached;
     }
@@ -2604,7 +2715,7 @@ var DefaultPermissionPolicy = class {
       return decision;
     }
     if (tool.name === "write" && subject) {
-      if (ctx.hasRead(subject)) {
+      if (ctx.hasRead(subject) && !isInsideAgentStateRoot(subject)) {
         return {
           permission: "auto",
           source: "context",
@@ -2954,13 +3065,14 @@ var DefaultPermissionPolicy = class {
     }
     add("yolo", false, "auto", "yolo", "YOLO mode is not active");
     if (tool.name === "write" && subject) {
-      const hasRead = ctx.hasRead(subject);
+      const isAgentState = isInsideAgentStateRoot(subject);
+      const hasRead = ctx.hasRead(subject) && !isAgentState;
       add(
         "write smart bypass",
         hasRead,
         "auto",
         "context",
-        hasRead ? `file "${subject}" was already read in this session \u2014 auto-approving write` : `file "${subject}" was not read in this session \u2014 bypass does not apply`
+        isAgentState ? `file "${subject}" is WrongStack's own state \u2014 bypass never applies, write always confirms` : hasRead ? `file "${subject}" was already read in this session \u2014 auto-approving write` : `file "${subject}" was not read in this session \u2014 bypass does not apply`
       );
       if (hasRead) {
         winnerIndex = steps.length - 1;
@@ -3042,7 +3154,7 @@ var DefaultPermissionPolicy = class {
 };
 
 // src/security/readonly-permission-policy.ts
-import * as path4 from "node:path";
+import * as path7 from "node:path";
 var MUTATION_CAPABILITIES = /* @__PURE__ */ new Set([
   ToolCapabilities.FS_WRITE,
   ToolCapabilities.FS_WRITE_OUTSIDE_PROJECT,
@@ -3056,9 +3168,11 @@ var MUTATION_CAPABILITIES = /* @__PURE__ */ new Set([
   ToolCapabilities.PACKAGE_INSTALL,
   ToolCapabilities.SUBAGENT_SPAWN
 ]);
-function hasMutationCapability(tool) {
+function toolMutates(tool) {
+  if (tool.mutating === true) return true;
   return (tool.capabilities ?? []).some((c) => MUTATION_CAPABILITIES.has(c));
 }
+var hasMutationCapability = toolMutates;
 function isAllowedReportFile(input, projectRoot) {
   if (!input || typeof input !== "object") return false;
   const record = input;
@@ -3066,9 +3180,9 @@ function isAllowedReportFile(input, projectRoot) {
   if (typeof inputPath !== "string") return false;
   if (!inputPath.endsWith(".md")) return false;
   try {
-    const resolved = path4.resolve(projectRoot, inputPath);
-    const tempDir = path4.resolve(projectRoot, ".temp_files");
-    if (!resolved.startsWith(tempDir + path4.sep) && resolved !== tempDir) return false;
+    const resolved = path7.resolve(projectRoot, inputPath);
+    const tempDir = path7.resolve(projectRoot, ".temp_files");
+    if (!resolved.startsWith(tempDir + path7.sep) && resolved !== tempDir) return false;
     return true;
   } catch {
     return false;
@@ -3091,10 +3205,12 @@ var ReadOnlyPermissionPolicy = class {
     if (isAllowedReportFile(input, this.projectRoot)) {
       return this.inner.evaluate(tool, input, ctx);
     }
+    const matched = (tool.capabilities ?? []).filter((c) => MUTATION_CAPABILITIES.has(c));
+    const why = matched.length > 0 ? `requires mutation capabilities (${matched.join(", ")})` : "is declared mutating";
     return {
       permission: "deny",
       source: "readonly_mode",
-      reason: `Session is in read-only mode: tool "${tool.name}" requires mutation capabilities (${(tool.capabilities ?? []).filter((c) => MUTATION_CAPABILITIES.has(c)).join(", ")}) which are not allowed. Only .md report files under .temp_files/ may be written.`
+      reason: `Session is in read-only mode: tool "${tool.name}" ${why}, which is not allowed. Only .md report files under .temp_files/ may be written.`
     };
   }
   async trust(rule) {
@@ -3217,16 +3333,20 @@ function generateTotp(secretBase32, atMs = Date.now(), stepSeconds = DEFAULT_STE
   return hotp(secret, counter, digits);
 }
 function verifyTotp(code, secretBase32, atMs = Date.now(), window = DEFAULT_WINDOW, stepSeconds = DEFAULT_STEP_SECONDS, digits = DEFAULT_DIGITS) {
-  if (typeof code !== "string" || code.length !== digits) return false;
+  return verifyTotpCounter(code, secretBase32, atMs, window, stepSeconds, digits) !== void 0;
+}
+function verifyTotpCounter(code, secretBase32, atMs = Date.now(), window = DEFAULT_WINDOW, stepSeconds = DEFAULT_STEP_SECONDS, digits = DEFAULT_DIGITS) {
+  if (typeof code !== "string" || code.length !== digits) return void 0;
   const secret = base32Decode(secretBase32);
   const currentCounter = totpCounter(Math.floor(atMs / 1e3), stepSeconds);
   for (let offset = -window; offset <= window; offset++) {
-    const expected = hotp(secret, currentCounter + offset, digits);
+    const counter = currentCounter + offset;
+    const expected = hotp(secret, counter, digits);
     if (timingSafeEqual(Buffer.from(expected), Buffer.from(code))) {
-      return true;
+      return counter;
     }
   }
-  return false;
+  return void 0;
 }
 function buildOtpAuthUri(secretBase32, account, issuer = "WrongStack HQ", stepSeconds = DEFAULT_STEP_SECONDS, digits = DEFAULT_DIGITS) {
   const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(account)}`;
@@ -3275,7 +3395,7 @@ function verifyRecoveryCode(code, storedHashes) {
 import { createCipheriv, createDecipheriv, randomBytes as randomBytes2, scryptSync } from "node:crypto";
 import * as fs2 from "node:fs";
 import * as fsp from "node:fs/promises";
-import * as path5 from "node:path";
+import * as path8 from "node:path";
 
 // src/utils/deep-merge.ts
 var FORBIDDEN_PROTO_KEYS = /* @__PURE__ */ new Set([
@@ -3578,7 +3698,7 @@ var DefaultSecretVault = class {
     const oldVersion = this._keyVersion;
     const newKey = randomBytes2(KEY_BYTES);
     const newVersion = oldVersion + 1;
-    fs2.mkdirSync(path5.dirname(this.keyFile), { recursive: true });
+    fs2.mkdirSync(path8.dirname(this.keyFile), { recursive: true });
     const passphrase = getVaultPassphrase();
     if (passphrase) {
       writeKeyFileAtomicSync(this.keyFile, wrapDataKey(newKey, newVersion, passphrase));
@@ -3665,7 +3785,7 @@ var DefaultSecretVault = class {
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
-    fs2.mkdirSync(path5.dirname(this.keyFile), { recursive: true });
+    fs2.mkdirSync(path8.dirname(this.keyFile), { recursive: true });
     const key = randomBytes2(KEY_BYTES);
     const passphrase = getVaultPassphrase();
     const initialBytes = passphrase ? wrapDataKey(key, 1, passphrase) : key;
@@ -3725,7 +3845,7 @@ async function rewriteConfigEncrypted(configPath, vault, patch) {
   }
   const merged = deepMerge(current, patch ?? {});
   const encrypted = encryptConfigSecrets(merged, vault);
-  await fsp.mkdir(path5.dirname(configPath), { recursive: true });
+  await fsp.mkdir(path8.dirname(configPath), { recursive: true });
   await atomicWrite(configPath, JSON.stringify(encrypted, null, 2), { mode: 384 });
   await restrictFilePermissions2(configPath);
   await vault.flushHardening?.();
@@ -3947,33 +4067,33 @@ var RESERVED_BYPASS_FIELDS = /* @__PURE__ */ new Set([
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function addString(issues, value, path6, required = true) {
+function addString(issues, value, path9, required = true) {
   if (typeof value === "string" && value.trim().length > 0) return true;
   if (!required && value === void 0) return false;
-  issues.push({ path: path6, message: "must be a non-empty string" });
+  issues.push({ path: path9, message: "must be a non-empty string" });
   return false;
 }
-function addEnum(issues, value, path6, values) {
+function addEnum(issues, value, path9, values) {
   if (typeof value === "string" && values.has(value)) return true;
-  issues.push({ path: path6, message: `must be one of: ${[...values].join(", ")}` });
+  issues.push({ path: path9, message: `must be one of: ${[...values].join(", ")}` });
   return false;
 }
-function validateAttributes(issues, value, path6) {
+function validateAttributes(issues, value, path9) {
   if (!isRecord3(value)) {
-    issues.push({ path: path6, message: "must be an object" });
+    issues.push({ path: path9, message: "must be an object" });
     return false;
   }
   let valid = true;
   for (const [key, item] of Object.entries(value)) {
     if (RESERVED_BYPASS_FIELDS.has(key)) {
       issues.push({
-        path: `${path6}.${key}`,
+        path: `${path9}.${key}`,
         message: "generic authorization bypass fields are forbidden"
       });
       valid = false;
     } else if (item !== null && !["string", "number", "boolean"].includes(typeof item)) {
       issues.push({
-        path: `${path6}.${key}`,
+        path: `${path9}.${key}`,
         message: "must be a string, number, boolean, or null"
       });
       valid = false;
@@ -3981,16 +4101,16 @@ function validateAttributes(issues, value, path6) {
   }
   return valid;
 }
-function validateScope(issues, value, path6) {
+function validateScope(issues, value, path9) {
   if (!isRecord3(value)) {
-    issues.push({ path: path6, message: "must be an object" });
+    issues.push({ path: path9, message: "must be an object" });
     return false;
   }
   for (const field of ["projectId", "sessionId", "cwd"]) {
-    if (value[field] !== void 0) addString(issues, value[field], `${path6}.${field}`);
+    if (value[field] !== void 0) addString(issues, value[field], `${path9}.${field}`);
   }
   if (value.constraints !== void 0)
-    validateAttributes(issues, value.constraints, `${path6}.constraints`);
+    validateAttributes(issues, value.constraints, `${path9}.constraints`);
   return true;
 }
 function decodeTrustBoundaryRequest(input) {
@@ -4113,9 +4233,11 @@ export {
   sanitizeApiError,
   scrubErrorDetail,
   scrubErrorText,
+  toolMutates,
   validateDirectoryPolicy,
   validateTrustPolicy,
   verifyRecoveryCode,
-  verifyTotp
+  verifyTotp,
+  verifyTotpCounter
 };
 //# sourceMappingURL=index.js.map

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

@@ -1,9 +1,3 @@
-/**
- * Pure helpers for permission policy evaluation — trust-pattern matching,
- * tool fingerprinting, and sensitive-read detection.
- *
- * Extracted from permission-policy.ts. No class state, no I/O.
- */
 import type { Tool } from '../types/tool.js';
 /**
  * Match a computed subject against stored trust patterns.
@@ -88,6 +82,29 @@ export declare function alwaysAllowUnavailableReason(tool: Tool, input: unknown)
  */
 export declare function permissionFingerprint(tool: Tool): string;
 export declare function shellCommandLineFromInput(input: unknown): string | undefined;
+/**
+ * True when `absPath` is the wstack global root (`~/.wrongstack`, or
+ * `WRONGSTACK_HOME`) or lives inside it.
+ *
+ * Callers use this to refuse *silent* access to WrongStack's own state. It is
+ * not a containment check — the file tools deliberately allow this root so the
+ * agent can manage its memory and sessions. What it gates is whether that
+ * access may happen without the user seeing it.
+ *
+ * The comparison is realpath-aware on both sides: `~/.wrongstack` may itself
+ * be a symlink, and the file tools canonicalize subjects to realpaths
+ * (`safeResolveReal`, WS-048), so a purely lexical check misses every state
+ * file under a symlinked root. The lexical pass stays first — it is free and
+ * correct for the default layout — and the realpath pass only runs when it
+ * fails, comparing the root (cached) against the subject's nearest existing
+ * ancestor.
+ */
+export declare function isInsideAgentStateRoot(absPath: string): boolean;
+/**
+ * True when writing `absPath` must not be silently auto-approved, because the
+ * file is part of WrongStack's own trusted state rather than project content.
+ */
+export declare function isProtectedAgentStatePath(absPath: string): boolean;
 export declare function inputPathLooksSensitive(input: unknown): boolean;
 export declare function shellCommandReadsSensitivePath(command: string): boolean;
 //# sourceMappingURL=permission-helpers.d.ts.map

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

@@ -92,6 +92,22 @@ export declare class DefaultPermissionPolicy implements PermissionPolicy {
     setYoloDestructive(enabled: boolean): void;
     /** Whether YOLO currently extends to destructive shell commands. */
     getYoloDestructive(): boolean;
+    /**
+     * True when this call is an FS_WRITE whose target lands inside WrongStack's
+     * own state root.
+     *
+     * FS_WRITE tools disagree on where the target path lives: write/edit use
+     * `path`, replace/format/git `files` (string OR array), patch `directory`,
+     * design `out`, scaffold writes under `cwd`/`template`. Checking only
+     * `path`/`file_path` let a state-root write merely switch tools, so every
+     * path-bearing key is inspected.
+     *
+     * Shared by the YOLO carve-out and the eval-cache guard so the two cannot
+     * drift: the carve-out scans all path keys while the cache key fingerprints
+     * only the subject key, so the cache must consult the same predicate or a
+     * secondary state-root key can be replayed a cached `auto`.
+     */
+    private hasAgentStateWriteTarget;
     /**
      * 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

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

@@ -31,6 +31,26 @@
 import type { Context } from '../core/context.js';
 import type { PermissionDecision, PermissionPolicy, PermissionTrace } from '../types/permission.js';
 import type { Tool } from '../types/tool.js';
+/**
+ * Does this tool change something?
+ *
+ * `capabilities` is the precise answer and stays authoritative — but it is
+ * OPT-IN metadata, and a repo-wide count found 154 tools declaring
+ * `mutating: true` of which 121 carried no mutation capability at all (28 of
+ * those at `permission: 'auto'`, including tools that write API keys and one
+ * that sends messages outbound). Read-only mode consulted only `capabilities`,
+ * so every one of them ran unblocked and unprompted, while
+ * `permission-policy.ts` was already answering the same question with
+ * `tool.mutating || …`.
+ *
+ * Trusting `mutating` here closes all 121 at once and makes the two policies
+ * agree. It fails in the safe direction: a tool that declares itself mutating
+ * is blocked in read-only mode even if its capability list is incomplete.
+ * Fixing the capability labels is still worth doing — it is what the finer
+ * grained gates key on — but it is no longer what stands between read-only
+ * mode and a write.
+ */
+export declare function toolMutates(tool: Tool): boolean;
 /**
  * Read-only permission policy — session-scoped toggle via ctx.meta['readOnly'].
  *

package/dist/security/totp.d.ts

@@ -55,6 +55,20 @@ export declare function generateTotp(secretBase32: string, atMs?: number, stepSe
  * @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;
+/**
+ * Like {@link verifyTotp}, but returns the time-step counter the code matched
+ * so the caller can enforce single use.
+ *
+ * RFC 6238 §5.2 requires that a code be accepted only once: the validation
+ * window is ±1 step by default, so a code observed in transit stays
+ * arithmetically valid for up to ~90 seconds. Recording the matched counter and
+ * refusing anything at or below it turns that window into one-shot. HQ's
+ * `/api/login/verify` does this against `mutableAuth.totpLastUsedCounter`.
+ *
+ * @returns the matched counter, or `undefined` when no step in the window
+ *   matches.
+ */
+export declare function verifyTotpCounter(code: string, secretBase32: string, atMs?: number, window?: number, stepSeconds?: number, digits?: number): number | undefined;
 /**
  * Build an `otpauth://` URI for QR-code provisioning (RFC 6238 / Google Auth).
  *

package/dist/session-registry-atomic-file.d.ts

@@ -1,12 +1,39 @@
 import type { SessionRegistryEntry } from './session-registry-types.js';
 /** Also the scan interval for {@link pruneStaleTempFiles} — see its caller. */
 export declare const STALE_TMP_MS = 60000;
+/** `host:pid` owner stamp written into the advisory lock on acquisition. */
+export declare function lockOwnerStamp(): string;
 /**
- * Break a contended lock if it is stale: the recorded owner pid is no longer
- * alive, or the lock is older than {@link STALE_LOCK_MS}. Returns true when the
- * lock was removed (caller should retry acquisition). Best-effort and
- * race-tolerant — a fresh lock (age ~0, live owner) is never broken, so the
- * common concurrent case self-heals on the next heartbeat.
+ * Unlink `lockPath` only if it still carries OUR exact host:pid stamp. A
+ * stale-lock breaker may have stolen the lock and re-stamped it with another
+ * host:pid; the resumed holder must not remove the new owner's lock. An EMPTY
+ * read is never ours to remove either — it may be the new owner's lock in its
+ * open-to-stamp gap (that lock is mtime-bounded instead).
+ *
+ * Residual race: between the owner read and the unlink, a foreign-host lease
+ * break could replace the lock; unlinking would then remove the new owner's
+ * lock. Exploiting it requires a >STALE_LOCK_MS hold AND a rename+stamp
+ * landing inside that microsecond window, so it is accepted and bounded by
+ * the same foreign-lease logic that enabled it.
+ */
+export declare function maybeUnlinkOwnedLock(lockPath: string): Promise<void>;
+/**
+ * Break a contended lock if it is stale: a same-host owner pid that is no
+ * longer alive, or a foreign-host/ownerless lock older than
+ * {@link STALE_LOCK_MS}. A live same-host owner's lock is only broken past
+ * {@link SAME_HOST_STALE_MS} — a live-but-wedged holder must not degrade
+ * cross-session writes forever, but mtime alone must not false-positive while
+ * the holder is mid-critical-section. Returns true when the lock was removed
+ * (caller should retry acquisition).
+ *
+ * Removal is an atomic RENAME to a unique tombstone, never unlink: with
+ * unlink, two waiters can both read a stale lock and one's unlink can remove
+ * the OTHER's fresh lock, letting both into the critical section (POSIX).
+ * Rename wins for exactly one waiter; losers get ENOENT and simply retry.
+ * (A rename landing after the winner re-created the lock could still move the
+ * winner's fresh lock — a pre-existing microsecond TOCTOU; the caller's
+ * stamp-guarded cleanup prevents the resumed holder from unlinking the new
+ * owner's lock.)
  */
 export declare function breakStaleLock(lockPath: string): Promise<boolean>;
 export declare function writeAtomicFile(filePath: string, registry: Record<string, SessionRegistryEntry>): Promise<void>;

package/dist/skills/frontmatter.d.ts

@@ -28,6 +28,12 @@ export interface ParsedSkillFrontmatter {
      * consult this field, so it neither grants nor restricts any tool.
      */
     allowedTools?: string[] | undefined;
+    /** WrongStack stable runtime capabilities required before this skill may load. */
+    requiredCapabilities?: string[] | undefined;
+    /** Exact registered tool names required before this skill may render or load. */
+    requiredTools?: string[] | undefined;
+    /** Capabilities that improve the workflow but have documented fallbacks. */
+    optionalCapabilities?: string[] | undefined;
 }
 /**
  * Parse the YAML frontmatter block from a raw SKILL.md file. Returns `{}` when