@sabaiway/agent-workflow-kit 14.15.0 → 14.16.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.16.0 — `/agent-workflow-kit jev` walks you to a first Jev request: what it is, what it is not, three steps and three prompts where it pays (AD-164)
+
+**A new read-only command, `/agent-workflow-kit jev`, recommends Jev (TypeSafe), a decision model that returns a typed
+answer with probabilities and a confidence.** It says what Jev is, why it pays in this workflow, and what it is not,
+quoting the vendor's own sentence that it is not a drop-in replacement for the LLM behind Claude Code, Cursor, opencode
+or Copilot, then the jagged edges of jev-1.13, the confidence caveat and the retention terms as the vendor states them,
+and its sources, each with the date it was read.
+
+- **Three steps to a first request.** The vendor skill: both install forms, Claude Code's and the other agents', in a
+  fixed order, and a mark: `found` names each of five skill paths that holds a `typesafe-ai/SKILL.md`, `not seen`
+  says a plugin install is not visible to a file check and names the checks that do see it. The key: where to get it,
+  `TYPESAFE_API_KEY` exported before the agent starts, never pasted into the chat, and a `set` / `not set` mark. The
+  first use: a prompt routing three tickets, then the vendor's smallest documented request and response with the
+  field and error meanings, quoted.
+- **Three prompts where it pays here:** the first real error in a red gate log, the decided-register entry a council
+  finding repeats, a paragraph that restates a named rule. Each tells the agent to keep every request within the vendor
+  limits (255 options, 64k tokens, 32k for the state plus the longest question), and each answer is a hint the agent
+  checks, never a gate; every candidate text goes to the vendor.
+- **Safe to run anywhere.** The guide writes nothing, opens no connection and never prints the key's value; `--json`
+  gives the same content as an envelope. The command appears in the command list, the skill description and the
+  README's Use table.
+
+## 14.15.1 — a fenced empty read-only file no rule calls a mask stops the probe, so a concurrent sandboxed command no longer turns its masks into real paths (AD-163)
+
+**`/agent-workflow-kit sandbox-masks` now withholds its verdict on a possible leftover.** While one sandboxed
+command runs, a second one sees that command's masks as empty read-only regular files; until 14.15.1 the probe called
+each of those fenced masks a real path, and the Recommendations screen offered `--apply --clear`, which would
+remove a working block.
+
+- **The refusal.** A fenced entry that neither rule calls a mask, and whose lstat is an empty regular file with a
+  numeric mode and no write bit, stops the probe with exit 1; the Recommendations screen records a skip. The message
+  lists every fenced entry that became a real path first, then each such file with its three readings: a
+  running sandbox's mask (re-run once no other sandboxed command runs), litter a sandbox left (remove the file outside
+  the sandbox, keep its line), or a real file (delete its line). No `--clear` is offered and no plain `--apply` drops
+  its line.
+- **What stays.** An unfenced file of that shape is not a mask, a fenced foreign mount target of that shape stays a
+  mask, a stat without a numeric mode proves nothing, and `--apply --clear` still removes the block without judging
+  it. The derivation and the check of fenced entries share one lstat answer per work-tree path within a probe.
+
 ## 14.15.0 — a sandbox mask made by a bind mount counts as a mask, so the advisor no longer offers to clear a working exclude block (AD-162)
 
 **`/agent-workflow-kit sandbox-masks` now reads the Linux mount table.** Until 14.15.0 a mask was only a device, a

package/README.md

