kronk-cli 0.2.1 → 0.3.1

package/README.md

@@ -234,12 +234,45 @@ little, since an attacker just takes whichever store was not on the list. So the
 material that is pivot-grade and never legitimately read by a build.
 
 **The one exception is the macOS keychain**, which is denied by default. `gh` stores its token
-there, so it will report `Failed to log in` under the sandbox. If you want it:
+there, so it reports `Failed to log in` under the sandbox even though you are logged in.
+
+You no longer have to know that in advance. When the agent is about to run a command that needs a
+credential store the sandbox denies, it asks first:
+
+```console
+  1 ⚙ bash: gh issue view 34
+  gh reads ~/Library/Keychains, which the sandbox denies.
+  allow read-only access for this session? [y/N/always]
+```
+
+- `y` grants it for the rest of the session. The seatbelt profile is rebuilt for every command, so
+  it takes effect on the next one — no restart.
+- `always` also writes the path to `~/.kronk-cli.json` under `sandboxReadable`, so later sessions
+  do not ask. It says which file it wrote.
+- Anything else declines, and **the command still runs**. Declining is not an error; the command
+  fails the way it would have failed anyway, and the result carries a note saying a denial is the
+  likely cause.
+
+You are asked at most once per path per session, whichever way you answered. With `--yes` or
+`--auto` there is nobody to ask, so the grant is automatic and announced on stderr — piping stdout
+still gets only the answer.
+
+The grant is **read-only**. That is the difference from the older escape hatch, which still works
+and is still the right tool if you would rather set it before you start:
 
 ```bash
 KRONK_SANDBOX_ALLOW=~/Library/Keychains kronk-cli
 ```
 
+`KRONK_SANDBOX_ALLOW` makes a path fully available — **readable *and writable***. For a credential
+store that is a poor trade: reading it is what a logged-in CLI needs, and writing to it is what an
+attacker needs. The prompt grants only the read.
+
+Be honest with yourself about what you are granting either way: it is the whole `~/Library/Keychains`
+directory, not one tool's item in it. macOS `securityd` gates individual items by per-application
+ACL independently of file reads, so a process still cannot read another application's item without
+your consent — but that is a mitigation on top, not the boundary you drew here.
+
 **Logging in from inside the agent will not work**, by design — `argocd login`, `gh auth login` and
 `kubectl config set-context` all write outside the project. Log in yourself, in your own shell,
 before starting a session. If a tool genuinely must write to its config directory, allow just that:
@@ -632,6 +665,7 @@ The per-turn usage line still prints after each response; this one is the runnin
 | `KRONK_SANDBOX` | `auto` | `auto` confines `bash` when the OS can, `strict` refuses to run it when it cannot, `off` disables it |
 | `KRONK_SANDBOX_ALLOW` | — | Paths to make fully available inside the sandbox, comma or colon separated |
 | `KRONK_SANDBOX_DENY` | — | Extra paths to hide from `bash`, comma or colon separated |
+| `KRONK_CONFIG` | `~/.kronk-cli.json` | Path to the config file, so tests and throwaway runs stay off the real one |
 | `KRONK_DISTILL` | `true` | `false` disables tool-output distillation |
 | `KRONK_DISTILL_AT` | `8000` | Characters of output that trigger distillation |
 | `KRONK_WARM` | `true` | `false` skips the boot-time model preload |
@@ -655,10 +689,15 @@ The per-turn usage line still prints after each response; this one is the runnin
   "compactAt": 0.85,
   "noThink": true,
   "preserveThinking": true,
