Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* The wall catalog (design 4.10): seven errors that a command keeps hitting
* on a machine for reasons outside the code, each with the fix a person
* wrote, appended to the agent's context when the error comes back.
*
* A class matches only on its own line-anchored patterns, in the first and
* last 4 KB of the result, never inside quoted or JSON-escaped output (D147:
* a printed record of another session), and (for four classes) only when a segment of the
* command runs the program the error belongs to (R28): a log printed by
* `cat`, or an `echo` an agent writes, matches nothing.
*
* The fix texts are constants. Nothing from the command's output reaches
* them; the only value put in is the remote's SSH address, rebuilt from its
* https URL and checked. They read as information about the failed command
* (D88): Trail is the tool the person installed, this is the error it knows,
* and this command usually fixes it, because. They never tell the agent what
* to say.
*
* Pure. Not on the PreToolUse fast path.
*/
import { flatLine } from '../notes/flatten.js';
import { WALL_CLASSES } from '../notes/learning-fields.js';
import { isLookOnly } from './shell.js';
import { afterTimeout, shellScript, simpleCommands } from './shell-words.js';
import { ASSIGN, base, words } from './shell-scan.js';
import { globWallTied } from './walls-glob.js';
import { unquotedMatch } from './walls-quoted.js';
import type { WallClass } from './types.js';
export interface WallCtx {
hasProgram(p: string): boolean;
/** The remote's SSH address (sshRemoteFor), or null. */
remoteSsh: string | null;
}
export interface WallEntry {
cls: WallClass;
/** Line-anchored patterns, tried on the first and last 4 KB of the result (4.10). */
patterns: readonly RegExp[];
/** Programs one of whose segments must be in the command for the class to match, or null for any (R28). */
programs: readonly string[] | null;
/** Fixed words naming the wall, for offers and the screen. */
words: string;
/** The human-written fix (4.10 table). ctx says which form applies (colima on PATH, the remote's ssh form). */
fix(ctx: WallCtx): string;
/** A guardrail init may offer for it, or null. */
guardrail: { title: string; text: string; fileName: string; check?: 'no-timeout'; applies: 'every repo' | 'this repo' } | null;
}
/** Where a shell puts its name before its own error: `zsh:1: `, `bash: line 3: `, `bash: `, `(eval):1: `, `/bin/zsh:1: `. */
const SHELL = String.raw`(?:(?:\/[\w./-]*\/)?(?:zsh|bash|sh)(?::\d+)?:(?: line \d+:)? |\(eval\):\d+: )?`;
const at = (body: string) => new RegExp(`^${SHELL}${body}`, 'm');
const DOCKER_ENV = 'DOCKER_HOST=unix://$HOME/.colima/default/docker.sock TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock TESTCONTAINERS_RYUK_DISABLED=true';
/** The parts every fix line shares (b7 holds them to the words rules with the other copy constants). */
export const WALL_COPY: Record<string, string> = {
lead: '[trail] Trail, the tool this person installed, recognizes this error',
lastTime: '[trail] What fixed this here before (a lesson this person kept in Trail, worked on {date1} and {date2}): {lesson}',
};
const lead = (what: string, words: string) => `${WALL_COPY.lead}${what}: ${words}.`;
export const WALLS: readonly WallEntry[] = Object.freeze([
{
cls: 'timeout-missing',
patterns: [at(String.raw`command not found: timeout\s*$`), at(String.raw`timeout: command not found\s*$`)],
programs: ['timeout'],
words: '"timeout: command not found"',
fix: () => `${lead(' from the timeout command', '"timeout: command not found"')} This Mac has no timeout program. `
+ "The usual fix is the same command without timeout, using the Bash tool's own timeout parameter or run_in_background, since neither needs that program.",
guardrail: {
title: 'No timeout on this Mac', fileName: 'no-timeout.md', check: 'no-timeout', applies: 'every repo',
text: "This Mac has no `timeout`. Run long commands in the background, or use the Bash tool's own timeout.",
},
},
{
cls: 'zsh-no-match',
patterns: [/^(?:(?:\/[\w./-]*\/)?zsh|\(eval\)):\d*:? no matches found: /m],
programs: null,
words: 'zsh "no matches found"',
fix: () => `${lead('', 'zsh "no matches found"')} zsh expanded an unquoted glob before the command ran. `
+ "The usual fix is to quote that argument ('...*...') or put noglob in front of the command, so the glob reaches the program as written.",
guardrail: null,
},
{
cls: 'git-https-auth',
patterns: [at("fatal: could not read Username for 'https://"), /^remote: Invalid username or password/m, /^(?:fatal: )?Authentication failed for 'https:\/\//m],
programs: ['git', 'gh'],
words: 'the HTTPS push asking for a username',
fix: (ctx) => {
const ssh = goodSsh(ctx.remoteSsh);
const push = ssh
? `The usual fix is git push ${ssh} HEAD, because an SSH push uses this machine's SSH key, not HTTPS credentials.`
: "The usual fix is to push to the remote's SSH address (git@host:owner/repo.git), because an SSH push uses this machine's SSH key, not HTTPS credentials.";
const gh = ctx.hasProgram('gh') ? ' gh auth setup-git, run once by the person in their own terminal, also fixes it.' : '';
return `${lead(' from git', 'the HTTPS push asking for a username')} This remote is HTTPS and git has no credentials for it here. ${push}${gh}`;
},
guardrail: {
title: 'Push over SSH in this repo', fileName: 'push-over-ssh.md', applies: 'this repo',
text: "This repo's remote is HTTPS and git has no credentials for it here. Push over SSH, to the remote's git@ address.",
},
},
{
cls: 'docker-rootless',
// Anywhere on a line (a test runner's `Failed to get provider: ...`), so the match starts at the error's words.
patterns: [/\brootless Docker not found\b/m, /\bCannot connect to the Docker daemon at unix:\/\//m],
programs: null,
words: '"rootless Docker not found"',
fix: (ctx) => ctx.hasProgram('colima')
? `${lead(' from Docker', '"rootless Docker not found"')} Docker on this Mac runs in Colima. The usual fix is colima start if it isn't running, `
+ `then the same command with ${DOCKER_ENV} in front, because test tools look for Docker's default socket and Colima's is elsewhere.`
: `${lead(' from Docker', '"rootless Docker not found"')} No Docker daemon is running here. It needs Docker Desktop or Colima started on this machine, `
+ 'which is the person\'s step; after that the same command usually works, since only the daemon was missing.',
guardrail: null,
},
{
cls: 'npm-e401-eotp',
patterns: [/^npm (?:ERR!|error) code (?:E401|EOTP|ENEEDAUTH)\b/m],
programs: ['npm', 'npx', 'pnpm', 'yarn'],
words: 'npm asking for a login or one-time password',
fix: () => `${lead(' from npm', 'npm asking for a login or one-time password')} Only the person can give npm a fresh login or a one-time password, `
+ 'so the same npm command fails the same way until then. The usual fix is npm login, or the publish itself, run by the person in their own terminal.',
guardrail: null,
},
{
cls: 'claude-not-logged-in',
patterns: [/^(?:Error: )?Invalid API key · Please run \/login/m, /^(?:Error: )?Failed to authenticate\b/m, /^(?:Error: )?OAuth session expired\b/m],
programs: ['claude'],
words: 'claude not signed in',
fix: () => `${lead(' from the claude CLI', 'claude not signed in')} The claude CLI isn't signed in on this terminal, `
+ 'so the same claude command fails the same way until it is. The usual fix is the person running claude in their own terminal and signing in there.',
guardrail: null,
},
{
cls: 'enospc',
patterns: [/(?:^|: )[Nn]o space left on device\b/m, /(?:^|Error: |code )ENOSPC\b/m],
programs: null,
words: '"No space left on device"',
fix: () => `${lead('', '"No space left on device"')} The disk is full, so writes fail whatever the command is. `
+ 'df -h . shows what is left; the usual fix is freeing space, and which files go is the person\'s call, since deleting can\'t be undone.',
guardrail: null,
},
] satisfies WallEntry[]) as readonly WallEntry[];
const BY_CLASS = new Map(WALLS.map((w) => [w.cls, w]));
/** Classes matched on a command that exited 0 (P23): the three that hide behind `| tail` in the corpus. */
const EXIT_ZERO: ReadonlySet<WallClass> = new Set(['timeout-missing', 'zsh-no-match', 'docker-rootless']);
const END = 4 * 1024;
const MAX_CHAIN = 16;
const MAX_DEPTH = 4;
/** A longer command is no wall: parsing it would cost more than the hook has (2 MB took 0.9 s), and no real one is this long. */
const MAX_COMMAND = 64 * 1024;
/** A colour or cursor code (CSI): npm and git colour their error lines under FORCE_COLOR. */
const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
/**
* Programs that only print what they were given or read. A command made of these alone (and no redirect, so
* look-only) can't hit the disk or Docker: an error it shows is quoted from a log, a README or an echo (planted text).
*/
const PRINTERS: ReadonlySet<string> = new Set([
'echo', 'printf', 'cat', 'head', 'tail', 'grep', 'egrep', 'fgrep', 'rg', 'less', 'more', 'wc', 'true', 'false',
'exit', 'return', 'test', '[', '[[', ':', 'cd', 'pwd', 'sleep',
]);
/** An SSH remote as sshRemoteFor makes them: `git@host:owner/repo.git`, plain characters only. */
const SSH_REMOTE = /^git@[A-Za-z0-9.-]{1,253}:[A-Za-z0-9._-]{1,100}(?:\/[A-Za-z0-9._-]{1,100}){1,4}\.git$/;
/** No part may start with '-': git and ssh would read `git@-oProxyCommand…` or `:-upload-pack…` as an option. */
const goodSsh = (s: string | null) => (typeof s === 'string' && SSH_REMOTE.test(s) && !s.includes('..') && !/[@:/.]-/.test(s) ? s : null);
/** `https://host/owner/repo(.git)` to `git@host:owner/repo.git`; never a user or token; null for anything else. */
export function sshRemoteFor(url: string): string | null {
const m = /^https:\/\/(?:[^@/\s]+@)?([A-Za-z0-9.-]{1,253})\/([A-Za-z0-9._-]{1,100}(?:\/[A-Za-z0-9._-]{1,100}){1,4}?)(?:\.git)?\/?$/.exec(String(url ?? '').trim());
if (!m) return null;
return goodSsh(`git@${m[1]}:${m[2]!.replace(/\.git$/, '')}.git`);
}
/** The words after one wrapper (time, nohup, env, sudo, timeout, ...), or null when `w` doesn't start with one. */
function unwrap(w: string[]): string[] | null {
const p = w[0];
if (p === 'time') return w.slice(w[1] === '-p' ? 2 : 1);
if (p === 'nohup' || p === '!' || p === 'exec' || p === 'noglob' || p === 'caffeinate') return w.slice(1);
if (p === 'command') return w[1] && !w[1].startsWith('-') ? w.slice(1) : null;
if (p === 'nice') return w.slice(w[1] === '-n' ? 3 : w[1]?.startsWith('-') ? 2 : 1);
if (p === 'timeout' || p === 'gtimeout') return afterTimeout(w);
if (p === 'env' || p === 'sudo' || p === 'doas') {
let i = 1;
while (i < w.length && (w[i]!.startsWith('-') || ASSIGN.test(w[i]!))) i += /^-[uCgDhprtUT]$/.test(w[i]!) ? 2 : 1;
return w.slice(i);
}
return null;
}
/** Every program a simple command runs through its wrappers, and inside `sh -c '...'`. */
function programsOf(simple: string, depth: number, out: Set<string>): void {
let w = words(simple);
for (let n = 0; n < MAX_CHAIN && w.length; n++) {
while (w.length && ASSIGN.test(w[0]!)) w = w.slice(1);
if (!w.length) return;
out.add(base(w[0]!));
const script = shellScript(w);
if (script !== null) {
if (depth < MAX_DEPTH) for (const s of simpleCommands(script)) programsOf(s, depth + 1, out);
return;
}
const next = unwrap(w);
if (!next) return;
w = next;
}
}
function programsIn(command: string): Set<string> {
const out = new Set<string>();
for (const s of simpleCommands(command)) programsOf(s, 0, out);
return out;
}
/** The command outside its quotes and escapes, in one pass (a regex over nested quotes can backtrack). */
function unquoted(command: string): string {
let out = '';
let q = '';
for (let i = 0; i < command.length; i++) {
const c = command[i]!;
if (q === "'") { if (c === "'") q = ''; continue; }
if (c === '\\') { i++; continue; }
if (q === '"') { if (c === '"') q = ''; continue; }
if (c === "'" || c === '"') { q = c; continue; }
out += c;
}
return out;
}
/**
* The first and last 4 KB of the result, colour codes gone. A line the window's edge cuts is no line: the tail
* window starts at its first whole line, and the head window's cut end is kept off a line end (NUL before the
* joining newline), so `^` and `$` see only real line edges.
*/
function windows(result: string): string {
if (result.length <= 2 * END) return result.replace(ANSI, '');
const head = result.slice(0, END);
let tail = result.slice(-END);
const before = result[result.length - END - 1];
if (before !== '\n' && before !== '\r') {
const nl = tail.search(/[\r\n]/);
tail = nl < 0 ? '' : tail.slice(nl + 1);
}
return `${head}\u0000\n${tail}`.replace(ANSI, '');
}
/** Null unless one class matches. `failed` false means the command exited 0 (P23 limits apply). */
export function matchWall(result: string, command: string, failed: boolean): WallClass | null {
try {
if (typeof result !== 'string' || typeof command !== 'string' || !result || command.length > MAX_COMMAND) return null;
const ends = windows(result);
// The patterns first: they read at most 8 KB, and most results match none, so the command is parsed only for a hit.
// A match inside quoted or JSON-escaped output (a printed record of another session) is no hit (D147).
const hits = WALLS.filter((w) => (failed || EXIT_ZERO.has(w.cls)) && w.patterns.some((re) => unquotedMatch(re, ends)));
if (!hits.length) return null;
const look = isLookOnly(command);
if (!failed && look) return null;
const programs = programsIn(command);
// Planted text: a look-only command made only of printers shows an error, it doesn't hit one (zsh's own glob aside).
const printsOnly = look && programs.size > 0 && [...programs].every((p) => PRINTERS.has(p));
for (const w of hits) {
if (w.programs && !w.programs.some((p) => programs.has(p))) continue;
if (w.cls === 'zsh-no-match') {
// zsh says it only for a glob the command itself left unquoted, and it is a wall only when that glob was
// never a file path: a flag's value, a URL or query, a git grep/log/diff pathspec, a grep pattern (D147).
if (!/[*?[]/.test(unquoted(command)) || !globWallTied(ends, command)) continue;
} else if (!w.programs && printsOnly) continue;
return w.cls;
}
return null;
} catch {
return null;
}
}
/** '[trail] Trail, the tool this person installed, recognizes this error ...' (4.10, D88); '' for an unknown class. */
export function wallFixText(cls: WallClass, ctx: WallCtx): string {
const w = BY_CLASS.get(cls);
if (!w) return '';
try {
return w.fix(ctx);
} catch {
return w.fix({ hasProgram: () => false, remoteSsh: null });
}
}
const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
const shortDay = (d: string) => {
const m = DAY.exec(d)!;
return `${MONTHS[Number(m[2]) - 1] ?? m[2]} ${Number(m[3])}`;
};
/**
* '[trail] What fixed this here before (...worked on {date1} and {date2}): {lesson text}', only when the lesson
* worked on 2 or more days given as local dates (4.10); the newest two are said. '' otherwise.
*/
export function lastTimeText(lessonText: string, workedOn: string[]): string {
// Only real days count as epochs: junk in the list is no second epoch.
const valid = (Array.isArray(workedOn) ? workedOn : []).filter((d) => typeof d === 'string' && DAY.test(d));
const days = [...new Set(valid)].sort();
const text = flatLine(lessonText, 200);
if (!text || valid.length < 2) return '';
const [d1, d2] = days.slice(-2);
if (!d1) return '';
// Two epochs on one day: 'worked twice on Oct 2'.
const when = d2 ? WALL_COPY.lastTime! : WALL_COPY.lastTime!.replace('on {date1} and {date2}', 'twice on {date1}');
// Functions, so a `$'` or `$&` in the lesson is text, not a replacement pattern.
return when.replace('{date1}', () => shortDay(d1)).replace('{date2}', () => (d2 ? shortDay(d2) : '')).replace('{lesson}', () => text);
}
// The catalog and the closed list agree (a test holds them equal too).
if (WALLS.map((w) => w.cls).join() !== WALL_CLASSES.join()) throw new Error('walls.ts: the catalog and WALL_CLASSES differ');