@@ -235,6 +235,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), and the **feature-spec adoption state** (`not adopted` / `adopting (N draft)` / `adopted (N live, M draft)` / `could not be read`, plus `declined` when recorded), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit now` | any time | **read-only** answer to where work stands in four blocks: **NOW** names every plan in flight, its phase, current and next step, and the tree evidence; **STEPS** gives every ledger row its evidence-derived status; **QUEUE** folds named rows under their full heading paths and calls position priority only in the judged backlog; **CAMPAIGN** shows the source-size practice figures and config state. The plan's own text never sets a status; a contradicted claim prints beside it. A block that cannot be derived is WITHHELD with its cause; NOW has two halves, plans and tree, each independently a value or WITHHELD, and NOW itself is WITHHELD only when both are. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit tier` | any time | **read-only** guide to the epic, story and task tier: what each level is, and the next step of the walk, with the command that runs it wherever a tool does. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit jev` | any time | **read-only** guide to Jev (TypeSafe), a decision model: what it is, why it pays here, what it is not, the three steps to a first request and three prompts where it pays. Opens no connection and never prints the key. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents five named recipes for composing the carriers of a step — the bridges and the full-tool executor subagent — into plan → execute → review — **Solo / Reviewed / Council / Delegated / Subagent** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready, or when the executor vehicle is missing/unusable), and offers the choice. The activity/slot registry (six activities) is rendered by `procedures` and by `set-recipe --help`. The orchestrator runs it via the bridge skills or the executor vehicle and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution` / `routine` / `feedback-triage` / `epic` / `task`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + carrier readiness (`plan-authoring`: author, fold, review; default Reviewed when a backend is ready, Council on request; slot-aware incl. Delegated and Subagent) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same) — except `feedback-triage`, whose record-bound block carries the check with `--excerpts`, the resolved member lines (ready bridge commands, the ready lens brief, or explicit skipped members), and either the record round-table command for a bridge obligation or the no-receipt fact otherwise: the record is the artifact. `--override <slot>=<value>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<value>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend or a subagent, never commits**; hand-editing stays fully supported. |

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-kit
-description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
+description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.15.0'
+  version: '14.16.0'
 ---
 
 # agent-workflow-kit
@@ -119,6 +119,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/now.md` before acting.
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/tier.md` before acting.
 
+### Mode: jev
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/jev.md` before acting.
+
 ### Mode: recommendations
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md` before acting.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.15.0",
+  "version": "14.16.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.15.0",
+  "version": "14.16.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/jev.md

@@ -0,0 +1,21 @@
+### Mode: jev
+
+<!-- opt-in-capability: none — a read-only guide that configures nothing and calls no service -->
+
+Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the three steps to a first request and three prompts where it pays. It writes no file, opens no connection, never prints the key's value and never commits.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/jev-guide.mjs --dir <project> --json`.
+
+Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them. Keep every vendor-quoted text verbatim and in quotes, never translated or reflowed: the not-a-replacement sentence, the request, the response, the three field meanings and the four error meanings.
+
+Keep this order: the fixed text (WHAT, WHY HERE, NOT, SOURCES); then the three steps — the vendor skill with its install lines and its mark, the key with its mark, the first use; then the three prompts where it pays.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Rendered, or `--help` / `-h` as the whole invocation. |
+| 1 | Nothing rendered: a stat of the `--dir` does not report a directory; the cause is printed on stderr. |
+| 2 | Usage: an unknown argument, a `--dir` without a value, or `--help` / `-h` combined with anything. |
+
+**Invariants:** read-only · no network · the key's value never printed · compact user-language render with paths, commands and vendor quotes verbatim · `process.exitCode`, never `process.exit()`.

package/tools/commands.mjs

@@ -98,6 +98,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Explain the epic, story and task tier in plain words and name the next step of the walk, with the command that runs it wherever a tool does: the tier guide reads the disk alone.',
   },