-  "replayReasoning": true
+  "replayReasoning": true,
+  "sandboxReadable": ["~/Library/Keychains"]
 }
 ```
 
+`sandboxReadable` is the list `always` writes at the credential prompt — paths the sandbox lifts
+its **read** denial on, and nothing more. Unlike `KRONK_SANDBOX_ALLOW` it never grants writes.
+Entries may be absolute or `~`-relative, and one that no longer exists is ignored in silence.
+
 ---
 
 ## Choosing a model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kronk-cli",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A Claude-Code-style terminal agent for local models served by Kronk.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,6 +29,7 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "node --test test/*.test.js",
+    "changelog": "node scripts/changelog.mjs",
     "lint": "eslint .",
     "check": "npm run lint && npm test"
   },

package/src/agent.js

@@ -1,5 +1,8 @@
 import { streamChat } from './client.js';
-import { TOOLS, NEEDS_APPROVAL, runTool, describe, preview, mcpNeedsApproval } from './tools.js';
+import {
+  TOOLS, NEEDS_APPROVAL, runTool, describe, preview, mcpNeedsApproval,
+  grantsNeeded, rememberGrants, declineGrants, credentialMatches,
+} from './tools.js';
 import { config, shouldPreserveThinking } from './config.js';
 import { forRequest } from './reasoning.js';
 import { c, fmtUsage, spinner, liveLine, toolResultLines } from './ui.js';
@@ -73,6 +76,8 @@ function endTurn(messages) {
 /**
  * Run one user turn to completion, looping while the model requests tools.
  *
+ * `grant(binary, paths)` resolves to 'yes' | 'no' | 'always'; asked before a
+ * command that needs a credential store the sandbox denies.
  * `approve(name, args)` returns a boolean; used for mutating tools. `auto` is
  * autonomous mode — the system prompt in force, not `--yes` — and decides
  * both whether a premature "done" is handed back or accepted, and (via
@@ -80,7 +85,7 @@ function endTurn(messages) {
  * replayed on the wire.
  */
 export async function runTurn({
-  messages, model, signal, approve, mcp, auto = false, maxSteps = config.maxSteps,
+  messages, model, signal, approve, grant, mcp, auto = false, maxSteps = config.maxSteps,
 }) {
   const tools = mcp ? [...TOOLS, ...mcp.toolDefs()] : TOOLS;
   let totalUsage = null;
@@ -251,6 +256,38 @@ export async function runTurn({
         }
       }
 
+      // Ask here, not in the tool layer, and not after this point.
+      //
+      // `liveLine()` below starts a 120 ms interval that rewrites the current
+      // line with `\r…\x1b[K` unconditionally, so a question printed once it is
+      // running gets overwritten between the asking and the answering. This is
+      // the last moment at which stdout belongs to us, and it is next door to
+      // the approval prompt the user already expects, which is where a second
+      // question belongs anyway.
+      if (call.name === 'bash' && grant) {
+        const needed = grantsNeeded(args.cmd);
+        if (needed.length) {
+          // Name the tool the user recognises, from the same scan that found
+          // the paths — so the question cannot name one binary while granting
+          // for another.
+          const binary = credentialMatches(args.cmd)
+            .find((m) => m.paths.some((p) => needed.includes(p)))?.bin ?? 'this command';
+          const answer = await grant(binary, needed);
+          if (answer === 'yes' || answer === 'always') {
+            try {
+              const wrote = rememberGrants(needed, { persist: answer === 'always' });
+              if (wrote) console.log(c.grey(`  remembered in ${wrote}`));
+            } catch (e) {
+              // Failing to persist must not fail the command. The grant is
+              // already in force for this session either way.
+              console.log(c.yellow(`  ${e.message}`));
+            }
+          } else {
+            declineGrants(needed);
+          }
+        }
+      }
+
       const live = liveLine();
       let result;
       try {

package/src/config.js

@@ -2,7 +2,10 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readFileSync } from 'node:fs';
 
-const RC = join(homedir(), '.kronk-cli.json');
+// KRONK_CONFIG exists so tests never touch the real file. Everything here is
+// read at module load, so a test that sets it must `await import()` rather than
+// use a static import — a static one is hoisted and runs before the assignment.
+const RC = process.env.KRONK_CONFIG ?? join(homedir(), '.kronk-cli.json');
 const MODEL_CONFIG = join(homedir(), '.kronk', 'models', 'model_config.yaml');
 
 function fileConfig() {
@@ -56,6 +59,12 @@ export const config = {
   // Kronk's per-model runtime settings. `setup` is the only thing that writes
   // it; the override exists so tests never go near the real one.
   modelConfigPath: process.env.KRONK_MODEL_CONFIG ?? file.modelConfigPath ?? MODEL_CONFIG,
+  // Paths a previous session granted read-only to the sandbox, via `always` at
+  // the credential prompt. Read-only is the whole point: KRONK_SANDBOX_ALLOW
+  // grants writes as well, and these are credential stores.
+  sandboxReadable: (Array.isArray(file.sandboxReadable) ? file.sandboxReadable : [])
+    .filter((p) => typeof p === 'string' && p.trim())
+    .map((p) => (p.startsWith('~/') ? join(homedir(), p.slice(2)) : p)),
   lastUsed: 0,
   contextWindow: null,   // filled in at boot from Kronk
   nativeContext: null,

package/src/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
+import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { config, DEFAULT_MODEL, warnIfInsecure } from './config.js';
 import { listModels, listModelDetails, listLoaded, modelLimits, tokenize } from './client.js';
@@ -76,6 +77,9 @@ if (args.help) {
 // --auto: run the whole task unattended (implies --yes)
 const AUTO = args.auto;
 const AUTO_YES = args.yes || AUTO;
+
+/** `~/Library/Keychains` reads better than the absolute path in a prompt. */
+const tilde = (p) => (p.startsWith(`${homedir()}/`) ? `~/${p.slice(homedir().length + 1)}` : p);
 const SHOW_MODELS = args.models;
 const SHOW_MCP = args.mcpList;
 const NO_CONTEXT = args.noContext;
@@ -312,8 +316,21 @@ async function oneShot(prompt) {
     console.log(c.yellow(`  ✗ ${name} needs approval; re-run with --yes to allow it`));
     return false;
   };
+
+  // Nobody is here to answer, and this mode already auto-approves everything
+  // else. Granting silently would reproduce the exact failure #21 is about —
+  // `gh` reporting a broken login — in the mode where it is hardest to notice,
+  // so it is announced. On stderr, so a piped stdout still carries only the
+  // answer.
+  const grant = async (binary, paths) => {
+    if (!AUTO_YES) return 'no';
+    console.error(c.grey(`  granted read-only ${paths.map(tilde).join(', ')} to ${binary} (--yes)`));
+    return 'yes';
+  };
   try {
-    await runTurn({ messages, model: config.model, signal: ac.signal, approve, mcp, auto: AUTO });
+    await runTurn({
+      messages, model: config.model, signal: ac.signal, approve, grant, mcp, auto: AUTO,
+    });
   } catch (e) {
     if (e.name !== 'AbortError') { console.error(c.red(`  ${e.message}`)); process.exitCode = 1; }
   } finally {
@@ -414,6 +431,21 @@ async function main() {
     return a === 'y' || a === 'yes';
   };
 
+  // Read-only, and said so: the answer to "why is my gh broken" should not be a
+  // flag you had to know about before you started. `always` writes the path to
+  // ~/.kronk-cli.json so the next session does not ask.
+  const grant = async (binary, paths) => {
+    if (autoApprove) {
+      console.error(c.grey(`  granted read-only ${paths.map(tilde).join(', ')} to ${binary} (--yes)`));
+      return 'yes';
+    }
+    console.log(c.yellow(`  ${binary} reads ${paths.map(tilde).join(', ')}, which the sandbox denies.`));
+    const a = (await rl.question(c.yellow('  allow read-only access for this session? [y/N/always] ')))
+      .trim().toLowerCase();
+    if (a === 'always' || a === 'a') return 'always';
+    return a === 'y' || a === 'yes' ? 'yes' : 'no';
+  };
+
   for (;;) {
     const status = statusLine({
       model: config.model,
@@ -524,7 +556,9 @@ async function main() {
     messages.push({ role: 'user', content: input });
     ac = new AbortController();
     try {
-      await runTurn({ messages, model: config.model, signal: ac.signal, approve, mcp, auto: isAuto() });
+      await runTurn({
+        messages, model: config.model, signal: ac.signal, approve, grant, mcp, auto: isAuto(),
+      });
     } catch (e) {
       if (e.name === 'AbortError') messages.push({ role: 'assistant', content: '(interrupted)' });
       else console.error(c.red(`\n  ${e.message}`));

package/src/sandbox.js

@@ -37,9 +37,13 @@ export const cacheDirs = (home) => CACHE_DIRS.map((d) => join(home, d));
  * exfiltrates whichever credential store was not on it.
  *
  * So the default is narrow and covers material that is pivot-grade and never
- * legitimately read by a build. Session tokens for CLIs you are already logged
- * in to stay readable — add them with KRONK_SANDBOX_DENY if your threat model
- * wants them gone, at the cost of those commands failing.
+ * legitimately read by a build. Session tokens that CLIs keep in their own
+ * config directories — `~/.config/gh`, `~/.aws`, `~/.kube` — stay readable. A
+ * token in the macOS keychain does not: `Library/Keychains` is on the list
+ * below, which is why `gh` reports a login failure here even though it is
+ * logged in. That is what the `readable` grant exists to lift, one path at a
+ * time and without granting writes. Add more with KRONK_SANDBOX_DENY if your
+ * threat model wants them gone, at the cost of those commands failing.
  *
  * The write confinement is the half that holds categorically. This half is
  * best-effort, and the README says so.
@@ -66,7 +70,7 @@ const sb = (p) => `"${p.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
  * dylib, locale file and device node a toolchain touches, and getting that wrong
  * fails closed in ways that look like a broken CLI rather than a blocked write.
  */
-export function seatbeltProfile({ root, home, tmp, allow = [], deny = [] }) {
+export function seatbeltProfile({ root, home, tmp, allow = [], deny = [], readable = [] }) {
   const writable = [root, '/dev', '/private/tmp', '/private/var/tmp', '/private/var/folders', '/tmp']
     .concat(tmp ? [tmp] : [])
     .concat(cacheDirs(home))
@@ -75,8 +79,14 @@ export function seatbeltProfile({ root, home, tmp, allow = [], deny = [] }) {
   // ALLOW means "this path is fully available", so it also lifts a default
   // denial. Without that there is no way to run a keychain-backed CLI like `gh`
   // short of turning the sandbox off entirely, which is a worse trade.
+  //
+  // `readable` lifts the same denial and stops there — note it is absent from
+  // `writable` above. Reading a credential store is what a logged-in CLI needs;
+  // writing to one is what an attacker needs, and handing over the second to
+  // obtain the first is the trade this parameter exists to refuse.
+  const lifted = allow.concat(readable);
   const unreadable = SECRET_DIRS.map((d) => join(home, d)).concat(deny)
-    .filter((d) => !allow.some((a) => d === a || d.startsWith(`${a}/`)));
+    .filter((d) => !lifted.some((a) => d === a || d.startsWith(`${a}/`)));
 
   return [
     '(version 1)',
@@ -99,7 +109,7 @@ export function seatbeltProfile({ root, home, tmp, allow = [], deny = [] }) {
  * shape that matches what the README promises, and it is what seatbelt does on
  * the other side.
  */
-export function bwrapArgs({ root, home, cwd, tmp, allow = [], deny = [] }) {
+export function bwrapArgs({ root, home, cwd, tmp, allow = [], deny = [], readable = [] }) {
   // /dev and /proc must be fresh mounts: a read-only bind of the host's would
   // leave a shell unable to write to its own stdout or read /proc/self.
   const args = ['--die-with-parent', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc'];
@@ -121,8 +131,14 @@ export function bwrapArgs({ root, home, cwd, tmp, allow = [], deny = [] }) {
   // A tmpfs makes a credential directory exist but be empty; /dev/null over a
   // file makes it readable and empty. Both beat a missing path, which tools
   // report as a confusing ENOENT rather than an obvious denial.
+  // A `readable` path is simply left out of this loop. It needs no bind of its
+  // own: `--ro-bind / /` above already made the whole filesystem readable, so
+  // not hiding it *is* the grant. An explicit `--ro-bind` would be redundant,
+  // and worse, would read as though write access were being withheld by that
+  // line rather than never offered — so there is none.
+  const lifted = allow.concat(readable);
   const hidden = SECRET_DIRS.map((x) => join(home, x)).concat(deny)
-    .filter((d) => !allow.some((a) => d === a || d.startsWith(`${a}/`)));
+    .filter((d) => !lifted.some((a) => d === a || d.startsWith(`${a}/`)));
   for (const d of hidden) {
     if (existsSync(d) && statSync(d).isDirectory()) args.push('--tmpfs', d);
   }
@@ -153,16 +169,19 @@ export function detectBackend({ platform = process.platform, env = process.env }
  * Build the argv that runs `script` under `backend`.
  * Returns `['bash', ['-c', script]]` shaped output for spawn().
  */
-export function sandboxArgv(script, { backend, root, home, cwd, tmp, env = process.env }) {
+export function sandboxArgv(
+  script,
+  { backend, root, home, cwd, tmp, env = process.env, readable = [] },
+) {
   const allow = extraPaths(env.KRONK_SANDBOX_ALLOW, home);
   const deny = extraPaths(env.KRONK_SANDBOX_DENY, home);
 
   if (backend === 'seatbelt') {
     return ['sandbox-exec',
-      ['-p', seatbeltProfile({ root, home, tmp, allow, deny }), 'bash', '-c', script]];
+      ['-p', seatbeltProfile({ root, home, tmp, allow, deny, readable }), 'bash', '-c', script]];
   }
   if (backend === 'bwrap') {
-    return ['bwrap', [...bwrapArgs({ root, home, cwd, tmp, allow, deny }), '-c', script]];
+    return ['bwrap', [...bwrapArgs({ root, home, cwd, tmp, allow, deny, readable }), '-c', script]];
   }
   return ['bash', ['-c', script]];
 }

package/src/tools.js

@@ -1,10 +1,11 @@
 import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { promisify } from 'node:util';
-import { resolve, relative, dirname, basename, isAbsolute } from 'node:path';
-import { realpathSync, mkdirSync } from 'node:fs';
+import { resolve, relative, dirname, basename, isAbsolute, join } from 'node:path';
+import { realpathSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { detectBackend, sandboxArgv, cacheDirs } from './sandbox.js';
+import { config } from './config.js';
 import { setPlan, MAX_ITEMS } from './plan.js';
 import { c } from './ui.js';
 
@@ -21,7 +22,130 @@ const TOOL_TIMEOUT = Number(process.env.KRONK_TOOL_TIMEOUT ?? 900) * 1000;   //
  * re-running `pwd` and `cd` trying to work out where it is. We keep the cwd
  * here and hand it back to every subsequent call.
  */
-export const session = { root: real(process.cwd()), cwd: real(process.cwd()) };
+export const session = {
+  root: real(process.cwd()),
+  cwd: real(process.cwd()),
+  // Paths granted read-only to the sandbox for the rest of this run, and paths
+  // the user was asked about and said no to. Both are needed: without
+  // `declined`, a refusal would be re-asked on the very next command, which is
+  // how a prompt trains people to stop reading it.
+  //
+  // The seatbelt profile is rebuilt per command — `runBash` calls `sandboxArgv`
+  // every time — so adding to this set takes effect on the next command with no
+  // restart. That is what makes asking at the moment of need possible at all.
+  grants: new Set(config.sandboxReadable),
+  declined: new Set(),
+};
+
+/**
+ * Credential stores a tool needs to read, and cannot reach under the sandbox.
+ *
+ * Deliberately tiny, and grown only on measurement. Under the denied profile on
+ * macOS, `kubectl config current-context` and `aws configure list` both exit 0 —
+ * their tokens live in their own config directories, which are readable — so
+ * neither belongs here. `heroku` uses `~/.netrc` and `vault` uses
+ * `~/.vault-token`; both are SECRET_FILES rather than SECRET_DIRS, and this
+ * makes no file grantable, so neither belongs here either.
+ *
+ * A speculative entry would prompt for something that was never denied, which
+ * is worse than not prompting: it teaches the user that the question is noise.
+ */
+export const CREDENTIAL_TOOLS = {
+  gh: ['Library/Keychains'],        // verified: fails denied, succeeds granted
+  docker: ['Library/Keychains'],    // unverified; credsStore: "desktop" uses the keychain
+};
+
+/**
+ * Which known binaries a command line actually runs.
+ *
+ * Split on the separators that start a new command, then take the first token
+ * of each segment after stepping over leading `NAME=value` assignments. That is
+ * a heuristic and is meant to be: its only outputs are "ask" and "do not ask",
+ * so a miss costs one un-asked question and a false hit costs one declined
+ * prompt. It never rewrites, blocks or delays the command.
+ *
+ * `echo gh` must not match — `gh` is an argument there, not the command — and
+ * neither must `mygh`, which is why the first token is compared whole.
+ */
+export function credentialMatches(cmd, home = homedir()) {
+  const hits = new Map();
+  for (const segment of String(cmd ?? '').split(/[;&|\n]+/)) {
+    const tokens = segment.trim().split(/\s+/).filter(Boolean);
+    let i = 0;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+    if (!tokens[i]) continue;
+    const bin = basename(tokens[i]);
+    const paths = CREDENTIAL_TOOLS[bin];
+    if (paths && !hits.has(bin)) hits.set(bin, paths.map((rel) => join(home, rel)));
+  }
+  return [...hits].map(([bin, paths]) => ({ bin, paths }));
+}
+
+/** Just the paths, deduplicated across however many tools matched. */
+export function credentialPaths(cmd, home = homedir()) {
+  return [...new Set(credentialMatches(cmd, home).flatMap((m) => m.paths))];
+}
+
+/**
+ * The paths this command needs that are denied right now — nothing to ask about
+ * when the sandbox is off, when they are already granted, or when the path does
+ * not exist on this machine, which is what keeps Linux silent about a macOS
+ * keychain.
+ */
+export function ungranted(cmd, { home = homedir(), backend = sandbox.backend } = {}) {
+  if (backend === 'none' || backend === 'pending') return [];
+  return credentialPaths(cmd, home)
+    .filter((p) => !session.grants.has(p) && existsSync(p));
+}
+
+/**
+ * What this command would need asking about: denied, not granted, and not
+ * already refused this session. Empty means say nothing and run it.
+ *
+ * `declined` is filtered here rather than at the call site so that "ask at most
+ * once per path per session" is one rule in one place, true of a refusal
+ * exactly as it is of a grant.
+ */
+export function grantsNeeded(cmd, opts = {}) {
+  return ungranted(cmd, opts).filter((p) => !session.declined.has(p));
+}
+
+/**
+ * Record a grant, and optionally remember it past this session.
+ *
+ * Persisting is a read-modify-write of `~/.kronk-cli.json` rather than a
+ * rewrite: the file is the user's, and it holds their model, their base URL and
+ * whatever else they have set. Losing those to record a keychain path would be
+ * a bad trade for a convenience feature. A file that cannot be parsed is left
+ * alone and reported, never silently replaced.
+ *
+ * Returns the path written to, or null when nothing was persisted.
+ */
+export function rememberGrants(paths, { persist = false, home = homedir() } = {}) {
+  for (const p of paths) {
+    session.grants.add(p);
+    session.declined.delete(p);
+  }
+  if (!persist || !paths.length) return null;
+
+  const tilde = (p) => (p.startsWith(`${home}/`) ? `~/${p.slice(home.length + 1)}` : p);
+  let current = {};
+  try { current = JSON.parse(readFileSync(config.rcPath, 'utf8')); }
+  catch (e) {
+    if (e.code !== 'ENOENT') throw new Error(`${config.rcPath} is not valid JSON — leaving it alone`, { cause: e });
+  }
+  const merged = [...new Set([
+    ...(Array.isArray(current.sandboxReadable) ? current.sandboxReadable : []),
+    ...paths.map(tilde),
+  ])];
+  writeFileSync(config.rcPath, `${JSON.stringify({ ...current, sandboxReadable: merged }, null, 2)}\n`);
+  return config.rcPath;
+}
+
+/** Remember a refusal, so the same command does not ask again this session. */
+export function declineGrants(paths) {
+  for (const p of paths) session.declined.add(p);
+}
 
 /**
  * Resolve symlinks before comparing paths.
@@ -186,6 +310,31 @@ function applyCwd(out, mark) {
   return { body, pwd: next, escaped };
 }
 
+/**
+ * One line telling the model that a sandbox denial is the likely cause, when it
+ * actually is.
+ *
+ * The gate is narrow on purpose: this fires only when the failing command named
+ * a tool in CREDENTIAL_TOOLS *and* the path it needs is still ungranted.
+ * Loosening it to "the sandbox denies something" would fire on every failing
+ * `npm test` and every failing build, because SECRET_FILES are denied
+ * unconditionally under any active backend — something is always denied. A hint
+ * that appears on every failure teaches the model to blame the sandbox for
+ * ordinary bugs, which is worse than no hint at all.
+ *
+ * KRONK_SANDBOX_ALLOW is deliberately not suggested here. It is the read-write
+ * hatch the grant prompt exists to replace.
+ */
+export function credentialHint(cmd, opts = {}) {
+  const denied = ungranted(cmd, opts);
+  if (!denied.length) return null;
+  const home = opts.home ?? homedir();
+  const tilde = (p) => (p.startsWith(`${home}/`) ? `~/${p.slice(home.length + 1)}` : p);
+  const match = credentialMatches(cmd, home).find((m) => m.paths.some((p) => denied.includes(p)));
+  return `note: the sandbox denies reads of ${denied.map(tilde).join(', ')}, which `
+    + `${match?.bin ?? 'this command'} uses. Re-run and allow it if this failed on credentials.`;
+}
+
 /** The directory a command ran in, and a warning when that was outside the root. */
 function whereLines(pwd, escaped) {
   const ran = pwd ? `ran in: ${pwd}` : `ran in: ${session.cwd} (final directory unknown)`;
@@ -234,6 +383,7 @@ export function resolveSandbox({ platform = process.platform, env = process.env
 
   const [bin, argv] = sandboxArgv('exit 0', {
     backend: wanted, root: session.root, home: homedir(), cwd: session.cwd, tmp: real(tmpdir()),
+    readable: [...session.grants],
   });
   const probe = spawnSync(bin, argv, { stdio: 'ignore', timeout: 10_000 });
 
@@ -273,8 +423,13 @@ export function runBash(cmd, { onProgress, timeoutMs = TOOL_TIMEOUT } = {}) {
       return resolve(`error: refusing to run unconfined — KRONK_SANDBOX=strict and ${sandbox.reason}.`);
     }
 
+    // Read straight from module state rather than from `opts`. The profile is
+    // rebuilt here on every command, so a grant made a moment ago is in force
+    // now; threading it through the caller would add a second route for the
+    // same fact, and the two would eventually disagree.
     const [bin, argv] = sandboxArgv(script, {
       backend, root: session.root, home: homedir(), cwd: session.cwd, tmp: real(tmpdir()),
+      readable: [...session.grants],
     });
     const child = spawn(bin, argv, {
       cwd: session.cwd,
@@ -338,13 +493,19 @@ export function runBash(cmd, { onProgress, timeoutMs = TOOL_TIMEOUT } = {}) {
         err.trim() && `stderr:\n${err.trim()}`,
       ].filter(Boolean).join('\n\n');
 
+      // Right after `error:` and `ran in:`, never appended at the end: the tool
+      // result is capped for display, and a hint below the cap is a hint the
+      // reader never sees.
+      const hint = credentialHint(cmd);
+
       if (timedOut) {
         return resolve(clip([
           `error: killed after ${secs}s (timeout ${Math.round(timeoutMs / 1000)}s).`,
           'The command may simply be slow — re-run a narrower scope, or raise KRONK_TOOL_TIMEOUT.',
           ...where,
+          hint,
           tail || '(no output before it was killed)',
-        ].join('\n')));
+        ].filter(Boolean).join('\n')));
       }
       if (code === 0) {
         const okBody = clip(body + err);
@@ -359,6 +520,7 @@ export function runBash(cmd, { onProgress, timeoutMs = TOOL_TIMEOUT } = {}) {
           ? `error: killed by ${signal} after ${secs}s`
           : `error: exit code ${code} after ${secs}s`,
         ...where,
+        hint,
         tail || '(no output)',
         truncated ? '[earlier output dropped]' : '',
       ].filter(Boolean).join('\n')));