Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 76 additions & 23 deletions .agents/scripts/shell-words.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,48 @@
// `$VAR` the guard cannot read, `stdin` is a heredoc or here-string body (null when none), and
// `redirects` are `{ op, target }` pairs. The words of a `$(…)` or backtick substitution become
// commands of their own. A `$(cat <<'EOF' … EOF)` inside a word is read as its heredoc body. It
// never throws: input it cannot follow ends the command it is in. `commandWords(cmd)` is a
// never throws: input it cannot follow ends the command it is in. A `$VAR` or `${VAR}` reads as
// its value when the call sets VAR once, to a literal, in a command of its own before the use
// (`F=/tmp/body.md; gh pr comment 5 --body-file "$F"`). `commandWords(cmd)` is a
// command's words from the program name on, without leading `VAR=value` assignments, wrappers
// (`env`, `time`, ...) or a `timeout <n>`.
export function parseShell(command) {
const commands = [];
parseInto(String(command ?? ""), commands);
return commands;
const src = String(command ?? "");
const scan = { commands: [], once: new Set(), vars: new Map() };
parseInto(src, scan);
const ctx = { commands: [], once: setOnce(scan.commands), vars: new Map() };
parseInto(src, ctx);
return ctx.commands;
}

const NAME_SETTERS = new Set([
"for",
"select",
"read",
"local",
"declare",
"typeset",
"readonly",
"getopts",
"mapfile",
"readarray",
"unset",
]);

// why: a name the call sets twice, or through `read`, a loop or a declaration, has a value only
// the shell knows; one set once has the value its assignment shows.
function setOnce(commands) {
const count = new Map();
const bump = (name, by) => count.set(name, (count.get(name) ?? 0) + by);
for (const { words } of commands) {
const declares = words.some((w) => NAME_SETTERS.has(w));
for (const word of words) {
const name = /^(\w+)\+?=/.exec(word)?.[1];
if (name !== undefined) bump(name, 1);
else if (declares && /^\w+$/.test(word)) bump(word, 2);
}
}
return new Set([...count].filter(([, n]) => n === 1).map(([name]) => name));
}

const WRAPPERS = new Set(["time", "nice", "env", "command", "exec", "nohup"]);
Expand All @@ -33,24 +68,24 @@ const SCANNERS = [
{ at: (p) => p.src[p.i] === "'", scan: singleQuoted },
{
at: (p) => p.src[p.i] === '"',
scan: (p) => (p.i = readDoubleQuoted(p.src, p.i + 1, current(p), p.commands)),
scan: (p) => (p.i = readDoubleQuoted(p.src, p.i + 1, current(p), p.ctx)),
},
{
at: (p) => p.src[p.i] === "$",
scan: (p) => (p.i = readDollar(p.src, p.i, current(p), p.commands)),
scan: (p) => (p.i = readDollar(p.src, p.i, current(p), p.ctx)),
},
{
at: (p) => p.src[p.i] === "`",
scan: (p) => (p.i = readBacktick(p.src, p.i, current(p), p.commands)),
scan: (p) => (p.i = readBacktick(p.src, p.i, current(p), p.ctx)),
},
{ at: (p) => p.src.startsWith("<<<", p.i), scan: hereString },
{ at: (p) => p.src.startsWith("<<", p.i), scan: heredoc },
{ at: (p) => /^(?:[<>]|&>)/.test(p.src.slice(p.i, p.i + 2)), scan: redirect },
{ at: (p) => ";|&()".includes(p.src[p.i]), scan: separator },
];