+  {
+    key: 'jev',
+    invocation: invocationOf('jev'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Guide to Jev (TypeSafe), a decision model: what it is, why it pays here, the steps to a first request and three prompts where it pays; the guide opens no connection.',
+  },
   {
     key: 'backends',
     invocation: invocationOf('backends'),

package/tools/jev-guide.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// spec:jev-guide — docs/ai/specs/kit/jev-guide/index.md
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const SCHEMA = 1;
+const KEY_VARIABLE = 'TYPESAFE_API_KEY';
+const SKILL_FILE = join('typesafe-ai', 'SKILL.md');
+const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the steps to a first request.
+
+Usage:
+  node jev-guide.mjs [--dir PROJECT] [--json]
+
+--dir   the project to read (default: the current directory).
+--json  the JSON envelope instead of the plain text.
+--help  answered only when it is the whole invocation.
+
+Exit codes: 0 rendered; 1 nothing rendered (a --dir that is not a directory); 2 usage.
+
+Reads only: the --dir, the home directory, the key variable's presence and five skill paths; no network.`;
+
+export const JEV_TEXT = Object.freeze([
+  'WHAT: Jev is a decision model: it takes a state and typed questions (choice, score, noul) and returns typed answers with probabilities and a confidence; it does not write text.',
+  'WHY HERE: a typed decision with a confidence instead of prompt-and-parse, in the user\'s own code and in the agent\'s scratch scripts.',
+  'Price and latency as the vendor states them: 0.042 dollars per million input tokens, output free; sub-second.',
+  'NOT: "Jev is not a drop-in replacement for the LLM behind Claude Code, Cursor, opencode, Copilot" (the vendor).',
+  'Jagged edge of jev-1.13: it reads literally.',
+  'Jagged edge of jev-1.13: no counting or arithmetic.',
+  'Jagged edge of jev-1.13: dates are read as text.',
+  'Jagged edge of jev-1.13: a large irrelevant state distracts it.',
+  'Jagged edge of jev-1.13: adversarial content can move the answer.',
+  'Jagged edge of jev-1.13: indirection lowers accuracy.',
+  'Jagged edge of jev-1.13: no structural invariants across questions.',
+  'Jagged edge of jev-1.13: no generation.',
+  'A confidence is not a correctness: start with conservative thresholds and test with your own data.',
+  'Retention as the vendor states it: zero data retention for enterprise customers only; a data processing agreement covers retention; a commitment not to train on user data.',
+  'SOURCES: docs.typesafe.ai for every Jev claim, read 2026-09-29.',
+  'The skills CLI README (github.com/vercel-labs/skills) for the skill paths, read 2026-09-29.',
+  'code.claude.com for claude plugin list, read 2026-09-29.',
+]);
+
+const INSTALL = [
+  'Claude Code:',
+  'claude plugin marketplace add typesafe-ai/skills',
+  'claude plugin install typesafe@typesafe-ai',
+  'Other agents:',
+  'npx skills add typesafe-ai/skills --skill typesafe-ai',
+];
+const NOT_SEEN = [
+  'skill: not seen at the five skill paths. A plugin install is not visible to a file check; check it by its owners:',
+  '/typesafe:typesafe-ai',
+  'in a Claude Code session (the vendor); ask any other agent to use the TypeSafe skill (the vendor); or run Claude Code\'s own',
+  'claude plugin list',
+];
+const KEY_TEXT = [
+  'Get a key at console.typesafe.ai and set it on every host the agent runs on.',
+  `Export ${KEY_VARIABLE}, the variable the vendor's SDKs read, in the shell the agent is started from: an agent inherits the environment its session started with, so export before starting it or restart it.`,
+  'Never paste the key into the chat or into a project file.',
+];
+const KEY_NOT_SET = `key: ${KEY_VARIABLE} not set. A host setting that filters the environment of the agent's commands also hides it.`;
+const FIRST_USE = [
+  'Give the agent this prompt: using the TypeSafe skill, route these three tickets to billing, technical or sales, one request each, and print each choice and confidence — "I was charged twice this month.", "The app crashes when I upload a file.", "Is there a discount for a yearly plan?".',
+  'The vendor\'s smallest documented request:',
+  'POST https://api.typesafe.ai/v1/systemone',
+  'Authorization: Bearer <API_KEY>',
+  '{"state":"Help! My payouts have been failing for 3 days.","model":"jev-latest","questions":{"department":{"type":"choice","instructions":"Which team should handle this?","criteria":{"billing":"Payments, invoicing, refunds","technical":"Bugs, outages, integrations","sales":"Pricing, upgrades, new accounts"}}}}',
+  'Its documented response:',
+  '{"model":"jev-1.13.0","answers":{"department":{"type":"choice","choice":"billing","probabilities":{"billing":0.88,"technical":0.12,"sales":0.0},"confidence":0.81}},"usage":{"input_tokens":318,"output_tokens":34}}',
+  'choice: "The highest-probability option."',
+  'probabilities: "Every option mapped to its probability (floats that sum to 1)."',
+  'confidence: "How certain the model is, derived from probabilities."',
+  '401: "Missing or invalid API key. Check the `Authorization` header."',
+  '422: "The request body failed validation — for example a missing required field or a malformed question. The body details the offending field."',
+  '429: "You have exceeded your rate limit. Back off and retry after a short delay."',
+  '529: "TypeSafe is temporarily overloaded. Retry after a short delay."',
+  'Success: three choices, each with a confidence.',
+];
+const LIMITS = 'Each request stays within the vendor limits: 255 options, 64k tokens, 32k for the state plus the longest question.';
+const HINT = 'The answer is a hint the agent checks, never a gate; every candidate text is sent to the vendor.';
+const PROMPTS = [
+  `(a) A red gate log: give each failing gate's own lines ids and ask one choice of the first real error per failing gate. ${LIMITS} ${HINT}`,
+  `(b) Council findings against the decided register: for each finding, ask a choice of the register id it repeats, or none. ${LIMITS} ${HINT}`,
+  `(c) Candidate paragraphs with ids: ask one noul each that the paragraph restates a named rule. ${LIMITS} ${HINT}`,
+];
+
+const valueAt = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('-')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+const parseArgv = (argv) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length !== 1) throw fail(2, '--help is answered only when it is the whole invocation');
+    return { help: true };
+  }
+  return argv.reduce((parsed, arg, index) => {
+    if (parsed.skip) return { ...parsed, skip: false };
+    if (arg === '--dir') return { ...parsed, dir: valueAt(argv, index, arg), skip: true };
+    if (arg === '--json') return { ...parsed, json: true };
+    throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }, { help: false, dir: '.', json: false, skip: false });
+};
+
+const statIs = (path, kind) => {
+  try { return kind === 'file' ? statSync(path).isFile() : statSync(path).isDirectory(); } catch { return false; }
+};
+const skillPaths = (dir, home) => [...new Set([join(dir, '.claude', 'skills'), join(dir, '.agents', 'skills'),
+  join(home, '.claude', 'skills'), join(home, '.codex', 'skills'), join(home, '.cursor', 'skills')]
+  .map((root) => join(root, SKILL_FILE)))];
+const keySet = (env) => typeof env[KEY_VARIABLE] === 'string' && env[KEY_VARIABLE].trim() !== '';
+
+const renderSteps = (found, set) => [
+  ['STEP 1 — the vendor skill', ...INSTALL,
+    ...(found.length ? found.map((path) => `skill: found at ${path}`) : NOT_SEEN)],
+  ['STEP 2 — the key', ...KEY_TEXT, set ? `key: ${KEY_VARIABLE} set.` : KEY_NOT_SET],
+  ['STEP 3 — the first use', ...FIRST_USE],
+];
+
+export const main = (argv, io = {}) => {
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const parsed = (() => {
+    try { return parseArgv(argv); } catch (err) { error(err.message); return null; }
+  })();
+  if (parsed === null) return 2;
+  if (parsed.help) { log(HELP); return 0; }
+  const dir = resolve(io.cwd ?? process.cwd(), parsed.dir);
+  if (!statIs(dir, 'directory')) { error(`${dir} is not a directory`); return 1; }
+  const found = skillPaths(dir, io.home ?? homedir()).filter((path) => statIs(path, 'file'));
+  const set = keySet(io.env ?? process.env);
+  const steps = renderSteps(found, set);
+  log(parsed.json
+    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found }, key: { set },
+      steps, prompts: PROMPTS }, null, 2)
+    : [...JEV_TEXT, ...steps.flat(), 'WHERE IT PAYS IN THIS WORKFLOW', ...PROMPTS].join('\n'));
+  return 0;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/sandbox-masks.mjs

@@ -86,6 +86,9 @@ const mountTargets = (root, readMountinfo) => {
   }
 };
 
+// A LEFTOVER: an empty regular file with a numeric mode and no write bit — it only withholds a verdict.
+const isLeftoverStat = (stat) => stat?.isFile?.() === true && stat.size === 0 && typeof stat.mode === 'number' && (stat.mode & 0o222) === 0;
+
 // A root-anchored gitignore pattern for one relative path: leading `/` (root-anchored — a mask
 // name can never shadow a deeper real path), glob metacharacters + leading-! / leading-# handled
 // by the anchor, trailing whitespace escaped (gitignore trims it otherwise).
@@ -150,9 +153,7 @@ export const patternToRel = (line) => {
   return t.slice(1).replace(/\\([\\*?[\] ])/g, '$1');
 };
 
-// Revalidate the CURRENT fence body against the disk: an entry whose path now exists as anything
-// that is not a mask (the derivation's predicate) is a STALE-REAL flag — the D5 watch (a real file
-// at an excluded path is silently skipped by bulk staging; delete the line before trusting git).
+// A fenced entry that exists and fails the derivation's predicate is STALE-REAL (the D5 watch).
 export const revalidateFence = (bodyLines, { root, lstat = lstatSync, readMountinfo = readMountinfoDefault, foreign = mountTargets(root, readMountinfo).foreign } = {}) => {
   const staleReal = [];
   for (const line of bodyLines) {
@@ -172,8 +173,8 @@ export const revalidateFence = (bodyLines, { root, lstat = lstatSync, readMounti
 // ── the probe (read-only; exported — the Recommendations advisor consumes it) ──────
 
 // probeSandboxMasks({ cwd, ... }) → everything the render/apply/advisor needs, or null when not a
-// git work tree. Read-only always.
-export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, listUntracked = listUntrackedUnfilteredZ, readFile = readFileSync, readMountinfo = readMountinfoDefault } = {}) => {
+// git work tree; a fenced LEFTOVER refuses unless clearOnly. Read-only always.
+export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, listUntracked = listUntrackedUnfilteredZ, readFile = readFileSync, readMountinfo = readMountinfoDefault, clearOnly = false } = {}) => {
   const root = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (root == null) return null;
   const gitPathRaw = gitLine(['rev-parse', '--git-path', 'info/exclude'], cwd);
@@ -183,23 +184,23 @@ export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, list
   // The write-containment root: info/exclude lives in the COMMON git dir (worktree-safe),
   // and the apply must never write through a symlinked component or a non-regular leaf.
   const gitCommonDir = resolve(cwd, commonDirRaw);
-  let text; // read ONCE: derivation and revalidation judge one table
+  let text; // read ONCE: derivation and revalidation judge one table, and one lstat answer per path
   const once = () => (text === undefined ? (text = readMountinfo()) : text);
-  const derived = deriveMasks({ root, lstat, listUntracked, readMountinfo: once });
+  const answers = new Map();
+  const lstatOnce = (p) => {
+    if (!answers.has(p)) answers.set(p, (() => { try { return { stat: lstat(p) }; } catch (error) { return { error }; } })());
+    if (answers.get(p).error) throw answers.get(p).error;
+    return answers.get(p).stat;
+  };
+  const derived = deriveMasks({ root, lstat: lstatOnce, listUntracked, readMountinfo: once });
   if (derived == null) return null;
   const { masks, unrenderable, mountOnly, mountSignal } = derived;
-  // The WHOLE chain is guarded BEFORE any read: a symlinked exclude leaf OR a
-  // symlinked parent (.git/info) must never be read through, and a FIFO/socket leaf would HANG
-  // the read-only probe — parent-chain containment + leaf lstat first, fail closed on everything
-  // but a plain absent file, then read the existing REGULAR content. The apply re-checks
-  // (defense in depth) before writing.
+  // The whole chain is guarded BEFORE any read (a symlinked component; a FIFO/socket leaf would hang).
   try {
     assertContainedRealPath(gitCommonDir, excludeFile, { lstat });
   } catch (err) {
     throw fail(1, `refusing to touch ${excludeFile}: ${err.message}`);
   }
-  // The chain guard above already refused symlinked components (the leaf included) and PROPAGATED
-  // any non-ENOENT lstat failure — after it, the leaf can only be absent or exist non-symlinked.
   const leafStat = (() => {
     try {
       return lstat(excludeFile);
@@ -222,16 +223,15 @@ export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, list
   }
   const lines = content.split('\n');
   const fence = findMasksFence(lines);
-  const staleReal = fence.state === 'ok' ? revalidateFence(fence.body, { root, lstat, readMountinfo: once }) : [];
+  const staleReal = fence.state === 'ok' ? revalidateFence(fence.body, { root, lstat: lstatOnce, readMountinfo: once }) : [];
+  const leftovers = clearOnly ? [] : staleReal.filter((rel) => isLeftoverStat(lstatOnce(join(root, rel))));
+  if (leftovers.length > 0) throw fail(1, [...staleReal.filter((rel) => !leftovers.includes(rel)).map(staleRealLine), ...leftovers.map(leftoverLine)].join('\n'));
   const applyCmd = `node ${shellQuoteArg(join(HERE, 'sandbox-masks.mjs'))} --cwd ${shellQuoteArg(root)} --apply`;
   return { root, excludeFile, gitCommonDir, content, lines, fence, masks, unrenderable, mountOnly, mountSignal, staleReal, applyCmd };
 };
 
-// needsMasksApply(probe) → whether the CURRENT derivation diverges from the fenced block — the
-// Recommendations advisor's fire condition (Phase 3, AD-044 Plan 4). True when any fenced entry
-// became a real path (stale-real), or when visible masks exist and the derived set ≠ the fenced
-// set. A malformed fence is NOT an apply item (the apply would fail closed — it needs a hand fix,
-// which the probe render itself flags loudly). Pure over the probe result.
+// needsMasksApply(probe) → the advisor's fire condition: a stale-real entry, or visible masks whose set
+// differs from the fenced one; a malformed fence is never an item (the render flags it). Pure.
 export const needsMasksApply = (probe) => {
   if (probe == null) return false;
   if (probe.staleReal.length > 0) return true;
@@ -262,10 +262,8 @@ export const planApply = (probe, { clear = false } = {}) => {
   }
   const masks = clear ? [] : probe.masks;
   const block = masks.length === 0 ? [] : [MASKS_FENCE_START, ...masks.map(toExcludePattern), MASKS_FENCE_END];
-  // EVERY hand byte outside the managed fence is preserved EXACTLY: the first-apply
-  // append adds at most ONE separator newline, and the existing-block replace splices via RAW
-  // string offsets around the fence lines — a split/join('\n') rebuild would silently normalize
-  // CRLF hand content outside the block. Only the fenced block itself is ours (always LF).
+  // Every hand byte outside the fence is preserved EXACTLY (raw offsets, never a split/join rebuild
+  // that would normalize CRLF); only the fenced block itself is ours (always LF).
   const rendered = block.length ? `${block.join('\n')}\n` : '';
   let content;
   if (probe.fence.state === 'ok') {
@@ -283,6 +281,9 @@ export const planApply = (probe, { clear = false } = {}) => {
 
 // ── rendering ───────────────────────────────────────────────────────────────────────
 
+const staleRealLine = (rel) => `  ⚠ fenced entry became a REAL path: ${rel} — delete its line from the managed block BEFORE relying on git for this path: an excluded real file is silently skipped by bulk staging (git add -A / git add .), so it stays OUT of your commits, and an explicit git add refuses it without -f; .git/info/exclude never warns`;
+const leftoverLine = (rel) => `  ⚠ refusing: fenced entry ${rel} is an empty read-only file no arm calls a mask, so neither verdict is given — a running sandbox's mask: re-run once no other sandboxed command runs; litter a sandbox left: remove the file outside the sandbox and keep its line; a real file: delete its line`;
+
 const formatProbe = (probe) => {
   const lines = [
     `sandbox-masks — sandbox masks (device/FIFO/socket or foreign mount target) in ${probe.root}`,
@@ -293,9 +294,7 @@ const formatProbe = (probe) => {
   lines.push(`  masks visible now: ${probe.masks.length === 0 ? '0 (outside the sandbox or clean)' : ''}`);
   for (const m of probe.masks) lines.push(`    · ${m}${probe.mountOnly.includes(m) ? ' (mount-only: it rides git add -A and the review fingerprint while git does not ignore it)' : ''}`);
   if (probe.mountSignal === 'absent') lines.push('  mount signal: not read on this platform — only device/FIFO/socket masks are judged');
-  for (const rel of probe.staleReal) {
-    lines.push(`  ⚠ fenced entry became a REAL path: ${rel} — delete its line from the managed block BEFORE relying on git for this path: an excluded real file is silently skipped by bulk staging (git add -A / git add .), so it stays OUT of your commits, and an explicit git add refuses it without -f; .git/info/exclude never warns`);
-  }
+  lines.push(...probe.staleReal.map(staleRealLine));
   for (const rel of probe.unrenderable) {
     lines.push(`  ⚠ mask name carries a newline or ends with a tab and cannot be expressed as ONE exclude rule — NOT written (the mask itself stays untracked): ${JSON.stringify(rel)}`);
   }
@@ -343,9 +342,9 @@ export const main = (argv, ctx = {}) => {
     const cwd = cwdIdx !== -1 ? argv[cwdIdx + 1] : (ctx.cwd ?? process.cwd());
     if (cwdIdx !== -1 && (!cwd || cwd.startsWith('--'))) throw fail(2, '--cwd requires a directory argument');
     if (argv.includes('--clear') && !argv.includes('--apply')) throw fail(2, '--clear is only valid together with --apply');
-    // --apply --clear needs no derivation, so it never reads the mount table (the absent answer).
+    // --apply --clear needs no derivation: it never reads the mount table and never judges the fence.
     const clearOnly = argv.includes('--apply') && argv.includes('--clear');
-    const probe = probeSandboxMasks({ cwd, ...(ctx.deps ?? {}), ...(clearOnly ? { readMountinfo: () => null } : {}) });
+    const probe = probeSandboxMasks({ cwd, ...(ctx.deps ?? {}), ...(clearOnly ? { readMountinfo: () => null, clearOnly } : {}) });
     if (probe == null) throw fail(1, `not a git work tree: ${cwd}`);
     if (!argv.includes('--apply')) {
       if (argv.includes('--json')) {