function parseInto(src, commands) {
const p = { src, commands, i: 0, cmd: newCommand(), word: null, redirectOp: null, pending: [] };
function parseInto(src, ctx) {
const p = { src, ctx, i: 0, cmd: newCommand(), word: null, redirectOp: null, pending: [] };
while (p.i < src.length) {
const scanner = SCANNERS.find((s) => s.at(p));
if (scanner === undefined) current(p).text += src[p.i++];
Expand Down Expand Up @@ -80,10 +115,23 @@ function endCommand(p) {
endWord(p);
p.redirectOp = null;
const { cmd } = p;
if (cmd.words.length > 0 || cmd.redirects.length > 0 || cmd.stdin !== null) p.commands.push(cmd);
rememberAssignments(p.ctx, cmd);
if (cmd.words.length > 0 || cmd.redirects.length > 0 || cmd.stdin !== null)
p.ctx.commands.push(cmd);
p.cmd = newCommand();
}

// why: `F=x` alone on a command sets a shell variable; before a program it sets only that
// program's environment, after the shell has expanded the command's own `$F`.
function rememberAssignments(ctx, cmd) {
const from = cmd.words[0] === "export" ? 1 : 0;
const assigned = cmd.words.slice(from).map((word) => /^(\w+)=([\s\S]*)$/.exec(word));
if (assigned.includes(null)) return;
assigned.forEach((found, i) => {
if (ctx.once.has(found[1]) && !cmd.dynamic[from + i]) ctx.vars.set(found[1], found[2]);
});
}

function newline(p) {
endCommand(p);
p.i++;
Expand Down Expand Up @@ -184,16 +232,16 @@ function newCommand() {
return { words: [], dynamic: [], stdin: null, stdinDynamic: false, redirects: [] };
}

function readDoubleQuoted(src, i, word, commands) {
function readDoubleQuoted(src, i, word, ctx) {
while (i < src.length && src[i] !== '"') {
const c = src[i];
if (c === "\\" && /[$`"\\\n]/.test(src[i + 1] ?? "")) {
if (src[i + 1] !== "\n") word.text += src[i + 1];
i += 2;
} else if (c === "$") {
i = readDollar(src, i, word, commands);
i = readDollar(src, i, word, ctx);
} else if (c === "`") {
i = readBacktick(src, i, word, commands);
i = readBacktick(src, i, word, ctx);
} else {
word.text += c;
i++;
Expand All @@ -213,23 +261,23 @@ const DOLLARS = [
{ at: (next) => /[\w@*#?$!-]/.test(next), read: dollarName },
];

function readDollar(src, i, word, commands) {
function readDollar(src, i, word, ctx) {
const next = src[i + 1] ?? "";
const reader = DOLLARS.find((d) => d.at(next));
if (reader !== undefined) return reader.read(src, i, word, commands);
if (reader !== undefined) return reader.read(src, i, word, ctx);
word.text += "$";
return i + 1;
}

function dollarParen(src, i, word, commands) {
function dollarParen(src, i, word, ctx) {
const doc = CAT_HEREDOC.exec(src.slice(i));
if (doc !== null) {
word.text += doc[3];
if (doc[1] === "" && /[$`]/.test(doc[3])) word.dynamic = true;
return i + doc[0].length;
}
const end = matchingParen(src, i + 2);
parseInto(src.slice(i + 2, end), commands);
parseInto(src.slice(i + 2, end), ctx);
word.dynamic = true;
return end + 1;
}
Expand All @@ -247,22 +295,27 @@ function ansiQuoted(src, i, word) {
return j + 1;
}

function dollarBrace(src, i, word) {
function dollarBrace(src, i, word, ctx) {
const end = src.indexOf("}", i);
word.dynamic = true;
expand(word, ctx, end === -1 ? "" : src.slice(i + 2, end));
return end === -1 ? src.length : end + 1;
}

function dollarName(src, i, word) {
function dollarName(src, i, word, ctx) {
let j = i + 2;
if (/\w/.test(src[i + 1])) while (/\w/.test(src[j] ?? "")) j++;
word.dynamic = true;
expand(word, ctx, src.slice(i + 1, j));
return j;
}

function readBacktick(src, i, word, commands) {
function expand(word, ctx, name) {
if (ctx.vars.has(name)) word.text += ctx.vars.get(name);
else word.dynamic = true;
}

function readBacktick(src, i, word, ctx) {
const end = src.indexOf("`", i + 1);
parseInto(src.slice(i + 1, end === -1 ? src.length : end), commands);
parseInto(src.slice(i + 1, end === -1 ? src.length : end), ctx);
word.dynamic = true;
return end === -1 ? src.length : end + 1;
}
Expand Down
18 changes: 11 additions & 7 deletions .agents/scripts/tool-guard.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@
// `protocol:` and REVIEW.md's text; a stage agent with a `model`; a `code-reviewer`
// off Opus on a diff that touches a strict area (REVIEW.md, "Routing"), outside a
// replay; or a sub-agent starts a helper that is not `run_in_background: false`.
// git a sub-agent runs `git stash`, `git rebase` (or `pull --rebase`), or a push that
// git a sub-agent runs `git stash` (but `list` or `show`), `git rebase` (or `pull
// --rebase`), or a push that
// rewrites or deletes a remote branch (`+<ref>`, `:<ref>`, `--force`, `--delete`).
// gh a sub-agent opens a PR without `--draft` (or a REST create without
// `draft=true`), opens one from a `-repro` branch, runs `gh pr ready`, or adds
Expand All @@ -34,7 +35,8 @@
// session assigns an issue by hand instead of through `claim.mjs`.
// body any session posts a body or comment (`gh issue|pr comment|create|edit|close`,
// `gh api ... body=`) that `body-rules.mjs` rejects, or one the guard cannot read
// (built by `$(...)`, a backtick or a variable: use `--body-file`).
// (built by `$(...)`, a backtick or a variable the call does not set once to a
// literal: use `--body-file`).
// slow lane any session runs vitest on an `e2e/slow-*` file, or the e2e project without a
// `!slow` tags filter; a sub-agent runs `pnpm test:e2e:slow` (or a physical lane);
// an agent other than `hardware-verifier` and `implementer` runs `slow-e2e.sh`
Expand All @@ -55,7 +57,6 @@ const SCRIPTS = new Set([
"check",
"test",
"test:timing",
"typecheck",
"typecheck:e2e",
"typecheck:e2e:types",
"lint",
Expand Down Expand Up @@ -284,12 +285,14 @@ function trackWrites(state, cmd) {
}
}

const STASH_READS = new Set(["list", "show"]);
const GIT_RULES = [
{
when: (g) => g.sub === "stash",
when: (g) => g.sub === "stash" && !STASH_READS.has(g.rest.find((w) => !w.startsWith("-"))),
reason:
"Refused: never `git stash` in a delivery stage: every worktree shares one stash list, so " +
"a pop can take another agent's changes. Commit the work instead.",
"a pop can take another agent's changes. Commit the work instead. `git stash list` and " +
"`git stash show` only read, and pass.",
},
{
when: (g) =>
Expand Down Expand Up @@ -479,7 +482,8 @@ function unreadable() {
refuse(
"Refused: the guard cannot read a body built by `$(...)`, a backtick or a variable, so it " +
"cannot check its shape (delivery rule 12). Write the body to a file and pass " +
"`--body-file <file>` (`-F body=@<file>` for `gh api`).",
"`--body-file <file>` (`-F body=@<file>` for `gh api`). A variable reads fine when this " +
"call sets it once, to a literal path, in a command of its own before the use.",
);
}

Expand Down Expand Up @@ -752,7 +756,7 @@ if (tool === "Bash" && subAgent) {
`Refused: \`${found}\` is under "Checks agents never run" in toolchain.md. The commit ` +
"hook runs lint, the comment lint and typecheck; the push hook runs Fallow and the e2e " +
"typecheck; CI runs the rest. Their errors show in the commit or push output. Run only " +
'the commands under "Tests agents run".',
'the commands under "Tests agents run"; for types that is `pnpm typecheck`.',
);
}
}
Expand Down
27 changes: 21 additions & 6 deletions .agents/scripts/worktree.sh
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
# .agents/scripts/worktree.sh --detach <commit> [--prepare]
# a new detached worktree at <commit>, in a
# fresh folder under $TMPDIR (a review lens's or
# a probe's); --prepare installs into it
# a probe's); --prepare installs into it, and
# may come before or after <commit>
# echo '{"name":"<name>"}' | .agents/scripts/worktree.sh
#
# The stdin form is what Claude Code's WorktreeCreate hook uses (.claude/settings.json): the
Expand Down Expand Up @@ -57,23 +58,37 @@ EOF
)
}

if [ "${1:-}" = "--prepare" ]; then
detach=
case " $* " in
*" --detach "*) detach=1 ;;
esac

if [ -z "$detach" ] && [ "${1:-}" = "--prepare" ]; then
prepare "${2:?usage: worktree.sh --prepare <dir>}"
exit 0
fi

# why: a folder picked by hand (/tmp/rv1222-claims) already held the last round's commit, and the
# reviewer read it as the new one; a fresh folder and a checked HEAD rule that out.
if [ "${1:-}" = "--detach" ]; then
commit=$(git rev-parse --verify --quiet "${2:?usage: worktree.sh --detach <commit> [--prepare]}^{commit}") \
|| { echo "worktree.sh: $2 is not a commit here; fetch it first" >&2; exit 1; }
if [ -n "$detach" ]; then
install=
rev=
for arg in "$@"; do
case $arg in
--detach) ;;
--prepare) install=1 ;;
*) rev=$arg ;;
esac
done
commit=$(git rev-parse --verify --quiet "${rev:?usage: worktree.sh --detach <commit> [--prepare]}^{commit}") \
|| { echo "worktree.sh: $rev is not a commit here; fetch it first" >&2; exit 1; }
tmp=${TMPDIR:-/tmp}
dir=$(mktemp -d "${tmp%/}/wt-$(echo "$commit" | cut -c1-9).XXXXXX")
rmdir "$dir"
git worktree add -q --detach "$dir" "$commit" >&2
[ "$(git -C "$dir" rev-parse HEAD)" = "$commit" ] \
|| { echo "worktree.sh: $dir is not at $commit" >&2; exit 1; }
[ "${3:-}" != "--prepare" ] || prepare "$dir"
[ -z "$install" ] || prepare "$dir"
echo "$dir"
exit 0
fi
Expand Down
1 change: 1 addition & 0 deletions .claude/agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ you run are copied below, so you need not open it for them.
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Unit tests that import what the branch changed | `pnpm test:changed` |
| One unit test file | `pnpm exec vitest run --project unit <file>` |
| Types across the project, before a commit | `pnpm typecheck` |
| One console DOM test file (`*.dom.test.tsx`) | `pnpm exec vitest run --project ui-dom <file>` |
| One timing file (`*.timing.test.ts`) | `pnpm exec vitest run --project timing <file>` |
| Fast e2e files (builds first) | `pnpm test:e2e <files>` |
Expand Down
5 changes: 5 additions & 0 deletions .claude/skills/deliver/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,11 @@ gh issue view <N> --json number,title,labels,assignees,body

- Anything else, or assigned to someone else: stop and say why (rule 1).

When a Done when line of an issue in the run needs the slow lane, and the
run has no `no-hardware`: run the lane script's `check` (`toolchain.md`)
once, now. What it prints as unfit does not stop the run: say it in one
line, so the machine can be fixed while the first build runs.

## 2. Deliver one issue

Claim it: `node .agents/scripts/claim.mjs <N>`; a refusal says why the
Expand Down
6 changes: 5 additions & 1 deletion docs/internal/agent-rules/toolchain.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ copies "Tests agents run"; change both together (a repo test compares them).
| ---------------------------------------------- | -------------------------------------------- |
| Unit tests that import what the branch changed | `pnpm test:changed` |
| One unit test file | `pnpm exec vitest run --project unit <file>` |
| Types across the project, before a commit | `pnpm typecheck` |
| One console DOM test file (`*.dom.test.tsx`) | `pnpm exec vitest run --project ui-dom <file>` |
| One timing file (`*.timing.test.ts`) | `pnpm exec vitest run --project timing <file>` |
| Fast e2e files (builds first) | `pnpm test:e2e <files>` |
Expand Down Expand Up @@ -37,7 +38,7 @@ pages; it compares nothing. Open the pictures the change touched.

Hooks and CI run these. Never run them by hand, and never the tools behind
them (from `node_modules/.bin` or any other path): `pnpm check`, `pnpm test`,
`pnpm test:timing`, `pnpm typecheck`, `pnpm typecheck:e2e`, `pnpm typecheck:e2e:types`, `pnpm lint`, `pnpm lint:comments`, `pnpm lint:tests`,
`pnpm test:timing`, `pnpm typecheck:e2e`, `pnpm typecheck:e2e:types`, `pnpm lint`, `pnpm lint:comments`, `pnpm lint:tests`,
`pnpm format`, `pnpm format:check`,
`pnpm fallow`, `pnpm mutate` (outside the `harden-tests` routine and a
refactor's `--touched-by` run, below), the whole
Expand Down Expand Up @@ -199,6 +200,9 @@ Tests that start real simulators or emulators. Run them only through
- It first stops what earlier runs left behind. By hand: `scripts/slow-e2e.sh
clean` (refused while a run holds the lock). Never stop a simulator,
emulator or daemon any other way.
- `scripts/slow-e2e.sh check`: the checks a run starts with, without a
run. Exit 69 with why when the machine is unfit. While a lane runs it
stops nothing and checks only free disk and the other tools.
- `scripts/slow-e2e.sh status`: the running test, the counts so far, how
long the log has been quiet, and each failure. `scripts/slow-e2e.sh stop`
ends the running lane and what it started.
Expand Down
12 changes: 8 additions & 4 deletions scripts/slow-e2e.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
# the log has been quiet; or the last run's log and exit code
# scripts/slow-e2e.sh stop stops the running lane and what it started, and frees the lock
# scripts/slow-e2e.sh clean stops what earlier runs left behind (refused while a lane runs)
# scripts/slow-e2e.sh check the checks a run starts with: clean, then free disk and builds
# scripts/slow-e2e.sh check the checks a run starts with: clean and the worker lock (neither
# while a run holds the lane lock), then free disk and builds
#
# Vitest arguments pass through: `-t <title>` runs one test, `--bail=1` stops at the first
# failure. A run prints its log path and exits at once; it writes its exit code to <log>.exit
Expand Down Expand Up @@ -140,12 +141,15 @@ if command == "clean":
clean()

elif command == "check":
clean()
# why: a running lane's processes, home and worker are its own, not leftovers; cleaning under it fails its tests.
running = holder()
if not running:
clean()
problems = []
# why: a lane worker an aborted run left is already killed by clean(), so a live holder here is a worker outside the lane (ADR 0059 §4).
# why: with no lane running, a lane worker an aborted run left is already killed by clean(), so a live holder is a worker outside the lane (ADR 0059 §4).
try:
owner = json.loads(read(os.path.join(worker_lock, "owner.json"), "{}"))
if alive(owner["pid"]):
if not running and alive(owner["pid"]):
print(f"not fit: a Simlock worker holds this machine (pid {owner['pid']}, folder {owner['folder']}); stop it first: SIMLOCK_HOME={owner['folder']} simlock daemon stop", file=sys.stderr)
sys.exit(69)
except (ValueError, KeyError, TypeError):
Expand Down
Loading
Loading