Bump eslint-plugin-import-structure to 0.13.0 (#27)

Co-authored-by: Danny Kim <temeddix@gmail.com>
Co-committed-by: Danny Kim <temeddix@gmail.com>

.agents/memory/agent-cli-auth-failures.md

@@ -0,0 +1,24 @@
+---
+description: How codex, claude, and opencode report rejected credentials, and how the runner detects them
+---
+
+Observed 2026-10 (codex 0.153/0.162, Claude Code 2.1.28x, opencode 1.18/1.19):
+
+- Codex: `codex login status` only reads the local auth.json, so a
+  server-revoked ChatGPT login passes it. `codex exec` then exits 1 with stderr
+  ERROR lines such as `refresh_token_invalidated` / "Your session has ended.
+  Please log in again.", `auth error code: token_revoked`, `401 Unauthorized`; a
+  bad API key gives `invalid_api_key`. Codex echoes the whole prompt and tool
+  output to stderr, so `isCodexAuthFailure` only matches ERROR lines and the
+  runner strips the prompt first.
+- Claude: a bad `CLAUDE_CODE_OAUTH_TOKEN` yields a stream-json `result` with
+  `is_error: true`, `api_error_status: 401`, and "Failed to authenticate. API
+  Error: 401 OAuth access token is invalid."; exit code 1, empty stderr.
+- OpenCode: a bad OpenRouter key exits 1 with empty stderr and a stdout JSON
+  event
+  `{"type":"error","error":{"name":"APIError","data":{"statusCode":401,
+  "message":"User not found."}}}`.
+  An empty key gives an opaque UnknownError.
+
+Sign-in failures become `AgentAuthError` and fall through to the next profile
+like usage exhaustion; the failure comment lists only fixed labels per profile.

.agents/memory/agents-md-and-damem.md

@@ -0,0 +1,39 @@
+---
+description: Every repo has AGENTS.md starting with the damem recall header; durable context lives in .agents/memory (flat, one fact per file) and .agents/skills
+---
+
+Standing convention (2026-10-12): every repo has an `AGENTS.md` whose first
+lines are exactly the damem header (cunarist/damem):
+
+```markdown
+At the start of every new session, run `damem recall` in the terminal and treat
+its output as the context for this repository. If the `damem` command is not
+found, read [INSTALL.md](https://github.com/cunarist/damem/blob/main/INSTALL.md)
+and follow it before reasoning or responding.
+```
+
+Below it: `# AGENTS.md`, then `## Project` (what the repo is, runtime,
+toolchain, where it came from) and `## Rules` (short bullets, each pointing at
+a memory where the reason lives). No `CLAUDE.md`, `GEMINI.md`, or other
+per-agent files; `AGENTS.md` is the single entry point.
+
+## `.agents/` layout
+
+- `memory/*.md`: one fact per file, flat (subdirectories are not listed),
+  frontmatter with a one-line `description` that states the fact. Link
+  related notes with double-bracket wiki links using the file name without
+  `.md`; a link to a missing note fails `damem doctor`.
+- `skills/<name>/SKILL.md`: frontmatter `name` and `description` (when to use
+  it), body says how. Helper scripts live next to it and are Python 3.12+.
+- `scratch/`: holds a `.gitignore` containing `*`.
+- Every memory and `SKILL.md` stays under 8 KB.
+
+## Keeping it right
+
+- Update an existing note instead of adding a near-duplicate; delete notes
+  that turn out wrong.
+- Write a note when the user corrects something, states a preference, or
+  when understanding something took reading many files.
+- Run `damem doctor` before finishing and fix what it reports.
+- Changing anything outside `.agents/` (source, config, `AGENTS.md`) follows
+  the normal branch and PR flow ([[git-pr-workflow]]).

.agents/memory/bot-agents-child-processes.md

@@ -0,0 +1,39 @@
+---
+description: Child processes use plain node:child_process spawn (explicit stdio, uid/gid, whole env); src/processes/child.ts has exitCode (128+signo) and echo; no execFile maxBuffer
+---
+
+Every call site calls `spawn` from `node:child_process` itself, with
+everything explicit:
+
+- **`uid`/`gid`** of the profile for anything an agent profile runs (each
+  profile is its own UID, 20000+). Never drop them.
+- **`env`** is the whole environment the child gets (a sanitized one for
+  agents); nothing from the coordinator is merged in.
+- **`stdio`**: stdin is `"ignore"` so an agent CLI never waits on input
+  (only `codex login --with-api-key` pipes the token in). Output that is not
+  read is `"ignore"`; output that is read is `"pipe"` and streamed.
+- No `execFile`/`exec`: their `maxBuffer` (1 MiB) kills a chatty child. Read
+  piped streams incrementally instead.
+
+`src/processes/child.ts` holds what the call sites share:
+
+- **`exitCode(child)`**: call it right after `spawn`. It settles on `exit`
+  (not `close`, which a daemonized grandchild can hold open), maps a signal to
+  `128 + signo` as a shell does, and rejects on a failed start. The rejection
+  is pre-caught so it is not reported as unhandled before the caller awaits it.
+- **`echo(stream, chunk)`**: writes and waits for `drain` when the buffer is
+  full, so echoing never outruns a slow reader.
+
+Tests use `spawnSync` for short commands.
+
+Other port details:
+
+- **`src/common/errors.ts`** `isNotFound` checks `ENOENT` (file) or `ESRCH` (process).
+- Temporary files are an exclusive `wx` create with mode `0600`.
+- `src/common/json.ts` holds type guards used instead of `as` casts on parsed JSON.
+- `process` and `Buffer` must come from `node:` imports:
+  `no-restricted-globals` in `scripts/project-lint.ts` enforces it
+  ([[lint-parity-never-shrinks]]).
+
+Related: how each agent CLI reports bad credentials is in
+[[agent-cli-auth-failures]].

.agents/memory/bot-agents-migration-decisions.md

@@ -0,0 +1,33 @@
+---
+description: bot-agents migration decisions: live @main action for six repos, JSON profiles, Node 24.2+, lints with eslint-plugin-import-structure and explicit-types (concrete, absence)
+---
+
+Decisions for `commons/bot-agents` (Capsulizers Gitea), from the Deno to
+Node + Vite+ migration (PR #20, `node-migration`, 2026-10-15/16):
+
+- **Live action.** Six consumer repos use `commons/bot-agents@main`, so a merge
+  switches all of them at once. It changes only through a PR and a careful
+  review. Suggested before merging a risky change: tag the current `main`
+  (e.g. `deno-final`) as a rollback target and canary the branch from one
+  consumer (`uses: .../commons/bot-agents@<branch>`) on a throwaway PR.
+- **Profiles are JSON.** `profiles.yml` became `profiles.json` with the same
+  content (encrypted `v1:` values unchanged), read with `JSON.parse`. That
+  removed the only runtime dependency (`@std/yaml`); keep it free of runtime
+  dependencies (`@eslint/core` and the other devDependencies serve only the
+  tooling).
+- **Node 24.2+**, not 22: `src/post/index.ts` uses `import.meta.main`. There is no
+  `engines` (user decision 2026-10-18): the `node:24-bookworm` job image
+  decides the version ([[bot-agents-runtime-no-build]]).
+- **Published lint plugins** (2026-10-18, after they reached npm):
+  `eslint-plugin-import-structure` (`modules` config) and
+  `eslint-plugin-explicit-types` (`concrete` and `absence` configs) are
+  devDependencies, enabled in `vite.config.ts` through their `all` configs.
+  `upper-snake-string-unions` was off while the user decided; since
+  2026-10-19 it is on and profile types, failure reasons, and anchor sides
+  are `UPPER_SNAKE` ([[enum-values-upper-snake]]). `eslint-plugin-lit-robust`
+  does not apply (no Lit).
+- **Stricter input checks were accepted** in the migration: Gitea `/user` and
+  comment responses, the runtime manifest, and the outcome's profile type are
+  validated; some type errors became `TypeError` with the same messages.
+- Merging is the user's call; the `bot` account's approval is required first
+  ([[git-pr-workflow]]).

.agents/memory/bot-agents-runtime-no-build.md

@@ -0,0 +1,31 @@
+---
+description: The action runs src/<phase>.ts directly with node on node:24-bookworm (no build); protect-source.sh copies only src/*.ts, package.json, profiles.json, prompt.md
+---
+
+`action.yml` is a composite action running three phases as
+`node "<source>/src/{prepare,run,post}.ts"`. Node's built-in type stripping
+runs the TypeScript; there is **no build step, no bundle, and no runtime
+dependency**. Hence `tsconfig.json` has `erasableSyntaxOnly` and
+`allowImportingTsExtensions`: only erasable syntax (no `enum`, no parameter
+properties, no decorators) and relative `.ts` imports.
+
+- **Image:** the steps assume the `node:24-bookworm` job container. Node must
+  be 24.2+ for `import.meta.main` in `src/post/index.ts`. That image is the only Node
+  pin (`package.json` has no `engines`); `check.yml` prints `node --version`
+  to confirm the cached image's minor.
+- **Root-owned source copy:** `scripts/protect-source.sh` copies the action
+  into `$RUNNER_TEMP` so an agent editing the checkout can't swap a later
+  phase. It copies exactly `src/*.ts`, `package.json` (`"type": "module"`
+  makes Node load the sources as ES modules), `profiles.json`, and
+  `prompt.md`. **A new runtime file or subdirectory must be added there**, or
+  it is missing at run time. Runtime code in `src/` is flat; a subfolder would
+  not be copied. The only subfolder, `src/testing/`, is test-only.
+- `tests/entrypoints.test.ts` runs each phase under real Node with a cleared
+  environment and expects its first "X is not set" error, which proves the
+  whole import graph loads without a build. Keep it in sync with the phases.
+- **None of the app build conventions apply here:** no `vp build`, no
+  frontend or Rust/Tauri output paths, no Containerfile, no decorators
+  plugin, no lit-check, no generated JS. Don't add any of them.
+- **CI** (`.gitea/workflows/check.yml`) runs on the self-hosted runner's
+  default image as root: `npm ci`, `npx vp check`, `npx vp test`. It does not
+  use `setup-vp`. YAML stays declarative ([[yaml-stays-declarative]]).

.agents/memory/bot-agents-tests-root-only.md

@@ -0,0 +1,25 @@
+---
+description: Isolation and credential tests need root and use test.skipIf(!IS_ROOT); locally 5 skip, CI runs as root so all 66 run; verify isolation changes in node:24-bookworm as root
+---
+
+Some tests exercise real UID isolation, process cleanup, and the prepare phase's
+credential cleanup. They need root and are written as
+`test.skipIf(!IS_ROOT)(...)` (`IS_ROOT` from `#testing`), so they show
+as skipped instead of silently passing.
+
+- As a normal user `vp test` passes 61 and skips 5. In CI (self-hosted
+  runner, root) all 66 run.
+- When changing `isolation.ts`, `runtime.ts`, `credentials.ts`, `prepare/index.ts`,
+  or `child.ts`, run the suite as root in `node:24-bookworm` (e.g. a
+  container with the repo mounted) before pushing; a green non-root run
+  proves nothing about those paths.
+- The migration also ran an end-to-end smoke as root with fake
+  `codex`/`claude`/`npx` binaries and a fake Gitea through
+  `protect-source.sh` -> `prepare/index.ts` -> `run/index.ts` -> `post/index.ts`; repeat that
+  for changes to the phase flow ([[bot-agents-runtime-no-build]]).
+- `src/testing/index.ts` holds the shared test helpers (user IDs, temp dirs,
+  `runCommand`) behind the `#testing` alias. Every test imports it as
+  `#testing`. It imports no source module, so `tests/` (which may not use
+  `../`) never reaches internals. Tests follow
+  [[tests-layout-vitest]] (unit tests next to their code in `src/`, repo-level ones in
+  `tests/`).

.agents/memory/enum-values-upper-snake.md

@@ -0,0 +1,48 @@
+---
+description: Enum-like string values are UPPER_SNAKE everywhere this repo owns the format, JSON included; external standards are converted at the boundary with explicit switch functions
+---
+
+Decided 2026-10-19 (all repos). An enum-like string value, a member of a
+string-literal union, is `UPPER_SNAKE` wherever this repo owns the format:
+TypeScript unions, `profiles.json`, the runtime outcome file, and the
+`anchors.json` the agent writes per `prompt.md`. explicit-types
+`upper-snake-string-unions` enforces it and stays on.
+
+A value an outside party defines (a CLI flag, an environment variable name,
+an HTTP API field, a human-readable message) is converted at the boundary by
+an explicit `switch` function, never by renaming our own values to match it:
+
+```ts
+export interface ProfileIdentity {
+  type: "CLAUDE" | "CODEX" | "OPENCODE";
+  model: string;
+}
+
+// The agent name the skills installer knows each profile type by.
+function skillsAgent(type: RuntimeProfile["type"]): string {
+  switch (type) {
+    case "CLAUDE":
+      return "claude-code";
+    case "CODEX":
+      return "codex";
+    case "OPENCODE":
+      return "opencode";
+  }
+}
+```
+
+In this repo:
+
+- Profile `type`: `CLAUDE`, `CODEX`, `OPENCODE` (also in `profiles.json`).
+  `skillsAgent()` (run phase) and `tokenVariable()` (profiles) map them to the
+  installer's agent name and the credential environment variable;
+  `defaultModel()` (credentials) picks a model.
+- `FailureReason`: `SIGN_IN_FAILED`, `USAGE_EXHAUSTED`, `FAILED`; `toMessage()`
+  gives the words that logs and posted comments show.
+- Anchor `side`: `NEW` or `OLD` (`prompt.md` tells the agent so); the Gitea
+  review call turns it into `new_position` / `old_position`.
+
+A lookup object keyed by enum values would need `UPPER_SNAKE` keys, which
+explicit-types `no-upper-snake-object-keys` bans, so use a `switch`. TypeScript
+checks such a switch for exhaustiveness through the declared return type; no
+`default:` branch ([[lint-config]]).

.agents/memory/git-pr-workflow.md

@@ -0,0 +1,51 @@
+---
+description: Work on a branch, plain imperative commits without AI trailers, one PR with the Claude Code footer, review until approved, never merge yourself; squash only
+---
+
+## Branches and commits
+
+- Never push to `main`. Every change goes through a branch and a PR, even a
+  one-line fix.
+- Commit messages are plain imperative sentences ("Port the import-check
+  rules to an ESLint plugin"). No conventional-commit prefixes, no AI
+  trailers (`Co-Authored-By: Claude`, "Generated with ..."), no emoji.
+- When several agents share a branch, each works in its own `git worktree`,
+  runs `git pull --rebase` before pushing, and retries a rejected push after
+  rebasing. Remove the worktree and temp branch afterwards.
+- `vp check`, `vp test`, and the build pass locally before every push.
+
+## Pull requests
+
+- One PR per repo for a migration, everything included (size-rule refactors
+  too).
+- The body covers: summary, what changed, deviations and risks, verification
+  done, and open questions. It ends with exactly this line:
+
+  ```
+  🤖 Generated with [Claude Code](https://claude.com/claude-code)
+  ```
+
+- Then run the review cycle (skill `review-cycle`): on Capsulizers Gitea repos
+  that have `.gitea/workflows/agents.yml`, comment `@bot` and address the `bot`
+  account's review; elsewhere, a subagent reviews the diff and posts the
+  review as a PR comment. Repeat until fully approved, then ask the user to
+  review.
+
+## Merging
+
+- **Never merge on your own.** The user merges, unless they explicitly allow
+  it for one specific PR.
+- GitHub repos are squash-merge only, so a PR lands as one commit titled after
+  the PR.
+- Also never, without the user: publish, archive a repo, or delete a branch
+  the user may still use.
+
+## Hosts
+
+- **cunarist** and **temeddix**: GitHub only, CI in `.github/workflows`, use
+  the `gh` CLI.
+- **Capsulizers**: Gitea at git.capsulizers.com (Gitea 1.26), CI in
+  `.gitea/workflows`, PRs through the Gitea API. Push and open PRs as the
+  user's own account (credentials in the user's environment; source them in a
+  subshell and never print them); `bot` is a separate review account. The
+  org's codified rules live in the `commons/code-rules` README.

.agents/memory/imports-aliases-barrels.md

@@ -0,0 +1,105 @@
+---
+description: An alias owns its target (folder index.ts = folder and below, any other file = that file); no overlap; outside an area only the exact alias reaches it; ../ is banned in every file; locally, aliases target only direct src/ subfolders
+---
+
+## `#` aliases own their targets
+
+Shared code is imported through Node subpath imports declared in
+`package.json` `imports`. Node, TypeScript, Vite, Vite+'s config bundler, and
+Oxlint's plugin loader all resolve them natively, so `.ts` source runs
+unbuilt. `vp pack` inlines them, so they never reach package consumers.
+
+One rule for every file, never tied to folder or file names (user rule
+2026-10-17; it replaces the earlier "aliases only point at direct `src/`
+subfolders" rule as the general rule, and the "import-structure plugin
+checks only aliased folders" scope; this repo keeps the stricter rule as a
+local convention, see the last section):
+
+- **An alias may point anywhere** and owns its target. An alias to a
+  folder's `index.ts` owns that folder and everything below it; an alias to
+  any other file owns only that file.
+- **No overlap.** No file may be owned by 2 aliases: no alias inside another
+  alias's area, and no 2 aliases with the same target. The import-structure
+  plugin's `enforce-layer-order` reports it once at the top of every file 2
+  aliases claim. Fix by merging the aliases or moving files apart.
+- **Outside an area, only the exact alias reaches it.** A deeper alias
+  specifier (`#a/one.ts`, `no-barrel-bypass`) and a relative path into the
+  area (`./a/one.ts`, `no-relative-bypass`; `./b/f.ts` to a file alias,
+  `prefer-alias-import`, fixed to the alias) are bypasses.
+- **Inside an area, relative imports of siblings and subfolders are free.**
+- **A `../` import is banned in every file**, owned or not (`no-parent-import`).
+  Runtime file URLs (`new URL("../prompt.md", import.meta.url)`) are not
+  imports and are allowed.
+  Anything above a file needs an alias.
+- **Files no alias owns** need no `index.ts` and no alias, and import `./`
+  siblings and subfolders freely.
+- Unchanged: no `/*` subpath patterns, the key order of `imports` is the
+  layer order `enforce-layer-order` checks (add a new alias at the right
+  layer), and entry files are `index.ts` only.
+
+```jsonc
+"imports": {
+  "#a": "./a/index.ts",      // owns a/**
+  "#f": "./b/f.ts",          // owns only b/f.ts
+  "#a-sub": "./a/sub/index.ts", // no: inside #a
+  "#a2": "./a/index.ts"      // no: same target as #a
+}
+```
+
+```ts
+// in main.ts, which no alias owns
+import { a } from "#a"; // yes
+import { one } from "#a/one.ts"; // no: deeper alias specifier
+import { one } from "./a/one.ts"; // no: relative path into #a
+import { f } from "#f"; // yes
+import { f } from "./b/f.ts"; // no: relative path to a file alias
+import { g } from "./b/g.ts"; // yes: unowned
+// in a/one.ts, owned by #a
+import { two } from "./two.ts"; // yes: sibling
+import { deep } from "./sub/deep.ts"; // yes: subfolder of the same area
+import { x } from "../x.ts"; // no: no ../ anywhere
+```
+
+- Aliases point at `.ts` files only. There is no `#package` alias
+  ([[ts-only-files-and-imports]]).
+- Lint `jsPlugins` entries in `vite.config.ts` stay path strings, even when
+  the file has an alias.
+- Keep test-only helpers in their own alias (e.g. `#testing`) so they never
+  land in a bundle.
+
+## Barrels
+
+- An area used from outside exposes its API through its alias target, and
+  callers import the alias (`#ui`), not files inside it.
+- Barrels are also the standard fix for `import/max-dependencies`: one barrel
+  import replaces many direct ones ([[lint-config]]).
+- `import/no-cycle` is on; a barrel must not create a cycle.
+
+Relative imports are written with the `.ts` extension.
+
+## `scripts/` is flat (user rule, 2026-10-16)
+
+- `scripts/` has no subfolders and no `index.ts`.
+- Each tool is one file, `scripts/<name>.ts`, imported directly by file:
+  `import projectLint from "./scripts/project-lint.ts";` in
+  `vite.config.ts`. No alias owns `scripts/`, so these `./` imports are free.
+- Code in a former `scripts/<tool>/` folder is merged or renamed into flat
+  `scripts/<name>.ts` files. Non-TS assets (HTML, images, fixtures) move to
+  where they belong (next to the tool's output, `.agents/`, or a gitignored
+  scratch dir). A subfolder that is really an app moves under an alias.
+
+## Local convention: aliases target direct `src/` subfolders
+
+This is a convention of this repo only, stricter than the general rule above
+(which the published import-structure plugin checks and which allows more).
+It is not a plugin rule.
+
+- Every `package.json` `imports` alias points only at the `index.ts` of a
+  direct subfolder of `src/`, e.g. `"#helpers": "./src/helpers/index.ts"`.
+  No alias to a single file, a deeper folder, or anything outside `src/`.
+  Here the aliases are `#prepare`, `#run`, `#post`, `#agents`, `#processes`, `#runtime`, `#profiles`,
+  `#common`, and `#testing`, in that layer order.
+- Code outside `src/` (`scripts/`, `tests/`, `vite.config.ts`) gets no alias
+  of its own and imports its own files by `./` relative paths. It reaches
+  `src/` only through the aliases, since `../` is banned.
+- No lint rule checks this; check `imports` by hand when adding an alias.

.agents/memory/lint-config.md

@@ -0,0 +1,102 @@
+---
+description: Lint config shape: every non-nursery Oxlint category on, plugins via `all`, a blacklist of offs in configs.project, per-file exceptions only in projectOverrides, ignorePatterns only for generated output
+---
+
+Policy (2026-10-19): a blacklist, not a whitelist. Replaces the older
+category-subset and "no overrides" notes.
+
+- **Categories:** `correctness`, `suspicious`, `pedantic`, `perf`, `style`,
+  `restriction` at `error`. `nursery` stays off (no line for it).
+- **Plugins** are enabled whole through their `all` config
+  (`explicitTypes.configs.all.rules`, `importStructure.configs.all.rules`).
+- **Blacklist:** repo-wide offs and option tweaks live in
+  `projectLint.configs.project.rules` in `scripts/project-lint.ts`, spread
+  last in `rules`, each with a one-line reason. Never re-list a rule a
+  category already turns on. bot-agents runs on Node everywhere, so
+  `import/no-nodejs-modules`, `unicorn/no-process-exit`, and `no-console` are
+  off repo-wide.
+- **Per-file exceptions** only via `projectOverrides`, the whole `overrides`
+  array exported from `scripts/project-lint.ts`: the Node code entry
+  (`vite.config.ts`, `scripts/**`, `nodeRules`) first, then one entry per
+  exception with a why-comment. `vite.config.ts` has exactly
+  `overrides: projectOverrides`.
+- **No `allowFiles`** options in custom rules, and no disable comments
+  ([[lint-no-disable-comments]]).
+- **`ignorePatterns`** only for generated or build output, never hand-written
+  code. A hand-written file is linted, with override entries for only what it
+  legitimately breaks. bot-agents has no generated code, so none.
+- **Precedence:** categories < `rules` (a later spread wins) < `overrides` (a
+  later entry wins).
+- Size and complexity limits (`complexity`, `max-lines`, ...) are set to the
+  smallest value the current code passes.
+
+```ts
+// scripts/project-lint.ts
+export const projectOverrides: OxlintOverride[] = [
+  { files: ["vite.config.ts", "scripts/**"], rules: nodeRules },
+  // Why: src/example.ts must ... (a per-file exception, if one is ever needed)
+  // { files: ["src/example.ts"], rules: { "some-rule": "off" } },
+];
+
+// vite.config.ts
+rules: {
+  ...explicitTypes.configs.all.rules,
+  ...importStructure.configs.all.rules,
+  ...projectLint.configs.project.rules,
+},
+overrides: projectOverrides,
+```
+
+## Rule decisions (2026-10-19, all repos)
+
+- `typescript/promise-function-async` is on with `require-await` and
+  `typescript/return-await`. A function that returns a promise is `async`
+  and awaits it: `async f() { const x = await g(); return x; }`. Test
+  doubles do the same (`const resolved = await Promise.resolve(v); return
+  resolved;`), and `expect(promise).rejects` takes the promise itself.
+  `src/processes/child.ts` is exempt in `projectOverrides`: `exitCode` must
+  return the very promise it marks handled, or a failed spawn would surface
+  as an unhandled rejection before callers await it.
+- `init-declarations` is on: an uninitialized `let` becomes
+  `let x: T | null = null;` (`unknown` already includes `null`); a `try` that
+  assigns and a `catch` that exits still narrow it.
+- `no-use-before-define` is on with only `{ functions: false }`.
+- `no-await-in-loop` is off (sequential awaits are intentional) and
+  `unicorn/no-array-reduce` is on: sequential steps are plain `for` loops,
+  never `reduce` chains or recursion.
+- `consistent-return`, `typescript/switch-exhaustiveness-check`, and
+  `default-case` are off: TypeScript's checks cover them, and no `default:`
+  branch is added to an exhaustive switch.
+- `unknown` is allowed; `any` is banned and the `typescript/no-unsafe-*`
+  rules are on. Untrusted data is `unknown` plus a type guard.
+- `unicorn/no-array-for-each` (use `for...of`),
+  `unicorn/prefer-structured-clone`, and `typescript/prefer-nullish-coalescing`
+  (defaults) stay on.
+- explicit-types `upper-snake-string-unions` is on
+  ([[enum-values-upper-snake]]); `unicorn/custom-error-definition` is on, so a
+  custom error has a constructor that sets `this.name`.
+- `src/post/` and `src/profiles/` (code and tests) are exempt from
+  `project/prefer-ascii` in `projectOverrides`: posted Gitea text shows emoji
+  verdict marks and a middle dot.
+
+## Rule decisions (2026-10-20, all repos)
+
+- `unicorn/number-literal-case` is off: Oxfmt lowercases hex digits back.
+- `typescript/consistent-return` is off too: it misfires on complete
+  switches, like `consistent-return`.
+- On with defaults, no offs: `prefer-object-spread`, `unicorn/prefer-spread`,
+  `unicorn/no-useless-spread`, `typescript/no-misused-spread`, `no-plusplus`
+  (`x += 1`), `unicorn/no-array-method-this-argument`,
+  `typescript/method-signature-style` ("property"),
+  `typescript/unified-signatures`.
+- `unicorn/import-style` uses its default: `import nodePath from "node:path"`
+  and `nodePath.join(...)` (`nodePath`, since `path` is a common variable).
+- `no-template-curly-in-string` is on; only `tests/workflow.test.ts`, which
+  checks literal Gitea `${{ }}` expressions, is exempt in `projectOverrides`.
+- Rule defaults are preferred over option tweaks unless a tweak is needed.
+- `fmt` matches `deno fmt`: `printWidth: 80`, `quoteProps: "preserve"`,
+  `embeddedLanguageFormatting: "off"`. `max-lines-per-function` is 124 after
+  the narrower width.
+
+A new category hit is fixed in the code; an off or exception is added only
+for a real collision or churn, with its reason. Rules: [[project-lint-plugin]].

.agents/memory/lint-no-disable-comments.md

@@ -0,0 +1,30 @@
+---
+description: Every eslint-/oxlint-disable or -enable comment is banned in every form; three checks enforce it together, keep all three
+---
+
+Banned (2026-10-16): `eslint-disable`, `eslint-disable-line`,
+`eslint-disable-next-line`, `eslint-enable`, and the same with `oxlint-`, as
+line or block comments, anywhere in the repo. Fix the code; if the code truly
+can't be fixed, ask the user, don't silence the rule. Old
+`deno-lint-ignore` lines are removed during the migration and their cause
+fixed.
+
+Oxlint (1.87) has no `noInlineConfig` and no `eslint-comments` rules, and
+`respectEslintDisableDirectives: false` only ignores `eslint-*` directives. So
+three checks enforce the ban together, and none is redundant:
+
+1. `project/no-disable-comments` (custom, in `scripts/project-lint.ts`) fails
+   any directive.
+2. `unicorn/no-abusive-eslint-disable` fails a directive that names no rule,
+   which would otherwise silence the custom rule on its own line.
+3. `options.reportUnusedDisableDirectives: "error"` fails a directive naming
+   `project/no-disable-comments` (the custom rule skips that one, so the
+   directive silences nothing and is reported as unused).
+
+Every form was probed and fails `vp check`.
+
+A rule that fires on legitimate code is a rule problem: change the rule or its
+options in `configs.project` with the user's agreement, not the call site.
+Known example: rule records are `Map`s keyed by id rather than object
+literals with kebab-case keys, which keeps naming rules happy without any
+directive.

.agents/memory/lint-parity-never-shrinks.md

@@ -0,0 +1,46 @@
+---
+description: Lint coverage never drops below what Deno enforced; every Deno rule maps to an Oxlint rule, a plugin rule, the compiler, or our own rule
+---
+
+Hard rule (2026-10-12): after the move, a repo has at least the lint coverage
+it had under Deno: built-in rules (the `recommended` and `jsr` tags plus
+opt-ins like `camelcase`, `eqeqeq`, `guard-for-in`, `no-console`,
+`no-eval`, `no-throw-literal`, `no-non-null-assertion`,
+`verbatim-module-syntax`), `@hugoalh` rules, and the custom plugins. Rules may
+be added, never lost. Formatting may change. "Gap" is not an acceptable end
+state: a Deno rule Oxlint lacks is replaced by a plugin rule or our own rule in
+[[project-lint-plugin]].
+
+Before removing any line from `configs.project`, find what else covers it.
+
+## How the template mapped Deno's 97 rules
+
+- **Same rule** in `configs.project` at `error`.
+- **Renamed equivalent:** `no-new-symbol` → `no-new-native-nonconstructor`;
+  `no-window` → `no-restricted-globals: ["error", "window"]`;
+  `ban-untagged-ignore` → `unicorn/no-abusive-eslint-disable`;
+  `ban-unused-ignore`, `ban-unknown-rule-code` →
+  `reportUnusedDisableDirectives`; `camelcase` → built-in `id-match`
+  ([[naming-id-match]]).
+- **Caught by the parser or `typeCheck`:** `no-dupe-args`, `no-octal`,
+  `no-await-in-sync-fn`, `no-import-assertions` (TS2880), `no-sloppy-imports`
+  (TS2835), `verbatim-module-syntax` (TS1484).
+- **`no-slow-types`:** `isolatedDeclarations`, enforced by `vp pack` (TS9010)
+  in packages.
+- **Vacuous:** JSX rules (no `.tsx` exists) and Deno-only rules.
+- **`@hugoalh` rules** map to Oxlint built-ins in `configs.project`.
+- **deno-import-check's CLI cycle check** → `import/no-cycle`.
+
+The template's list in `configs.project` is the baseline to copy: `curly`,
+`guard-for-in`, `no-console`, `no-empty`, `no-regex-spaces`,
+`no-restricted-globals`, `no-var`, `prefer-const`, `import/no-cycle`,
+`import/no-relative-parent-imports`, `typescript/adjacent-overload-signatures`,
+`typescript/consistent-type-imports`, `typescript/no-empty-interface`,
+`typescript/no-explicit-any`, `typescript/no-namespace`,
+`typescript/no-non-null-assertion`, the two `project/*` rules,
+`unicorn/no-abusive-eslint-disable`, `id-match`, and
+`typescript/switch-exhaustiveness-check` with
+`considerDefaultExhaustiveForUnions`.
+
+Each migration PR states its parity mapping (or links the template's table in
+cunarist/eslint-plugin-explicit-types#1) so the user can check it.

.agents/memory/naming-id-match.md

@@ -0,0 +1,48 @@
+---
+description: Deno's camelcase is Oxlint id-match ^_*[^_]*_*$|^[^a-z]*$; leading _ for unused vars; rename snake_case imports; PascalCase types; single-letter type params
+---
+
+Oxlint has no `camelcase`. Its built-in `id-match` replaces it, set in
+`configs.project` (user decision 2026-10-16, replacing a ~400-line port):
+
+```ts
+"id-match": ["error", "^_*[^_]*_*$|^[^a-z]*$", {
+  properties: false, classFields: false, onlyDeclarations: false,
+  ignoreDestructuring: true,
+}],
+```
+
+**Meaning** (Deno's `is_underscored`): after trimming leading and trailing
+underscores, the name has no `_`, **or** the name has no lowercase ASCII
+letter. `id-match` can't tell what kind of name it sees, so one regex accepts
+every valid style; other rules decide which style goes where.
+
+```ts
+const userName = 1; // ok
+class UserStore {} // ok here; pascal-case-types enforces PascalCase
+const MAX_SIZE = 10; // ok: no lowercase, so UPPER_SNAKE passes
+const _unused = 1; // ok: leading _ marks an unused binding
+const user_name = 1; // error
+```
+
+- **Leading underscores stay allowed** for unused parameters and variables
+  (`items.map((_item, index) => index)`). The user considered banning them and
+  kept them for exactly this.
+- **Rename snake_case imports at the import** (user wants this flagged):
+  `import { parse_args as parseArgs } from "some-lib";`
+- `declare` lines and snake_case globals are rare and accepted as they are.
+- **Types:** classes, interfaces, type aliases, enums are PascalCase
+  (`pascal-case-types` from explicit-types' `naming` config); string-union
+  members are UPPER_SNAKE_CASE; no `enum`.
+- **Type parameters:** the user wants single capital letters (`T`, `K`), not
+  `Item`; explicit-types PR 2 adds `single-capital-type-params` to `naming`.
+  Write new code that way already.
+- No autofix exists for `id-match`; rename by hand.
+
+**Known differences from Deno's `camelcase`** (against its 130 test cases):
+it misses 9 (unquoted object keys like `{ bar_baz: 1 }` and `{ bar_baz }`,
+shorthand destructuring in parameters, `{ a_b: a_b }`,
+`{ foo: bar_baz = 1 }`) and over-reports 17 (non-renamed imports, assignments
+to unresolved globals, 11 ambient `declare` cases). Beyond Deno it also checks
+type parameters, interface and type-literal members, class methods, and
+labels. The user accepted these differences.

.agents/memory/package-json-shape.md

@@ -0,0 +1,40 @@
+---
+description: package.json keys follow Oxfmt's standard order (vp check --fix); standard fields only; no peerDependencies or packageManager
+---
+
+## Key order (2026-10-16)
+
+Oxfmt's standard `package.json` sorting is accepted: there is no
+`fmt: { sortPackageJson: false }`, and `vp check --fix` sets the order. This
+replaces the earlier hand-written order (metadata, `scripts`, `exports`,
+`imports`, `devDependencies`, `dependencies`).
+
+The `imports` key order can carry meaning: the import-structure plugin's
+`enforce-layer-order` reads it as the layer order. Never reorder it casually.
+
+## Fields
+
+- **Standard fields only.** App repos have no `engines` field (user decision
+  2026-10-18; images pin Node, [[toolchain-node-vite-plus]]). Published
+  packages keep `engines` with only `node` (never `engines.bun`).
+  A tool-owned key (`eslint-doc-generator`) is allowed only because the tool
+  reads nothing else and no other config file is allowed.
+- **No `packageManager`.** npm is detected from `package-lock.json`.
+- **No `peerDependencies`, ever** (user preference, 2026-10-14). If something
+  is needed at runtime, it goes in `dependencies`.
+- **`dependencies`** = what runs or is type-referenced at runtime by consumers
+  (the lit-robust plugin ships `parse5`, `oxc-parser`, `oxc-resolver`, and
+  `@eslint/core` for its public types; they stay external, never bundled).
+- **`devDependencies`** = everything else: `vite-plus`, `eslint`,
+  `@typescript-eslint/parser`, `eslint-doc-generator`, `esbuild`,
+  `typescript-6`, `@types/node`. ESLint is a devDependency only; plugins need
+  nothing from it at runtime.
+
+Refresh the lockfile with `npm install` (or `npm install
+--package-lock-only` for a version bump) and commit it with the change.
+
+Alias rule: an alias may point anywhere and owns its target (a folder's
+`index.ts` owns the folder and everything below it; any other file owns only
+itself). No two aliases may own the same file, outside an area only the exact
+alias reaches it, and `../` is banned in every file
+([[imports-aliases-barrels]]).

.agents/memory/project-lint-plugin.md

@@ -0,0 +1,63 @@
+---
+description: scripts/project-lint.ts is the repo-local plugin "project" holding the repo's rule list (typed DummyRuleMap) and repo-only rules; never published, no tests
+---
+
+Every repo has `scripts/project-lint.ts`, copied from
+`cunarist/eslint-plugin-explicit-types` and extended. It is a repo-local
+Oxlint plugin with `meta.name` `"project"`, loaded through `jsPlugins` in
+`vite.config.ts`. It holds:
+
+- **`configs.project.rules`**: the repo's whole rule list beyond the published
+  plugin configs: Deno parity rules, extras, per-rule options, and opt-outs,
+  built-in Oxlint ids included (`curly`, `id-match`, `import/no-cycle`, ...).
+- **Custom rules**, enabled as `project/<rule>`. Every repo has
+  `no-disable-comments` and `no-asset-imports`. Since 2026-10-19 every repo
+  also has `prefer-ascii`, `no-nan` (a "no number" value is `null`, never
+  `NaN`), and the hugoalh `recommended` ports from
+  eslint-plugin-import-structure's own lint: `no-duplicate-typeofs`,
+  `no-empty-yield`, `no-unsafe-number`, `no-useless-continue`,
+  `no-duplicate-interfaces`, `no-duplicate-types`, `no-useless-type`, and
+  `no-modifier-private`. `no-duplicate-awaits` and `no-duplicate-voids` are
+  covered by `unicorn/no-unnecessary-await` and
+  `typescript/no-meaningless-void-operator`, and `no-enum` by explicit-types.
+
+`scripts/` stays flat; don't add `scripts/rules/`. All rules live in the one
+`scripts/project-lint.ts` (no file splitting), next to the plugin object and
+the rule list.
+
+```ts
+import type { DummyRuleMap } from "vite-plus/lint";
+
+const rules: DummyRuleMap = {
+  "id-match": ["error", "^_*[^_]*_*$|^[^a-z]*$", {/* ... */}],
+  curly: "error",
+  "project/no-disable-comments": "error",
+};
+
+const plugin = {
+  meta: { name: "project" },
+  rules: { "no-disable-comments": noDisableCommentsRule /* ... */ },
+  configs: { project: { rules } },
+};
+export default plugin;
+```
+
+## Why `DummyRuleMap` and an unannotated plugin (decided 2026-10-15)
+
+- `DummyRuleMap` (re-exported by `vite-plus/lint`) is Oxlint's type for
+  `OxlintConfig.rules`. Despite the name it lists every built-in rule with its
+  options, so a typo in a rule id or option is a type error, not just a CI
+  failure. Without it, TypeScript widens `"error"` to `string`; `as const`
+  doesn't help because Oxlint wants mutable tuples.
+- `@eslint/core`'s `Plugin` is too loose to read back: `configs` is optional,
+  any key may be missing, and a config may be an array, so
+  `projectLint.configs.project.rules` fails in `vite.config.ts` (and `!` is
+  banned). Optional chaining still leaves the array case.
+- Oxlint's own `Plugin` type (`vite-plus/lint/plugins`) has no `configs`.
+- Two hand-written interfaces worked but were dropped as noise; a plain
+  config object was rejected because custom rules need the plugin form anyway
+  and every repo should look the same.
+
+`scripts/` is tooling, not production code: never packed or published, and
+no tests. Its offs sit in the Node code entry of `projectOverrides`; see
+[[lint-config]].

.agents/memory/tests-layout-vitest.md

@@ -0,0 +1,39 @@
+---
+description: Vitest via vp test; unit tests sit next to code as *.test.ts, regression/integration tests in tests/ via the public entry (through its # alias, never ../); scripts/ has no tests
+---
+
+Decided 2026-10-14 for all repos.
+
+- **Runner:** Vitest through `vp test`. Import test APIs from
+  `vite-plus/test` (`describe`, `expect`, `it`).
+- **Unit tests** sit next to the code: `src/foo/bar.ts` is tested in
+  `src/foo/bar.test.ts`. Vitest's default include finds them; no `test`
+  config needed. Packages publish only `dist/`, so colocated tests cost nothing
+  in the tarball.
+- **Regression and integration tests** live in the top-level `tests/` folder
+  and use only the public entry point, imported through its `#` alias (e.g.
+  `#plugin` for `./src/plugin/index.ts`), never internals and never `../`,
+  which is banned in every file. `vp test tests` runs just these
+  ([[imports-aliases-barrels]]). In bot-agents, `tests/` imports only
+  `#testing` (`./src/testing/index.ts`), plain helpers that import no source
+  module.
+- **No in-source tests** (`import.meta.vitest`).
+- **`scripts/` gets no tests** (2026-10-15): it is repo tooling, not
+  production code (`project-lint.ts`, `protect-source.sh`).
+- Test files follow every lint rule; no relaxed overrides for tests.
+
+## Migrating Deno tests
+
+`Deno.test` suites were converted by a codemod
+(`~/.local/share/deno-migration/src/convert.ts` on the user's machine), then
+its TODOs finished by hand. Watch for:
+
+- `@std/assert` → `expect` (`assertEquals` → `toStrictEqual` or `toBe`,
+  `assertThrows` → `toThrow`, `assertRejects` → `rejects.toThrow`);
+- `Deno.*` file, env, and process APIs → `node:fs`, `process.env`,
+  `node:child_process`;
+- `t.step` → nested `describe`/`it`;
+- sanitizer options, which Vitest doesn't have.
+
+A migration PR must keep every test case; a dropped case is lost coverage.
+Tests must pass locally before any push.

.agents/memory/toolchain-node-vite-plus.md

@@ -0,0 +1,61 @@
+---
+description: Node.js (no engines in apps; images pin 24) with Vite+ (vp) and npm; only package.json, tsconfig.json, vite.config.ts plus a committed package-lock.json
+---
+
+## The stack
+
+- **Runtime:** Node.js. App repos have no `engines` field (user decision
+  2026-10-18): the container or runner image decides the version, so the
+  Containerfile base image (`node:24-alpine`) and CI's `node-version: "24"`
+  are the pins. Published packages (the lint plugins) keep their own
+  `engines.node` floor. `npm run lit-check` runs
+  `node scripts/lit-check.ts`, which needs Node 22.18+ (unflagged type
+  stripping and `module.registerHooks`); Node 24 satisfies it. Without
+  `engines` or a `.node-version`, local `vp` uses its default Node
+  (`vp env default`). bot-agents has no Containerfile or setup step: the
+  self-hosted runner's `node:24-bookworm` job image runs the action and its
+  checks, and `src/post/index.ts` needs 24.2+ (`import.meta.main`).
+- **Bun is not supported** (dropped 2026-10-15). No Bun CI legs, docs, or
+  runtime branches. Oxlint's `RuleTester` refuses to run under Bun anyway, and
+  `vp` brings its own Node, the way uv brings its own Python.
+- **Toolchain:** Vite+ (`vite-plus` devDependency, command `vp`): Vite,
+  Vitest, Oxlint, Oxfmt, type checking, tsdown.
+- **Package manager:** npm everywhere. `package-lock.json` is committed in
+  apps _and_ libraries (user agreed 2026-10-14: `npm ci` needs it). There is no
+  `packageManager` field; Vite+ detects npm from the lockfile.
+
+## Config files
+
+Exactly three, plus the lockfile: `package.json`, `tsconfig.json`,
+`vite.config.ts`. No `.oxlintrc.json`, `.prettierrc`, `eslint.config.*`,
+`vitest.config.*`, `.npmrc`, or `tsdown.config.*`. Tool options go into
+`vite.config.ts` keys (`lint`, `fmt`, `test`, `pack`) or, when a tool only
+reads `package.json` (eslint-doc-generator), into a `package.json` key.
+The target is a short `vite.config.ts`, around 30 lines (not strict).
+
+## Commands
+
+| Command                  | Does                                                       |
+| ------------------------ | ---------------------------------------------------------- |
+| `vp check`               | format check, Oxlint (type-aware), and type check together |
+| `vp check --fix`         | the same, applying formatting and safe fixes               |
+| `vp test`                | Vitest; `vp test tests` runs only the top-level `tests/`   |
+| `vp build`               | Vite production build (apps)                               |
+| `vp dev`                 | Vite dev server (apps)                                     |
+| `vp pack`                | tsdown library build into `dist/` (packages)               |
+| `npm ci` / `npm install` | install; never another package manager                     |
+
+`vp check`, `vp test`, and the build (`vp build` or `vp pack`) must all pass
+before any push. CI installs the toolchain with `voidzero-dev/setup-vp`.
+
+## Gotchas found during the migration
+
+- `vp check` does **not** report `isolatedDeclarations` errors (TS9010); only
+  `vp pack` does, so packages run `vp pack` in CI on every PR.
+- Oxfmt sorts `package.json` keys by default; that order is accepted, so
+  there is no `fmt` option for it ([[package-json-shape]]).
+- Oxlint and Oxfmt skip what `.gitignore` lists; that is the only reason
+  `dist/` and `node_modules/` are not linted. Keep build output gitignored.
+- Vite+ bundles `vite.config.ts` itself and resolves `#` imports in it.
+- Oxlint loads a `.ts` plugin file directly on Node 24 (`jsPlugins`), so
+  repo-local lint plugins need no build step.

.agents/memory/ts-only-files-and-imports.md

@@ -0,0 +1,59 @@
+---
+description: Every file is .ts (no js/mjs/cjs/jsx/tsx, configs included); imports name only .ts files or .js/.mts/.mjs package subpaths; CSS comes from HTML, JSON/SVG become .ts modules
+---
+
+The user's rule, from the Deno days and restated for Node (2026-10-12): "No
+JS, not even JSX/TSX, only TS." Source, scripts, tests, and configs are all
+plain `.ts`. Build output in a gitignored folder is the only JS.
+
+`tsconfig.json`: no `allowJs`, no `jsx`, and exactly this strictness set (user
+decision, 2026-10-18): `strict` (written out), `noUncheckedIndexedAccess`,
+`noPropertyAccessFromIndexSignature`, `noImplicitReturns`, `noUnusedLocals`,
+`noUnusedParameters`, `noImplicitOverride`, `noFallthroughCasesInSwitch`,
+`erasableSyntaxOnly`, and `allowUnreachableCode: false` plus
+`allowUnusedLabels: false` (user decision, 2026-10-18; on in the Deno setup),
+plus the mechanical `verbatimModuleSyntax`, `allowImportingTsExtensions`, and
+`noEmit` (packages also keep `declaration` and `isolatedDeclarations`).
+`exactOptionalPropertyTypes` is off everywhere: write `{ key: maybeUndefined }`
+rather than leaving the key out to please it. If a tool or framework seems to
+need a JS or TSX file, stop and flag it instead of adding one.
+
+## No asset imports (2026-10-14, widened 2026-10-16 and 2026-10-17)
+
+`project/no-asset-imports` (in `scripts/project-lint.ts`; it was
+`no-non-ts-imports` before 2026-10-16) fails:
+
+- a relative, absolute, `#`, or package-subpath specifier whose last segment
+  has an extension other than `.ts`, `.js`, `.mts`, or `.mjs`: `.css`,
+  `.json`, `.svg`, `.jsx`, `.tsx`, and every other asset;
+- any `?query` suffix (`?raw`, `?url`, `?inline`);
+- any import attributes (`with { type: "json" }`, `with { type: "text" }`).
+
+`.js`, `.mts`, and `.mjs` are allowed (user decision, 2026-10-17) for package
+subpaths such as `lit/decorators.js` or `pdfjs-dist/legacy/build/pdf.mjs`;
+our own files are still `.ts` only. `.jsx` and `.tsx` stay banned. Bare
+packages (`lit`, `@types/json-schema`, `lodash.debounce`), `#` aliases, and
+`node:` builtins pass. `@fortawesome/x/svgs/a.svg` fails.
+
+```ts
+import "./theme.css"; // no
+import data from "./scenes.json" with { type: "json" }; // no
+import icon from "./lock.svg?raw"; // no
+import { scenes } from "#data/scenes"; // yes: scenes.ts
+```
+
+## What to do instead
+
+- **CSS:** load it from HTML with `<link rel="stylesheet" href="...">`. Never
+  import CSS from TS, not even for Vite. (This also removes most of the
+  `import/no-unassigned-import` hits the `suspicious` category reports.)
+- **JSON data:** turn it into a `.ts` module exporting a typed constant.
+- **SVG:** a `.ts` module exporting the markup.
+- **`package.json` fields at runtime:** never `import pkg from
+  "./package.json"` and there is no `#package` alias. Write the value out in
+  `.ts` and add a test in `tests/` that reads `package.json` with `node:fs`
+  and fails on drift (the plugin repos do this for `meta.name`/`meta.version`).
+- **Reading a file is not importing it.** `readFileSync` + `JSON.parse` is
+  fine in tooling and tests.
+- **A tool's CLI file:** prefer the package entry or spawning the package's
+  bin over importing `pkg/cli.js`, which runs the CLI as a side effect.

.agents/memory/working-with-the-user.md

@@ -0,0 +1,53 @@
+---
+description: Ask one decision at a time with a code example, follow ESLint/ecosystem conventions and ask before deviating, keep config minimal, and never block when the user is away
+---
+
+## Asking
+
+- **One question at a time.** Each decision question stands alone, with the
+  options and a recommendation.
+- **Show code.** The user is new to the ESLint ecosystem and asked for
+  example code blocks whenever possible (2026-10-14): before/after snippets
+  or config examples, not prose alone.
+
+  ```ts
+  // A. per-file override          // B. refactor with a barrel
+  overrides: [{ files: [...] }]    import { a, b } from "#ui";
+  ```
+
+- **Keep answers short.** State the decision and what changed; detail belongs
+  in `.agents/memory/`, not chat.
+- The user often probes with "why?" and "is this the simplest form?". Have
+  the reason ready, and prefer the option with fewer lines, fewer files, and
+  fewer custom types when the result is equivalent.
+
+## Conventions over invention
+
+- Follow ESLint's and the wider ecosystem's conventions (typescript-eslint,
+  unicorn as references): `docs/rules/<rule>.md`, one plugin per package,
+  flat configs at `plugin.configs`, `meta.docs.url`, `index.ts` entries.
+- **Any deviation is a question, not a default**, even one carried over from
+  the Deno version. The user was unhappy when rule docs were quietly placed in
+  `src/` ("You should have asked me about this though. We should respect
+  ESLint's way").
+- Before finishing structural work, compare against well-known projects and
+  list every difference for the user.
+
+## When the user is away
+
+- **Never block on the user.** No approval requests, no waiting. Pick the
+  conservative option consistent with these notes, write the choice and its
+  reason in the PR or report, and continue. (An idle approval request once
+  cost hours; the user was emphatic.)
+- Log open questions where the user will look: the PR body, and the shared
+  questions file the coordinator names (during the migration,
+  `~/.local/share/deno-migration/morning-questions.md`).
+- Hard limits still hold without asking: no merging, no publishing, no
+  archiving, no pushing to `main`, no external state changes.
+
+## Working style the user expects from agents
+
+- Keep the main conversation free: repo edits, commits, and long checks run
+  in background subagents.
+- Fan independent work out to many parallel subagents (more than five when it
+  splits), each in its own worktree when they share a branch.

.agents/memory/yaml-stays-declarative.md

@@ -0,0 +1,7 @@
+---
+description: Workflow and container YAML stays declarative; operational shell belongs in separate scripts
+---
+
+Do not embed multiline operational scripts in workflow, Compose, or container
+YAML. Keep YAML declarative and move shell logic into a small, named `.sh` file
+that can be tested directly.

.agents/scratch/.gitignore

@@ -0,0 +1 @@
+*

.agents/skills/review-cycle/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: review-cycle
+description: After opening a PR, run review rounds until fully approved; @bot on Capsulizers Gitea repos, an adversarial subagent review posted as a PR comment elsewhere; then hand to the user, never merge
+---
+
+Every PR gets reviewed before the user sees it. Repeat rounds until the
+review is a full approval (cap: 6 rounds; if still not approved, stop and
+report what remains). Never approve to finish early, and never merge.
+
+## Capsulizers repos (git.capsulizers.com) with `.gitea/workflows/agents.yml`
+
+1. Comment `@bot` on the PR through the Gitea API, as the user's own account
+   (credentials from the user's environment, sourced in a subshell, never
+   printed).
+2. Wait for the review from the `bot` account (poll about every 2 minutes,
+   up to about 30 minutes per round).
+3. For each point: fix valid ones with commits on the PR branch; reply
+   briefly with reasons to ones that are wrong.
+4. Re-run `vp check`, the build, and `vp test`, push, and comment `@bot`
+   again. Done when the bot approves.
+
+## Other repos (GitHub, or Gitea without the bot)
+
+1. Have a separate subagent review the **full PR diff** adversarially:
+   correctness, behavior changes, missed Deno APIs, broken build paths, lint
+   parity, and violations of the repo's `.agents/memory` rules.
+2. Post the review as a PR comment headed `Automated review (round N)`,
+   ending with exactly one verdict line: `VERDICT: APPROVED` or
+   `VERDICT: CHANGES REQUESTED`.
+3. Address every point with commits, re-run checks, push, and reply to the
+   review comment summarizing the fixes.
+4. Next round reviews from scratch, not just the fixes. Done when a round's
+   verdict is `APPROVED`.
+
+## After approval
+
+- Ask the user to review (or, when the user is away, list the PR and any open
+  questions in the report and the questions file). Don't wait idle.
+- The user merges (squash). Don't merge even after approval unless the user
+  explicitly allowed it for this PR.

.gitea/workflows/agents.yml

@@ -0,0 +1,48 @@
+name: Agents
+run-name: >-
+  AI bot at
+  #${{ gitea.event.issue.number || gitea.event.pull_request.number }}
+
+on:
+  issues:
+    types: [opened]
+  pull_request:
+    types: [opened, review_requested]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+concurrency:
+  group: >-
+    agents-${{ gitea.event.sender.login == 'bot' && gitea.run_id ||
+    gitea.event.issue.number || gitea.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  agent:
+    if: >-
+      gitea.actor != 'bot' && gitea.event.sender.login != 'bot' &&
+      ((gitea.event_name == 'issues' &&
+      contains(gitea.event.issue.body, '@bot')) ||
+      (gitea.event_name == 'pull_request' &&
+      ((gitea.event.action == 'opened' &&
+      contains(gitea.event.pull_request.body, '@bot')) ||
+      gitea.event.requested_reviewer.login == 'bot')) ||
+      (gitea.event_name == 'issue_comment' &&
+      contains(gitea.event.comment.body, '@bot')) ||
+      (gitea.event_name == 'pull_request_review_comment' &&
+      contains(gitea.event.review.content, '@bot')))
+    permissions:
+      code: write
+      issues: write
+      pull-requests: write
+    runs-on: self-hosted
+    container:
+      volumes:
+        - bot-home:/root
+    steps:
+      - name: Run AI bot
+        uses: https://git.capsulizers.com/commons/bot-agents@main
+        with:
+          master-key: ${{ secrets.BOT_AGENTS_MASTER_KEY }}

.gitea/workflows/check.yml

@@ -5,17 +5,18 @@ on:
     branches: [main]
 
 jobs:
-  deno:
+  check:
     runs-on: self-hosted
     steps:
       - uses: actions/checkout@v4
 
-      - run: apt-get update && apt-get install -y unzip
+      # The action runs on this same image; src/post/index.ts needs Node 24.2+.
+      - run: node --version
 
-      - uses: denoland/setup-deno@v2
+      - run: npm ci
 
-      - run: >-
-          deno fmt --check . &&
-          deno lint . &&
-          deno check run.ts &&
-          deno test
+      # Formatting, lint, and type checks, then every test. The job runs as
+      # root, so the isolation tests run rather than skip.
+      - run: npx vp check
+
+      - run: npx vp test

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+coverage/

AGENTS.md

@@ -0,0 +1,61 @@
+At the start of every new session, run `damem recall` in the terminal and treat
+its output as the context for this repository. If the `damem` command is not
+found, read [INSTALL.md](https://github.com/cunarist/damem/blob/main/INSTALL.md)
+and follow it before reasoning or responding.
+
+# Pull requests
+
+Land every change through a pull request. Immediately after creating one,
+comment `@bot` to request an AI-bot review. Wait for green CI and the bot's
+approval on the current head before merging. Never merge without the user's
+explicit permission.
+
+# Runtime and checks
+
+The action's TypeScript runs directly on the job image's Node.js (24.2 or
+newer; `package.json` has no `engines`, the `node:24-bookworm` image pins it),
+which strips the types itself: there is no build step and no runtime
+dependency. Keep the sources to erasable syntax and `.ts` imports, which
+`tsconfig.json` enforces. Its strictness set is fixed and leaves
+`exactOptionalPropertyTypes` off
+([.agents/memory/ts-only-files-and-imports.md](.agents/memory/ts-only-files-and-imports.md)).
+Checks use Vite+: `vp check` formats, lints, and type-checks, and `vp test`
+runs Vitest. Unit tests sit next to the code as `*.test.ts` in `src/`;
+repository-level tests live in `tests/`.
+
+A `#` alias in `package.json` `imports` may point anywhere and owns its
+target: an alias to a folder's `index.ts` owns that folder and everything
+below it; an alias to any other file owns only that file. No overlap: no file
+may be owned by 2 aliases, so no alias inside another alias's area and no 2
+aliases with the same target. Outside an area, only the exact alias reaches
+it; a deeper alias specifier or a relative path into the area is a bypass.
+Inside an area, relative imports of siblings and subfolders are free. A `../`
+import is banned in every file, owned or not
+(`import/no-relative-parent-imports`); runtime file URLs such as
+`new URL("../prompt.md", import.meta.url)` are paths, not imports, and stay.
+Files no alias owns need no `index.ts` and no alias, and import `./` siblings
+and subfolders freely. Every top-level entry of `src/` is an aliased module
+folder. The aliases, in layer order, are the three phases `#prepare`, `#run`,
+and `#post`, then `#agents` (Codex,
+Claude Code and OpenCode specifics), `#processes` (child processes and the
+isolated profile users), `#runtime` (the prepared runtime and its
+credentials), `#profiles`, `#common` (error and JSON checks), and `#testing`
+(test helpers), each with a `src/<name>/index.ts` barrel. A phase's
+`index.ts` is also its entry point, which `action.yml` runs as
+`node src/<phase>/index.ts`. Tests that use the test
+helpers import `#testing`, and `tests/` imports `src/` only through it. Local convention, stricter than the general rule above: in
+this repo, aliases point only at a direct subfolder of `src/`
+(`"#helpers": "./src/helpers/index.ts"`), and code outside `src/` uses `./`
+relative imports. `scripts/` is flat: one file per tool, no subfolders and no `index.ts`, imported directly by file path
+([.agents/memory/imports-aliases-barrels.md](.agents/memory/imports-aliases-barrels.md)).
+
+The only config files are `package.json`, `tsconfig.json`, and
+`vite.config.ts`, plus `package-lock.json`. Repo-local lint rules, the rule
+list, and the `overrides` array (`projectOverrides`) live in
+`scripts/project-lint.ts`
+([.agents/memory/lint-config.md](.agents/memory/lint-config.md)). Lint disable
+comments are not allowed; fix the source instead.
+
+The composite action uses npm only to install the externally distributed
+Claude Code, Codex, and OpenCode command-line tools; do not treat those
+vendor executables as repository TypeScript dependencies.

action.yml

@@ -2,30 +2,11 @@ name: Bot agents
 description: Run a coding agent for approved Gitea issue/PR automation
 
 inputs:
-  bot-type:
-    description: Which bot to run, either `codex` or `claude`
-    required: true
-  author-token:
+  master-key:
     description: >-
-      Gitea token of the account that commits, pushes, and opens pull requests,
-      with the `read:user`, `write:issue`, and `write:repository` scopes. The
-      agent sees it as `GITEA_TOKEN`.
+      Base64url-encoded 256-bit key used to decrypt the central bot profiles
+      and reviewer credential.
     required: true
-  reviewer-token:
-    description: >-
-      Gitea token of the bot account that posts comments and pull request
-      reviews, with the `write:issue` and `write:repository` scopes. Never
-      exposed to the agent, so it must differ from the author.
-    required: true
-  bot-token:
-    description: API key or token for the selected bot
-    required: false
-  model:
-    description: >-
-      Model for the selected bot. Defaults to `claude-sonnet-5` or
-      `gpt-5.6-terra`, the mid tiers, which cover reviews and fixes.
-    required: false
-
 runs:
   using: composite
   steps:
@@ -33,23 +14,52 @@ runs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-        token: ${{ inputs.author-token }}
-    # This step assumes this is `node:24-bookworm` container.
+        token: ${{ gitea.token }}
+    # This step assumes this is `node:24-bookworm` container. The action runs
+    # its TypeScript on that Node directly.
     - name: Install dependencies
       shell: bash
-      run: npm install -g @openai/codex @anthropic-ai/claude-code deno
-    - name: Run bot
+      run: npm install -g @openai/codex @anthropic-ai/claude-code opencode-ai
+    # A local action lives inside the writable checkout. Execute a root-owned
+    # copy so an agent changing this repository cannot replace a later phase.
+    - name: Protect action source
+      id: source
       shell: bash
-      run: deno run -A "${ACTION_PATH}/run.ts"
       env:
         ACTION_PATH: ${{ gitea.action_path }}
-        BOT_TYPE: ${{ inputs.bot-type }}
-        BOT_TOKEN: ${{ inputs.bot-token }}
-        MODEL: ${{ inputs.model }}
+        RUNNER_TEMP: ${{ runner.temp }}
+      run: bash "${{ gitea.action_path }}/scripts/protect-source.sh"
+    - name: Allow isolated profiles to edit the checkout
+      shell: bash
+      run: chmod -R a+rwX "${GITHUB_WORKSPACE}"
+    - name: Prepare credentials
+      id: prepare
+      shell: bash
+      run: node "${{ steps.source.outputs.path }}/src/prepare/index.ts"
+      env:
+        ACTION_PATH: ${{ steps.source.outputs.path }}
+        BOT_AGENTS_MASTER_KEY: ${{ inputs.master-key }}
+        RUNNER_TEMP: ${{ runner.temp }}
+    - name: Run bot
+      id: agent
+      shell: bash
+      run: node "${{ steps.source.outputs.path }}/src/run/index.ts"
+      env:
+        BOT_AGENTS_MANIFEST: ${{ steps.prepare.outputs.manifest }}
+        GITEA_TOKEN: ${{ gitea.token }}
         GITEA_API_URL: ${{ gitea.api_url }}
         GITEA_REPOSITORY: ${{ gitea.repository }}
-        GITEA_TOKEN: ${{ inputs.author-token }}
-        REVIEWER_TOKEN: ${{ inputs.reviewer-token }}
         EVENT_NAME: ${{ gitea.event_name }}
         ISSUE_INDEX: ${{ gitea.event.issue.number || gitea.event.pull_request.number }}
         COMMENT: ${{ toJSON(gitea.event.comment || gitea.event.review) }}
+    - name: Post result and remove credentials
+      id: post
+      if: always() && steps.prepare.outputs.manifest != ''
+      shell: bash
+      run: node "${{ steps.source.outputs.path }}/src/post/index.ts"
+      env:
+        BOT_AGENTS_MANIFEST: ${{ steps.prepare.outputs.manifest }}
+        GITEA_API_URL: ${{ gitea.api_url }}
+        GITEA_REPOSITORY: ${{ gitea.repository }}
+        EVENT_NAME: ${{ gitea.event_name }}
+        ISSUE_INDEX: ${{ gitea.event.issue.number || gitea.event.pull_request.number }}

auth.ts

@@ -1,12 +0,0 @@
-export async function retryInvalidToken<
-  T extends { status: { success: boolean }; error: string },
->(attempt: () => Promise<T>, relogin: () => Promise<void>): Promise<T> {
-  let result = await attempt();
-  if (
-    !result.status.success && result.error.includes("invalid_refresh_token")
-  ) {
-    await relogin();
-    result = await attempt();
-  }
-  return result;
-}

auth_test.ts

@@ -1,44 +0,0 @@
-import { assertEquals } from "jsr:@std/assert@1";
-import { retryInvalidToken } from "./auth.ts";
-
-Deno.test("retries once after an invalid refresh token", async () => {
-  let attempts = 0;
-  let relogins = 0;
-  const result = await retryInvalidToken(
-    () =>
-      Promise.resolve({
-        status: { success: false },
-        error: attempts++ === 0 ? "invalid_refresh_token" : "still failed",
-      }),
-    () => {
-      relogins++;
-      return Promise.resolve();
-    },
-  );
-
-  assertEquals({ attempts, relogins, error: result.error }, {
-    attempts: 2,
-    relogins: 1,
-    error: "still failed",
-  });
-});
-
-Deno.test("does not retry an unrelated failure", async () => {
-  let attempts = 0;
-  let relogins = 0;
-  await retryInvalidToken(
-    () => {
-      attempts++;
-      return Promise.resolve({
-        status: { success: false },
-        error: "rate limited",
-      });
-    },
-    () => {
-      relogins++;
-      return Promise.resolve();
-    },
-  );
-
-  assertEquals({ attempts, relogins }, { attempts: 1, relogins: 0 });
-});

package.json

@@ -0,0 +1,26 @@
+{
+  "name": "bot-agents",
+  "private": true,
+  "description": "A Gitea composite action that runs a coding agent for approved issue and pull request automation.",
+  "type": "module",
+  "imports": {
+    "#prepare": "./src/prepare/index.ts",
+    "#run": "./src/run/index.ts",
+    "#post": "./src/post/index.ts",
+    "#agents": "./src/agents/index.ts",
+    "#processes": "./src/processes/index.ts",
+    "#runtime": "./src/runtime/index.ts",
+    "#profiles": "./src/profiles/index.ts",
+    "#common": "./src/common/index.ts",
+    "#testing": "./src/testing/index.ts"
+  },
+  "devDependencies": {
+    "@eslint/core": "^0.17.0",
+    "@types/node": "^24.19.2",
+    "@typescript-eslint/types": "^8.71.2",
+    "eslint-plugin-explicit-types": "^0.7.2",
+    "eslint-plugin-import-structure": "^0.13.0",
+    "vite-plus": "^1.2.0",
+    "yaml": "^2.9.1"
+  }
+}

profiles.json

@@ -0,0 +1,19 @@
+{
+  "reviewer-token": "v1:XFUvCI9PnXVaW-ig:_3S9BvXywUp29cVYGA_EzFScKwC5oHkV9x2Ld8k-V_uiG7iA8n3fmjXCArzh2Lz-JDgy3IMTHoY",
+  "profiles": [
+    {
+      "type": "CLAUDE",
+      "model": "claude-sonnet-5",
+      "token": "v1:-dyfF6ZicEhjPk4C:WCuMaGd09tYjtzUCl7abloRzPITvP5C35WpR372w3O_tcaD-ls-yV5sJBdU8iIVApZVCC98sY2gOyM3o9RMa8ciJq8Fuys7KxlYOp8QiluL9AYMSQi6rEsSH71EPWnxSACgo3uDQY8bWQpUlEZvXH9O-ZN9A58dh6b3vRg"
+    },
+    {
+      "type": "CODEX",
+      "model": "gpt-5.6-terra"
+    },
+    {
+      "type": "OPENCODE",
+      "model": "openrouter/qwen/qwen3.8-27b",
+      "token": "v1:4qdfJCdUx9jfiabC:8X0ic_J82lPlq_R3uTLaEbQy7UmEh7BgtG0bDKAcc8FeJ0xvEwkGCKaDoLmT5nta03hgjGdcWKjDdOSMi1kSDfp8J7tRTLtMRzDT8GX8OU_PVDPVahQIAU0"
+    }
+  ]
+}

prompt.md

@@ -19,10 +19,8 @@ author's push credentials. Read the code there, run its checks and tests when
 they bear on the task, and push from there.
 
 For a `pull_request` event, and for a comment on a pull request that asks you to
-review it, use the installed `superpowers:requesting-code-review` skill before
-inspecting the PR. Its exact installed instructions and reviewer template are
-included below, so this run fails before reaching you if they could not be
-loaded. You are the reviewer that has already been dispatched, so run the
+review it, use the installed `requesting-code-review` skill before inspecting
+the PR. You are the reviewer that has already been dispatched, so run the
 skill's code reviewer template yourself instead of dispatching another reviewer.
 Use the pull request and triggering instruction as its description and
 requirements, and review the exact base and head SHAs without changing code. Run
@@ -47,19 +45,11 @@ addressed to the author; the author's own agent picks the fixes up, so never ask
 and pixel-perfect, and that included screenshots prove the intended result was
 achieved.
 
-# Installed Superpowers review skill
-
-${SUPERPOWERS_REVIEW_SKILL}
-
-# Installed Superpowers reviewer template
-
-${SUPERPOWERS_REVIEW_TEMPLATE}
-
 Every finding that belongs to one line of the diff goes on that line instead of
 into the body. Write those to `${ANCHORS_PATH}` as a JSON array, each entry
-`{"path": "<path from the repository root>", "line": <number>, "side": "new" |
-"old", "body": "<the finding>"}`.
-`side` is `new` for a line in the head file and `old` for one only in the base
+`{"path": "<path from the repository root>", "line": <number>, "side": "NEW" |
+"OLD", "body": "<the finding>"}`.
+`side` is `NEW` for a line in the head file and `OLD` for one only in the base
 file; `line` is that file's own line number, and it must be a line the diff
 touches, or Gitea refuses the anchor. Write the file only when there is
 something to anchor, and keep each body to the what, the why, and the how, with

run.ts

@@ -1,335 +0,0 @@
-// Runs a coding agent for one Gitea issue or pull request event and posts its
-// final response back. The agent works as the author account through
-// GITEA_TOKEN; everything this script posts goes through the reviewer token,
-// so it appears as the bot account.
-import { TextLineStream } from "jsr:@std/streams@1/text-line-stream";
-import { retryInvalidToken } from "./auth.ts";
-import {
-  type BotType,
-  loadSuperpowersReviewGuide,
-  parseBotType,
-  superpowersInstallCommands,
-  type SuperpowersReviewGuide,
-} from "./superpowers.ts";
-
-type GiteaUser = { login: string; email: string };
-type GiteaComment = { user: GiteaUser; created_at: string; body: string };
-
-const env = (name: string): string => {
-  const value = Deno.env.get(name);
-  if (value === undefined) throw new Error(`${name} is not set`);
-  return value;
-};
-
-const API = env("GITEA_API_URL");
-const REPO = env("GITEA_REPOSITORY");
-const INDEX = env("ISSUE_INDEX");
-const EVENT = env("EVENT_NAME");
-const BOT = parseBotType(env("BOT_TYPE"));
-const AUTHOR_TOKEN = env("GITEA_TOKEN");
-const REVIEWER_TOKEN = env("REVIEWER_TOKEN");
-const RULES_PATH = "repos/commons/code-rules/raw/README.md";
-// The mid tiers: a run follows a fixed template and the project's checks.
-const DEFAULT_MODELS: Record<string, string> = {
-  claude: "claude-sonnet-5",
-  codex: "gpt-5.6-terra",
-};
-const model = (bot: string): string =>
-  Deno.env.get("MODEL") || DEFAULT_MODELS[bot];
-
-// The reviewer token is withheld so the agent cannot approve as the bot.
-const { REVIEWER_TOKEN: _, ...agentEnv } = Deno.env.toObject();
-
-async function gitea(
-  token: string,
-  path: string,
-  body?: unknown,
-): Promise<Response> {
-  const response = await fetch(`${API}/${path}`, {
-    method: body === undefined ? "GET" : "POST",
-    headers: {
-      Authorization: `token ${token}`,
-      "Content-Type": "application/json",
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  if (!response.ok) {
-    throw new Error(`${path}: ${response.status} ${await response.text()}`);
-  }
-  return response;
-}
-
-const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[A-Za-z]`, "g");
-const stripAnsi = (text: string): string => text.replace(ANSI, "");
-
-async function postComment(body: string): Promise<void> {
-  await gitea(REVIEWER_TOKEN, `repos/${REPO}/issues/${INDEX}/comments`, {
-    body: stripAnsi(body),
-  });
-}
-
-// A review is posted whenever the agent wrote one, whether a review request or
-// a comment asked for it. It comes through a file, because a final chat message
-// picks up narration while a file's first line is written on purpose. That line
-// is the verdict, matched whole; anything unexpected only comments, never
-// approves. The mark in front is added here, so it is never part of the match.
-const REVIEW_DIR = await Deno.makeTempDir();
-const REVIEW_PATH = `${REVIEW_DIR}/review.md`;
-const VERDICTS: Record<string, [event: string, mark: string]> = {
-  Approved: ["APPROVED", "✅"],
-  "Changes requested": ["REQUEST_CHANGES", "🛑"],
-};
-
-// A finding about one line is posted on that line of the diff rather than as
-// `file:line` prose in the body. Those anchors come as JSON, so the file and
-// line are structured instead of parsed back out of English; a malformed entry
-// fails the run, because a silently dropped finding is worse than a red run.
-const ANCHORS_PATH = `${REVIEW_DIR}/anchors.json`;
-type Anchor = { path: string; line: number; side: "new" | "old"; body: string };
-
-function parseAnchors(text: string): Anchor[] {
-  const entries: unknown = JSON.parse(text);
-  if (!Array.isArray(entries)) throw new Error(`${ANCHORS_PATH}: not an array`);
-  return entries.map((entry: unknown, index) => {
-    const at = `${ANCHORS_PATH}[${index}]`;
-    if (typeof entry !== "object" || entry === null) {
-      throw new Error(`${at}: not an object`);
-    }
-    const { path, line, side = "new", body } = entry as Record<string, unknown>;
-    if (typeof path !== "string" || path === "") {
-      throw new Error(`${at}.path: expected a repository path`);
-    }
-    if (typeof line !== "number" || !Number.isInteger(line) || line < 1) {
-      throw new Error(`${at}.line: expected a line number`);
-    }
-    if (side !== "new" && side !== "old") {
-      throw new Error(`${at}.side: expected "new" or "old"`);
-    }
-    if (typeof body !== "string" || body.trim() === "") {
-      throw new Error(`${at}.body: expected the finding`);
-    }
-    return { path, line, side, body };
-  });
-}
-
-async function readAnchors(): Promise<Anchor[]> {
-  const written = await Deno.readTextFile(ANCHORS_PATH).catch(() => null);
-  return written === null ? [] : parseAnchors(written);
-}
-
-async function postResult(body: string): Promise<void> {
-  const review = await Deno.readTextFile(REVIEW_PATH).catch(() => null);
-  if (review === null) {
-    if (EVENT === "pull_request") {
-      throw new Error(`no review was written to ${REVIEW_PATH}`);
-    }
-    return postComment(body);
-  }
-  const [verdict, ...rest] = review.split("\n");
-  const [event, mark] = VERDICTS[verdict.trim()] ?? ["COMMENT", "💬"];
-  const post = (anchors: Anchor[]) =>
-    gitea(REVIEWER_TOKEN, `repos/${REPO}/pulls/${INDEX}/reviews`, {
-      body: stripAnsi([`${mark} ${verdict.trim()}`, ...rest].join("\n")),
-      event,
-      comments: anchors.map(({ path, line, side, body }) => ({
-        path,
-        body: stripAnsi(body),
-        new_position: side === "new" ? line : 0,
-        old_position: side === "old" ? line : 0,
-      })),
-    });
-  const anchors = await readAnchors();
-  // Gitea rejects the whole review when an anchor names a line outside the
-  // diff, and a verdict that never lands blocks the pull request, so the body
-  // goes up alone rather than not at all.
-  await post(anchors).catch(async (error: Error) => {
-    if (anchors.length === 0) throw error;
-    console.error(`inline comments rejected: ${error.message}`);
-    await post([]);
-  });
-}
-
-async function run(command: string, args: string[]): Promise<void> {
-  const { success, code } = await new Deno.Command(command, { args }).output();
-  if (!success) throw new Error(`${command} ${args[0]} exited with ${code}`);
-}
-
-// The reviewer uses Superpowers' requesting-code-review template. Both plugin
-// installers are idempotent on the persisted bot home.
-async function installSuperpowers(bot: BotType): Promise<void> {
-  for (const { command, args } of superpowersInstallCommands(bot)) {
-    await run(command, args);
-  }
-}
-
-async function prepareSuperpowers(
-  bot: BotType,
-): Promise<SuperpowersReviewGuide> {
-  await installSuperpowers(bot);
-  const guide = await loadSuperpowersReviewGuide(bot, env("HOME"));
-  console.log(
-    `Loaded Superpowers requesting-code-review ${guide.version} from ${guide.skillPath}`,
-  );
-  console.log(
-    `Loaded Superpowers reviewer template from ${guide.templatePath}`,
-  );
-  return guide;
-}
-
-// Commits belong to the same account as the pull request they end up in.
-async function configureGitAuthor(): Promise<void> {
-  const user: GiteaUser = await (await gitea(AUTHOR_TOKEN, "user")).json();
-  for (const [key, value] of [["name", user.login], ["email", user.email]]) {
-    await run("git", ["config", "--global", `user.${key}`, value]);
-  }
-}
-
-async function renderPrompt(guide: SuperpowersReviewGuide): Promise<string> {
-  const comments: GiteaComment[] = await (await gitea(
-    REVIEWER_TOKEN,
-    `repos/${REPO}/issues/${INDEX}/comments?limit=100`,
-  )).json();
-  const values: Record<string, string> = {
-    COMMENT: env("COMMENT"),
-    ISSUE_COMMENTS: comments
-      .map((c) => `## ${c.user.login} at ${c.created_at}\n\n${c.body}\n`)
-      .join("\n"),
-    CODE_RULES: await (await gitea(REVIEWER_TOKEN, RULES_PATH)).text(),
-    EVENT_NAME: EVENT,
-    GITEA_API_URL: API,
-    GITEA_REPOSITORY: REPO,
-    ISSUE_INDEX: INDEX,
-    REVIEW_PATH,
-    ANCHORS_PATH,
-    SUPERPOWERS_REVIEW_SKILL: guide.skill,
-    SUPERPOWERS_REVIEW_TEMPLATE: guide.template,
-  };
-  const template = await Deno.readTextFile(
-    new URL("prompt.md", import.meta.url),
-  );
-  return template.replace(
-    /\$\{(\w+)\}/g,
-    (match, name) => values[name] ?? match,
-  );
-}
-
-async function runClaude(): Promise<string> {
-  const token = Deno.env.get("BOT_TOKEN");
-  if (!token) {
-    throw new Error(
-      "Run `claude setup-token` locally and set the `bot-token` action input.",
-    );
-  }
-  const prompt = await renderPrompt(await prepareSuperpowers("claude"));
-  const claude = new Deno.Command("claude", {
-    args: [
-      "--print",
-      "--dangerously-skip-permissions",
-      "--model",
-      model("claude"),
-      "--output-format",
-      "stream-json",
-      "--verbose",
-      prompt,
-    ],
-    // Claude refuses --dangerously-skip-permissions as root outside a sandbox.
-    env: { ...agentEnv, CLAUDE_CODE_OAUTH_TOKEN: token, IS_SANDBOX: "1" },
-    clearEnv: true,
-    stdout: "piped",
-  }).spawn();
-  let result: { result?: string; subtype: string } | undefined;
-  // Print events as they stream so the runner does not kill the job as a zombie.
-  const lines = claude.stdout
-    .pipeThrough(new TextDecoderStream())
-    .pipeThrough(new TextLineStream());
-  for await (const line of lines) {
-    if (!line) continue;
-    const event = JSON.parse(line);
-    for (const part of event.message?.content ?? []) {
-      const text = part.thinking ?? part.text ?? part.name;
-      if (text) console.log(text);
-    }
-    if (event.type === "result") result = event;
-  }
-  await claude.status;
-  if (result?.result === undefined) {
-    throw new Error(`claude ended with ${result?.subtype ?? "no result"}`);
-  }
-  return result.result;
-}
-
-// Posts the device code so a human can finish the login on the persisted home.
-async function codexDeviceLogin(): Promise<void> {
-  const login = new Deno.Command("codex", {
-    args: ["login", "--device-auth"],
-    stdout: "piped",
-    stderr: "piped",
-  }).spawn();
-  let shown = "";
-  const collect = (stream: ReadableStream<Uint8Array>): Promise<void> =>
-    stream.pipeThrough(new TextDecoderStream()).pipeTo(
-      new WritableStream({ write: (chunk) => void (shown += chunk) }),
-    );
-  const drained = Promise.all([collect(login.stdout), collect(login.stderr)]);
-  const status = login.status;
-  await new Promise((resolve) => setTimeout(resolve, 3000));
-  while (shown.trim() === "") {
-    const exited = await Promise.race([
-      status.then(() => true),
-      new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 100)),
-    ]);
-    if (exited) throw new Error("AI bot login produced no instructions");
-  }
-  await postComment(shown);
-  await Promise.all([status, drained]);
-}
-
-async function runCodex(): Promise<string> {
-  const loggedIn = await new Deno.Command("codex", {
-    args: ["login", "status"],
-  })
-    .output();
-  if (!loggedIn.success) await codexDeviceLogin();
-  const prompt = await renderPrompt(await prepareSuperpowers("codex"));
-  const file = await Deno.makeTempFile();
-  const attempt = async () => {
-    const codex = new Deno.Command("codex", {
-      args: [
-        "exec",
-        "--model",
-        model("codex"),
-        "--dangerously-bypass-approvals-and-sandbox",
-        "--output-last-message",
-        file,
-        prompt,
-      ],
-      env: agentEnv,
-      clearEnv: true,
-      stdout: "inherit",
-      stderr: "piped",
-    }).spawn();
-    const decoder = new TextDecoder();
-    let error = "";
-    for await (const chunk of codex.stderr) {
-      await Deno.stderr.write(chunk);
-      error += decoder.decode(chunk, { stream: true });
-    }
-    error += decoder.decode();
-    return { status: await codex.status, error };
-  };
-  const { status } = await retryInvalidToken(attempt, async () => {
-    await run("codex", ["logout"]);
-    await codexDeviceLogin();
-  });
-  if (!status.success) throw new Error(`codex exited with ${status.code}`);
-  return await Deno.readTextFile(file);
-}
-
-try {
-  await configureGitAuthor();
-  const result = BOT === "claude" ? await runClaude() : await runCodex();
-  await postResult(result);
-} catch (error) {
-  await postComment(`Bot failed: ${error}`);
-  throw error;
-}

scripts/project-lint.ts

@@ -0,0 +1,959 @@
+/**
+ * `project` - this repository's changes to the Oxlint categories in
+ * `vite.config.ts`. Its rules of its own are `no-disable-comments`,
+ * `no-asset-imports`, `prefer-ascii`, and ports of the hugoalh `recommended`
+ * rules Oxlint lacks, as in eslint-plugin-import-structure's own lint.
+ *
+ * Loaded by `vite.config.ts` as an Oxlint `jsPlugins` entry.
+ *
+ * @module
+ */
+
+import type {
+  LanguageOptions,
+  Position,
+  RuleDefinition,
+  RuleTextEdit,
+  RuleVisitor,
+  TextSourceCode,
+} from "@eslint/core";
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/types";
+import type { DummyRuleMap, OxlintOverride } from "vite-plus/lint";
+
+/** The source code both hosts hand a rule, with the comment list and index lookup. */
+interface ProjectSourceCode extends TextSourceCode {
+  getAllComments: () => TSESTree.Comment[];
+  getLocFromIndex: (index: number) => Position;
+}
+
+/** ESLint's default rule types, reporting TypeScript-ESTree nodes. */
+interface ProjectRuleTypes {
+  LangOptions: LanguageOptions;
+  Code: ProjectSourceCode;
+  RuleOptions: [];
+  Visitor: RuleVisitor;
+  Node: TSESTree.Node;
+  MessageIds: string;
+  ExtRuleDocs: unknown;
+}
+
+/** A repo-local rule, in ESLint's standard `create` form. */
+type ProjectRule = RuleDefinition<ProjectRuleTypes>;
+
+/** A comment that turns lint rules off or back on, in ESLint or Oxlint form. */
+const DIRECTIVE_PATTERN: RegExp = /^\s*(?:eslint|oxlint)-(?:disable|enable)/u;
+
+/** This rule's own name, which a directive may not use to silence it. */
+const RULE_NAME: string = "no-disable-comments";
+
+/**
+ * `no-disable-comments` - rejects every `eslint-disable*`, `eslint-enable*`,
+ * `oxlint-disable*`, and `oxlint-enable*` comment, line or block. Oxlint has
+ * no `noInlineConfig` and no `eslint-comments` rules, so this repo bans them
+ * itself: when a rule fires, fix the source.
+ *
+ * A directive can silence the report on itself, so two built-in checks close
+ * the gaps: `unicorn/no-abusive-eslint-disable` fails one that names no rule,
+ * and this rule skips one that names it, which then silences nothing and fails
+ * `reportUnusedDisableDirectives` in `vite.config.ts`.
+ */
+const noDisableCommentsRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow lint disable and enable comments" },
+    schema: [],
+    messages: {
+      directive: "Lint disable comments are not allowed; fix the source.",
+    },
+  },
+  create(context) {
+    return {
+      Program(_node: TSESTree.Program): void {
+        for (const comment of context.sourceCode.getAllComments()) {
+          if (
+            DIRECTIVE_PATTERN.test(comment.value) &&
+            !comment.value.includes(RULE_NAME)
+          ) {
+            context.report({ loc: comment.loc, messageId: "directive" });
+          }
+        }
+      },
+    };
+  },
+};
+
+/** The highest code point `prefer-ascii` lets through. */
+const MAX_ASCII_CODE_POINT: number = 127;
+
+/**
+ * `prefer-ascii` - every character of the source is ASCII. A file is exempted
+ * only through an entry in `projectOverrides`.
+ */
+const preferAsciiRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Require the source to be ASCII" },
+    schema: [],
+    messages: {
+      nonAscii:
+        "Non-ASCII character '{{character}}' (U+{{codePoint}}) is not allowed.",
+    },
+  },
+  create(context) {
+    return {
+      Program(_node: TSESTree.Program): void {
+        const { sourceCode } = context;
+        let index: number = 0;
+        for (const character of sourceCode.text) {
+          const codePoint: number = character.codePointAt(0) ?? 0;
+          if (codePoint > MAX_ASCII_CODE_POINT) {
+            context.report({
+              loc: {
+                start: sourceCode.getLocFromIndex(index),
+                end: sourceCode.getLocFromIndex(index + character.length),
+              },
+              messageId: "nonAscii",
+              data: {
+                character,
+                codePoint: codePoint
+                  .toString(16)
+                  .toUpperCase()
+                  .padStart(4, "0"),
+              },
+            });
+          }
+          index += character.length;
+        }
+      },
+    };
+  },
+};
+
+/** `no-duplicate-typeofs` - `typeof typeof x` is always `"string"`. */
+const noDuplicateTypeofsRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow `typeof` applied twice in a row" },
+    schema: [],
+    messages: {
+      doubled:
+        'Multiple `typeof`s always return `"string"`, possibly not intended.',
+    },
+  },
+  create(context) {
+    return {
+      UnaryExpression(node: TSESTree.UnaryExpression): void {
+        if (
+          node.operator === "typeof" &&
+          node.argument.type === AST_NODE_TYPES.UnaryExpression &&
+          node.argument.operator === "typeof"
+        ) {
+          context.report({ node, messageId: "doubled" });
+        }
+      },
+    };
+  },
+};
+
+/** `no-empty-yield` - a `yield` with no expression, likely missing one. */
+const noEmptyYieldRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow `yield` without an expression" },
+    schema: [],
+    messages: {
+      empty: "Empty `yield` is not allowed, possibly missing the expression.",
+    },
+  },
+  create(context) {
+    return {
+      YieldExpression(node: TSESTree.YieldExpression): void {
+        if (node.argument === null) {
+          context.report({ node, messageId: "empty" });
+        }
+      },
+    };
+  },
+};
+
+/** The globals `no-nan` sees through, as in `globalThis.Number.NaN`. */
+const GLOBAL_NAMES: ReadonlySet<string> = new Set<string>([
+  "globalThis",
+  "self",
+  "window",
+]);
+
+/** The name a member expression's property spells, computed or not. */
+function propertyName(node: TSESTree.MemberExpression): string | null {
+  if (node.property.type === AST_NODE_TYPES.Identifier && !node.computed) {
+    return node.property.name;
+  }
+  if (
+    node.property.type === AST_NODE_TYPES.Literal &&
+    typeof node.property.value === "string"
+  ) {
+    return node.property.value;
+  }
+  return null;
+}
+
+/** Whether `node` is a global object, such as `globalThis` or `globalThis.self`. */
+function isGlobalChain(node: TSESTree.Expression): boolean {
+  if (node.type === AST_NODE_TYPES.Identifier) {
+    return GLOBAL_NAMES.has(node.name);
+  }
+  return (
+    node.type === AST_NODE_TYPES.MemberExpression &&
+    GLOBAL_NAMES.has(propertyName(node) ?? "") &&
+    isGlobalChain(node.object)
+  );
+}
+
+/**
+ * Whether a member expression reads the global `NaN`: `Number.NaN`,
+ * `globalThis.NaN`, or `globalThis.Number.NaN`.
+ */
+function isNanMember(node: TSESTree.MemberExpression): boolean {
+  if (propertyName(node) !== "NaN") {
+    return false;
+  }
+  const { object } = node;
+  if (object.type === AST_NODE_TYPES.Identifier && object.name === "Number") {
+    return true;
+  }
+  return (
+    isGlobalChain(object) ||
+    (object.type === AST_NODE_TYPES.MemberExpression &&
+      propertyName(object) === "Number" &&
+      isGlobalChain(object.object))
+  );
+}
+
+/** `no-nan` - a `NaN` value is usually an error; use `null` for "no number". */
+const noNanRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow `NaN` as a value" },
+    schema: [],
+    messages: {
+      nan: "Using `NaN` as a value is usually an error and not intended.",
+    },
+  },
+  create(context) {
+    return {
+      Identifier(node: TSESTree.Identifier): void {
+        if (
+          node.name === "NaN" &&
+          node.parent.type !== AST_NODE_TYPES.MemberExpression
+        ) {
+          context.report({ node, messageId: "nan" });
+        }
+      },
+      MemberExpression(node: TSESTree.MemberExpression): void {
+        if (isNanMember(node)) {
+          context.report({ node, messageId: "nan" });
+        }
+      },
+    };
+  },
+};
+
+/** `no-unsafe-number` - a number literal outside the safe integer range. */
+const noUnsafeNumberRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow number literals outside the safe integer range",
+    },
+    schema: [],
+    messages: {
+      unsafe:
+        "Number literals with values equal to 2^53 or greater are too large to be represented accurately.",
+    },
+  },
+  create(context) {
+    return {
+      Literal(node: TSESTree.Literal): void {
+        if (
+          typeof node.value === "number" &&
+          (node.value < Number.MIN_SAFE_INTEGER ||
+            node.value > Number.MAX_SAFE_INTEGER)
+        ) {
+          context.report({ node, messageId: "unsafe" });
+        }
+      },
+    };
+  },
+};
+
+/** A loop statement, whose last `continue` `no-useless-continue` checks. */
+type LoopStatement =
+  | TSESTree.DoWhileStatement
+  | TSESTree.ForInStatement
+  | TSESTree.ForOfStatement
+  | TSESTree.ForStatement
+  | TSESTree.WhileStatement;
+
+/** A loop's trailing unlabeled `continue`, and whether removing it is a safe fix. */
+interface TrailingContinue {
+  statement: TSESTree.ContinueStatement;
+  removable: boolean;
+}
+
+/**
+ * The unlabeled `continue` a loop ends with, and whether removing it is a
+ * safe fix: it is in a block, rather than the loop's whole body.
+ */
+function trailingContinue(node: LoopStatement): TrailingContinue | null {
+  if (node.body.type === AST_NODE_TYPES.BlockStatement) {
+    const last = node.body.body.at(-1);
+    return last?.type === AST_NODE_TYPES.ContinueStatement &&
+      last.label === null
+      ? { statement: last, removable: true }
+      : null;
+  }
+  if (
+    node.body.type === AST_NODE_TYPES.ContinueStatement &&
+    node.body.label === null
+  ) {
+    return { statement: node.body, removable: false };
+  }
+  return null;
+}
+
+/**
+ * `no-useless-continue` - an unlabeled `continue` that ends a loop body. A
+ * trailing `continue;` in a block is removed by the fix; a loop whose whole
+ * body is `continue;` is only reported.
+ */
+const noUselessContinueRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow an unlabeled `continue` at the end of a loop",
+    },
+    fixable: "code",
+    schema: [],
+    messages: {
+      useless:
+        "The statement `continue` at the end of the loop and without a label is useless.",
+    },
+  },
+  create(context) {
+    function check(node: LoopStatement): void {
+      const found: TrailingContinue | null = trailingContinue(node);
+      if (found === null) {
+        return;
+      }
+      if (found.removable) {
+        context.report({
+          node: found.statement,
+          messageId: "useless",
+          fix: (fixer): RuleTextEdit => fixer.remove(found.statement),
+        });
+      } else {
+        context.report({ node: found.statement, messageId: "useless" });
+      }
+    }
+    return {
+      DoWhileStatement: check,
+      ForInStatement: check,
+      ForOfStatement: check,
+      ForStatement: check,
+      WhileStatement: check,
+    };
+  },
+};
+
+/** Node keys that say where a node is, not what it is, in ESLint and Oxlint. */
+const POSITION_KEYS: ReadonlySet<string> = new Set<string>([
+  "parent",
+  "range",
+  "loc",
+  "start",
+  "end",
+]);
+
+/** Node types whose member lists mean the same in any order. */
+const UNORDERED_TYPES: ReadonlySet<string> = new Set<string>([
+  "TSInterfaceBody",
+  "TSTypeLiteral",
+  "TSUnionType",
+  "TSIntersectionType",
+]);
+
+/** Type annotations too simple for an alias of their own (`no-useless-type`). */
+const SIMPLE_TYPES: ReadonlySet<string> = new Set<string>([
+  "TSAnyKeyword",
+  "TSBigIntKeyword",
+  "TSBooleanKeyword",
+  "TSIntrinsicKeyword",
+  "TSNeverKeyword",
+  "TSNullKeyword",
+  "TSNumberKeyword",
+  "TSObjectKeyword",
+  "TSStringKeyword",
+  "TSSymbolKeyword",
+  "TSUndefinedKeyword",
+  "TSUnknownKeyword",
+  "TSVoidKeyword",
+]);
+
+/**
+ * A node's shape as text, without positions, so two declarations compare
+ * alike wherever they sit. Members of a type literal, interface body,
+ * union, or intersection are sorted, since their order means nothing.
+ */
+function serialize(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item: unknown) => serialize(item)).join(",")}]`;
+  }
+  if (typeof value !== "object" || value === null) {
+    return JSON.stringify(value) ?? "undefined";
+  }
+  const unordered: boolean =
+    "type" in value && UNORDERED_TYPES.has(String(value.type));
+  const parts: string[] = Object.entries(value)
+    .filter(([key]: [string, unknown]) => !POSITION_KEYS.has(key))
+    .map(([key, child]: [string, unknown]) => {
+      const text: string =
+        unordered && Array.isArray(child)
+          ? `[${child
+              .map((item: unknown) => serialize(item))
+              .toSorted()
+              .join(",")}]`
+          : serialize(child);
+      return `${key}:${text}`;
+    });
+  return `{${parts.join(",")}}`;
+}
+
+/** The top-level declarations in a block, exported or not, that `matches`. */
+function declarationsOf<T extends TSESTree.Node>(
+  statements: TSESTree.Node[],
+  matches: (node: TSESTree.Node) => node is T,
+): T[] {
+  const found: T[] = [];
+  for (const statement of statements) {
+    const declaration: TSESTree.Node | null =
+      statement.type === AST_NODE_TYPES.ExportNamedDeclaration
+        ? statement.declaration
+        : statement;
+    if (declaration !== null && matches(declaration)) {
+      found.push(declaration);
+    }
+  }
+  return found;
+}
+
+/** Whether a node is an interface declaration. */
+function isInterface(
+  node: TSESTree.Node,
+): node is TSESTree.TSInterfaceDeclaration {
+  return node.type === AST_NODE_TYPES.TSInterfaceDeclaration;
+}
+
+/** Whether a node is a type alias declaration. */
+function isTypeAlias(
+  node: TSESTree.Node,
+): node is TSESTree.TSTypeAliasDeclaration {
+  return node.type === AST_NODE_TYPES.TSTypeAliasDeclaration;
+}
+
+/** Groups nodes by a key and returns the groups with more than one node. */
+function duplicateGroups<T>(nodes: T[], keyOf: (node: T) => string): T[][] {
+  const groups: Map<string, T[]> = Map.groupBy(nodes, keyOf);
+  return [...groups.values()].filter((group: T[]) => group.length > 1);
+}
+
+/** What an interface declares, its `extends` list included. */
+function interfaceShape(node: TSESTree.TSInterfaceDeclaration): string {
+  return `${serialize(node.extends)}&${serialize(node.body)}`;
+}
+
+/** An interface's name. */
+function interfaceName(node: TSESTree.TSInterfaceDeclaration): string {
+  return node.id.name;
+}
+
+/** What a type alias stands for. */
+function typeAliasShape(node: TSESTree.TSTypeAliasDeclaration): string {
+  return serialize(node.typeAnnotation);
+}
+
+/**
+ * `no-duplicate-interfaces` - two interfaces in one block with the same
+ * name, which merge silently, or with the same shape, which could be one.
+ */
+const noDuplicateInterfacesRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow interfaces with the same name or shape in one block",
+    },
+    schema: [],
+    messages: {
+      sameShape:
+        "Found multiple interfaces with the same shape, possibly mergeable.",
+      sameName:
+        "Found multiple interfaces named '{{name}}', possibly not intended.",
+    },
+  },
+  create(context) {
+    function check(statements: TSESTree.Node[]): void {
+      const nodes: TSESTree.TSInterfaceDeclaration[] = declarationsOf(
+        statements,
+        isInterface,
+      );
+      for (const node of duplicateGroups(nodes, interfaceShape).flat()) {
+        context.report({ node, messageId: "sameShape" });
+      }
+      for (const node of duplicateGroups(nodes, interfaceName).flat()) {
+        context.report({
+          node,
+          messageId: "sameName",
+          data: { name: node.id.name },
+        });
+      }
+    }
+    return {
+      BlockStatement(node: TSESTree.BlockStatement): void {
+        check(node.body);
+      },
+      Program(node: TSESTree.Program): void {
+        check(node.body);
+      },
+    };
+  },
+};
+
+/** `no-duplicate-types` - two type aliases in one block with the same type. */
+const noDuplicateTypesRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "Disallow type aliases with the same type in one block",
+    },
+    schema: [],
+    messages: {
+      sameShape:
+        "Found multiple types with the same shape, possibly mergeable.",
+    },
+  },
+  create(context) {
+    function check(statements: TSESTree.Node[]): void {
+      const nodes: TSESTree.TSTypeAliasDeclaration[] = declarationsOf(
+        statements,
+        isTypeAlias,
+      );
+      for (const node of duplicateGroups(nodes, typeAliasShape).flat()) {
+        context.report({ node, messageId: "sameShape" });
+      }
+    }
+    return {
+      BlockStatement(node: TSESTree.BlockStatement): void {
+        check(node.body);
+      },
+      Program(node: TSESTree.Program): void {
+        check(node.body);
+      },
+    };
+  },
+};
+
+/** A class member that can carry the `private` keyword. */
+type AccessibilityCarrier =
+  | TSESTree.AccessorProperty
+  | TSESTree.MethodDefinition
+  | TSESTree.PropertyDefinition
+  | TSESTree.TSAbstractAccessorProperty
+  | TSESTree.TSAbstractMethodDefinition
+  | TSESTree.TSAbstractPropertyDefinition
+  | TSESTree.TSParameterProperty;
+
+/**
+ * `no-modifier-private` - class members are made private with `#`, never the
+ * `private` keyword, which only TypeScript enforces. A `private constructor`
+ * has no `#` form and stays allowed.
+ */
+const noModifierPrivateRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Disallow the private modifier" },
+    schema: [],
+    messages: {
+      private: "Use a # private name instead of the private modifier.",
+    },
+  },
+  create(context) {
+    function check(node: AccessibilityCarrier): void {
+      const isConstructor: boolean =
+        node.type === AST_NODE_TYPES.MethodDefinition &&
+        node.kind === "constructor";
+      if (node.accessibility === "private" && !isConstructor) {
+        context.report({ node, messageId: "private" });
+      }
+    }
+    return {
+      AccessorProperty: check,
+      MethodDefinition: check,
+      PropertyDefinition: check,
+      TSAbstractAccessorProperty: check,
+      TSAbstractMethodDefinition: check,
+      TSAbstractPropertyDefinition: check,
+      TSParameterProperty: check,
+    };
+  },
+};
+
+/** Whether a type is too simple to need an alias: a keyword, literal, or bare name. */
+function isSimpleType(node: TSESTree.TypeNode): boolean {
+  if (SIMPLE_TYPES.has(node.type)) {
+    return true;
+  }
+  if (node.type === AST_NODE_TYPES.TSLiteralType) {
+    return node.literal.type === AST_NODE_TYPES.Literal;
+  }
+  return (
+    node.type === AST_NODE_TYPES.TSTypeReference &&
+    node.typeName.type === AST_NODE_TYPES.Identifier &&
+    node.typeArguments === undefined
+  );
+}
+
+/** `no-useless-type` - a type alias for a keyword, literal, or bare type name. */
+const noUselessTypeRule: ProjectRule = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Disallow type aliases too simple to need a name" },
+    schema: [],
+    messages: { simple: "The type is too simple to need an alias." },
+  },
+  create(context) {
+    return {
+      TSTypeAliasDeclaration(node: TSESTree.TSTypeAliasDeclaration): void {
+        if (isSimpleType(node.typeAnnotation)) {
+          context.report({ node, messageId: "simple" });
+        }
+      },
+    };
+  },
+};
+
+/** A module specifier read as a path: relative, absolute, or a `#` alias. */
+const PATH_SPECIFIER_PATTERN: RegExp = /^[./#]/u;
+
+/**
+ * Script module extensions an import may name: our `.ts` files and `.js`,
+ * `.mts`, or `.mjs` package subpaths. `.cts`, `.cjs`, `.tsx`, and `.jsx` are
+ * not among them.
+ */
+const SCRIPT_EXTENSIONS: ReadonlySet<string> = new Set([
+  ".ts",
+  ".js",
+  ".mts",
+  ".mjs",
+]);
+
+/**
+ * Whether `source` names an asset rather than a script module: a query string
+ * such as `?raw`, or a final path segment whose extension, from its last dot,
+ * is not `.ts`, `.js`, `.mts`, or `.mjs`. Bare package names are left alone,
+ * dots and all, as are extensionless paths.
+ */
+function isAssetSource(source: string): boolean {
+  if (source.includes("?")) {
+    return true;
+  }
+  const segments: string[] = source.split("/");
+  if (!PATH_SPECIFIER_PATTERN.test(source)) {
+    const nameLength: number = source.startsWith("@") ? 2 : 1;
+    if (segments.length <= nameLength) {
+      return false;
+    }
+  }
+  const lastSegment: string = segments.at(-1) ?? "";
+  if (
+    lastSegment === "." ||
+    lastSegment === ".." ||
+    !lastSegment.includes(".")
+  ) {
+    return false;
+  }
+  const extension: string = lastSegment.slice(lastSegment.lastIndexOf("."));
+  return !SCRIPT_EXTENSIONS.has(extension);
+}
+
+/**
+ * `no-asset-imports` - rejects importing anything but a script module: a
+ * source path, static or a dynamic `import()` with a string literal, ending in
+ * an extension other than `.ts`, `.js`, `.mts`, or `.mjs` (`.css`, `.json`,
+ * `.svg`, `.jsx`, `.tsx`, `.cjs`) or carrying a query string (`?raw`, `?url`),
+ * and any import or export with import attributes. `.js`, `.mts`, and `.mjs`
+ * cover package subpaths such as `lit/decorators.js` or
+ * `pdfjs-dist/legacy/build/pdf.mjs`; our own files are still `.ts` only. Bare
+ * package names, `#` aliases, and `node:` builtins
+ * without an extension pass; package subpaths are checked like paths.
+ */
+const noAssetImportsRule: ProjectRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing assets instead of .ts, .js, .mts, or .mjs modules",
+    },
+    schema: [],
+    messages: {
+      extension: "Only .ts, .js, .mts and .mjs modules may be imported.",
+      attributes: "Import attributes are not allowed.",
+    },
+  },
+  create(context) {
+    function checkSource(source: TSESTree.StringLiteral): void {
+      if (isAssetSource(source.value)) {
+        context.report({ node: source, messageId: "extension" });
+      }
+    }
+    function checkDeclaration(
+      node:
+        | TSESTree.ImportDeclaration
+        | TSESTree.ExportNamedDeclaration
+        | TSESTree.ExportAllDeclaration,
+    ): void {
+      if (node.source === null) {
+        return;
+      }
+      checkSource(node.source);
+      if (node.attributes.length > 0) {
+        context.report({ node, messageId: "attributes" });
+      }
+    }
+    return {
+      ImportDeclaration: checkDeclaration,
+      ExportNamedDeclaration: checkDeclaration,
+      ExportAllDeclaration: checkDeclaration,
+      ImportExpression(node: TSESTree.ImportExpression): void {
+        if (
+          node.source.type === AST_NODE_TYPES.Literal &&
+          typeof node.source.value === "string"
+        ) {
+          checkSource(node.source);
+        }
+        if (node.options !== null) {
+          context.report({ node, messageId: "attributes" });
+        }
+      },
+    };
+  },
+};
+
+/**
+ * This repository's changes to the Oxlint categories in `vite.config.ts`,
+ * which turn every non-nursery category on: its own rules, the category
+ * rules it turns off, and options that differ from a rule's defaults.
+ */
+const rules: DummyRuleMap = {
+  // The explicit-types template's `camelcase` stand-in: no `_` inside a name
+  // once leading and trailing ones are trimmed, unless it has no lowercase
+  // ASCII letter (UPPER_SNAKE).
+  "id-match": [
+    "error",
+    "^_*[^_]*_*$|^[^a-z]*$",
+    {
+      properties: false,
+      classFields: false,
+      onlyDeclarations: false,
+      ignoreDestructuring: true,
+    },
+  ],
+  // On Node, these come from an explicit `node:` import instead of the global scope.
+  "no-restricted-globals": [
+    "error",
+    "window",
+    "process",
+    "Buffer",
+    "global",
+    "setImmediate",
+    "clearImmediate",
+  ],
+  // Single capital type parameters, which explicit-types requires, may be one letter.
+  "id-length": ["error", { exceptionPatterns: ["^[A-Z]$"] }],
+  // Option tweaks.
+  "one-var": ["error", "never"],
+  "no-use-before-define": ["error", { functions: false }],
+  "func-style": ["error", "declaration", { allowArrowFunctions: true }],
+  // Each limit is the smallest value the current code passes.
+  complexity: ["error", 26],
+  "max-depth": ["error", 6],
+  "max-lines": [
+    "error",
+    { max: 2048, skipBlankLines: false, skipComments: false },
+  ],
+  "max-lines-per-function": ["error", 124],
+  "max-params": ["error", 4],
+  "max-statements": ["error", 32],
+  "import/max-dependencies": ["error", { max: 13 }],
+  "unicorn/max-nested-calls": ["error", { max: 4 }],
+  // No lint suppression and only `.ts` imports, as in the plugin template.
+  "project/no-disable-comments": "error",
+  "project/no-asset-imports": "error",
+  // Ports of the hugoalh `recommended` rules Oxlint lacks, and ASCII-only source.
+  "project/prefer-ascii": "error",
+  "project/no-duplicate-typeofs": "error",
+  "project/no-empty-yield": "error",
+  "project/no-nan": "error",
+  "project/no-unsafe-number": "error",
+  "project/no-useless-continue": "error",
+  "project/no-duplicate-interfaces": "error",
+  "project/no-duplicate-types": "error",
+  "project/no-modifier-private": "error",
+  "project/no-useless-type": "error",
+  // Off, collides with a repo or plugin rule, Oxfmt, or another category rule:
+  // Collides with `#private`: members are public unless marked so.
+  "typescript/explicit-member-accessibility": "off",
+  // Collides with `typescript/prefer-readonly-parameter-types` being off.
+  "typescript/prefer-readonly": "off",
+  // Collides with Node's and the web's mutable types (`Response`, `Stats`).
+  "typescript/prefer-readonly-parameter-types": "off",
+  // Collides with explicit-types `no-utility-types`, which bans `Record`.
+  "typescript/consistent-indexed-object-style": "off",
+  // Collides with explicitly annotated declarations.
+  "typescript/no-inferrable-types": "off",
+  // Collides with import-structure `enforce-import-order`.
+  "sort-imports": "off",
+  // Collides with import-structure `enforce-mod-file` barrels.
+  "oxc/no-barrel-file": "off",
+  // Collides with exporting each declaration where it stands.
+  "import/group-exports": "off",
+  // Collides with exporting each declaration where it stands.
+  "import/exports-last": "off",
+  // Collides with `import/no-default-export`.
+  "import/prefer-default-export": "off",
+  // Collides with `unicorn/prefer-ternary`.
+  "no-ternary": "off",
+  // Collides with `require-await` and `promise-function-async`.
+  "oxc/no-async-await": "off",
+  // Collides with `typescript/prefer-optional-chain`.
+  "oxc/no-optional-chaining": "off",
+  // Collides with file mode checks such as `mode & 0o077`.
+  "no-bitwise": "off",
+  // Collides with explicit-types `no-optional-null`, which makes `undefined` the absent value.
+  "no-undefined": "off",
+  // Collides with `typescript/no-floating-promises`, which `void` satisfies.
+  "no-void": "off",
+  // Collides with JSON and Node APIs, which return `null`.
+  "unicorn/no-null": "off",
+  // Collides with `import/no-default-export`.
+  "import/no-named-export": "off",
+  // Collides with `typescript/consistent-type-imports`.
+  "import/consistent-type-specifier-style": "off",
+  // Collides with Oxfmt, which lowercases hex digits back.
+  "unicorn/number-literal-case": "off",
+  // Node code, everywhere: this action runs on Node.
+  // Node built-ins are the action's runtime.
+  "import/no-nodejs-modules": "off",
+  // Command-line entry points set their exit status.
+  "unicorn/no-process-exit": "off",
+  // The action reports to the job log through the console.
+  "no-console": "off",
+  // Sequential awaits are intentional; workarounds cost more than they save.
+  "no-await-in-loop": "off",
+  // Not type-aware; TypeScript's `noImplicitReturns` covers it.
+  "consistent-return": "off",
+  // Misfires on complete switches, like `consistent-return`; TypeScript covers it.
+  "typescript/consistent-return": "off",
+  // TypeScript's type checking covers exhaustive switches.
+  "typescript/switch-exhaustiveness-check": "off",
+  // TypeScript checks completeness; a forced `default:` hides missing cases.
+  "default-case": "off",
+  // Off, too much churn:
+  // Literal numbers read better than a constant per use.
+  "no-magic-numbers": "off",
+  // Keys follow meaning, not the alphabet.
+  "sort-keys": "off",
+  // Comments may start with code or lowercase identifiers.
+  "capitalized-comments": "off",
+  // explicit-types `require-return-type` covers return types.
+  "typescript/explicit-function-return-type": "off",
+  // explicit-types `require-return-type` covers return types.
+  "typescript/explicit-module-boundary-types": "off",
+  // Empty callbacks are legitimate no-ops.
+  "no-empty-function": "off",
+  // Methods may not need `this`.
+  "class-methods-use-this": "off",
+  // Braces only where a case declares.
+  "unicorn/switch-case-braces": "off",
+  // Plain property reads are fine.
+  "prefer-destructuring": "off",
+  // Object rest and spread are idiomatic.
+  "oxc/no-rest-spread-properties": "off",
+  // Short numbers need no separators.
+  "unicorn/numeric-separators-style": "off",
+  // `continue` keeps loop bodies flat.
+  "no-continue": "off",
+};
+
+/** Node code (`vite.config.ts` and `scripts/`): the first `projectOverrides` entry. */
+const nodeRules: DummyRuleMap = {
+  // Vite and the Oxlint plugin host read a default export.
+  "import/no-default-export": "off",
+};
+
+/**
+ * The whole `overrides` array of `vite.config.ts`: the Node code entry first,
+ * then each per-file exception, each with a comment saying why. Later entries
+ * win over earlier ones, and all of them over `rules`.
+ */
+export const projectOverrides: OxlintOverride[] = [
+  {
+    files: ["vite.config.ts", "scripts/**"],
+    rules: nodeRules,
+  },
+  // exitCode must return the promise it marks handled; an async wrapper's
+  // promise would reject unhandled before callers await it.
+  {
+    files: ["src/processes/child.ts"],
+    rules: { "typescript/promise-function-async": "off" },
+  },
+  // Posted Gitea text shows emoji verdict marks and a middle dot.
+  {
+    files: [
+      "src/post/post.ts",
+      "src/post/post.test.ts",
+      "src/profiles/profiles.ts",
+      "src/profiles/profiles.test.ts",
+    ],
+    rules: { "project/prefer-ascii": "off" },
+  },
+  // The workflow test checks literal Gitea Actions `${{ }}` expressions.
+  {
+    files: ["tests/workflow.test.ts"],
+    rules: { "no-template-curly-in-string": "off" },
+  },
+];
+
+/**
+ * The repo-local plugin, namespace `project`: its own rules, enabled as
+ * `project/<rule>`, and `configs.project`, the rule list above.
+ */
+const plugin = {
+  meta: { name: "project" },
+  rules: {
+    "no-disable-comments": noDisableCommentsRule,
+    "no-asset-imports": noAssetImportsRule,
+    "prefer-ascii": preferAsciiRule,
+    "no-duplicate-typeofs": noDuplicateTypeofsRule,
+    "no-empty-yield": noEmptyYieldRule,
+    "no-nan": noNanRule,
+    "no-unsafe-number": noUnsafeNumberRule,
+    "no-useless-continue": noUselessContinueRule,
+    "no-duplicate-interfaces": noDuplicateInterfacesRule,
+    "no-duplicate-types": noDuplicateTypesRule,
+    "no-modifier-private": noModifierPrivateRule,
+    "no-useless-type": noUselessTypeRule,
+  },
+  configs: { project: { rules } },
+};
+
+export default plugin;

scripts/protect-source.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+path=$(mktemp -d "${RUNNER_TEMP}/bot-agents-source-XXXXXX")
+cp -a "${ACTION_PATH}/src" "${path}/"
+# package.json makes Node load the TypeScript sources as ES modules and
+# resolves their `#` aliases.
+cp -a "${ACTION_PATH}/package.json" "${ACTION_PATH}/profiles.json" "${ACTION_PATH}/prompt.md" "${path}/"
+chmod -R go-w "${path}"
+printf 'path=%s\n' "${path}" >> "${GITHUB_OUTPUT}"

src/agents/auth.test.ts

@@ -0,0 +1,213 @@
+import {
+  mkdir,
+  readFile,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { expect, test } from "vite-plus/test";
+
+import { currentGid, currentUid, IS_WINDOWS, makeTempDir } from "#testing";
+
+import {
+  codexAuthentication,
+  isClaudeAuthFailure,
+  isCodexAuthFailure,
+  persistCodexAuth,
+  retryInvalidToken,
+  stageCodexAuth,
+} from "./auth.ts";
+
+test("retries once after an invalid refresh token", async () => {
+  let attempts = 0;
+  let relogins = 0;
+  const result = await retryInvalidToken(
+    async () => {
+      const resolved = await Promise.resolve({
+        code: 1,
+        error:
+          (attempts += 1) === 1
+            ? "ERROR: invalid_refresh_token"
+            : "still failed",
+      });
+      return resolved;
+    },
+    async () => {
+      relogins += 1;
+      await Promise.resolve();
+    },
+  );
+
+  expect({ attempts, relogins, error: result.error }).toStrictEqual({
+    attempts: 2,
+    relogins: 1,
+    error: "still failed",
+  });
+});
+
+test("does not retry an unrelated failure", async () => {
+  let attempts = 0;
+  let relogins = 0;
+  await retryInvalidToken(
+    async () => {
+      attempts += 1;
+      const resolved = await Promise.resolve({
+        code: 1,
+        error: "rate limited",
+      });
+      return resolved;
+    },
+    async () => {
+      relogins += 1;
+      await Promise.resolve();
+    },
+  );
+
+  expect({ attempts, relogins }).toStrictEqual({ attempts: 1, relogins: 0 });
+});
+
+// Verbatim stderr lines from the revoked-login job on lead/memona-home#36.
+const REVOKED_CODEX = [
+  `2026-10-12T02:28:04.702126Z ERROR codex_models_manager::manager: failed to refresh available models: unexpected status 401 Unauthorized: Encountered invalidated oauth token for user, failing request, url: https://chatgpt.com/backend-api/codex/models?client_version=0.162.1, cf-ray: a492ab48fdefea25-ICN, request id: req_4caa104fe9184a63bb8877f42817172d, auth error: 401, auth error code: token_revoked`,
+  `2026-10-12T02:28:05.082447Z ERROR codex_login::auth::manager: Failed to refresh token status=401 Unauthorized detail=TokenErrorDetail { error_code: Some("refresh_token_invalidated"), error_message: Some("Your session has ended. Please log in again."), .. }`,
+  `2026-10-12T02:28:05.451678Z ERROR rmcp::transport::worker: worker quit with fatal: Transport channel closed, when UnexpectedServerResponse("HTTP 401: {\\n  \\"error\\": {\\n    \\"message\\": \\"Encountered invalidated oauth token for user, failing request\\",\\n    \\"type\\": null,\\n    \\"code\\": \\"token_revoked\\",\\n    \\"param\\": null\\n  },\\n  \\"status\\": 401\\n}")`,
+  "ERROR: workspace routing discovery unauthorized (401)",
+];
+
+test("recognizes each Codex sign-in failure line", () => {
+  for (const line of [
+    ...REVOKED_CODEX,
+    `2026-10-12T02:28:05Z ERROR codex_login::auth::manager: Failed to refresh token status=401 Unauthorized detail=TokenErrorDetail { error_code: Some("refresh_token_expired"), .. }`,
+    `ERROR: Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again. (refresh_token_reused)`,
+    "ERROR: unexpected status 401 Unauthorized: Incorrect API key provided: sk-inval*d123., auth error: 401, auth error code: invalid_api_key",
+  ]) {
+    expect(isCodexAuthFailure(`exec\n${line}\n`), line).toBe(true);
+  }
+});
+
+test("ignores auth words outside Codex error lines", () => {
+  expect(
+    isCodexAuthFailure(
+      "exec\ncurl returned 401 Unauthorized\ntoken_revoked in fixture\nERROR: tests failed\n",
+    ),
+  ).toBe(false);
+});
+
+test("re-logs in after the job 9837 revoked-session stderr", async () => {
+  let relogins = 0;
+  let attempts = 0;
+  const result = await retryInvalidToken(
+    async () => {
+      const resolved = await Promise.resolve({
+        code: (attempts += 1) > 1 ? 0 : 1,
+        error: attempts === 1 ? REVOKED_CODEX.join("\n") : "",
+      });
+      return resolved;
+    },
+    async () => {
+      relogins += 1;
+      await Promise.resolve();
+    },
+  );
+
+  expect({ relogins, code: result.code }).toStrictEqual({
+    relogins: 1,
+    code: 0,
+  });
+});
+
+test("recognizes a rejected Claude OAuth token", () => {
+  expect(
+    isClaudeAuthFailure({
+      apiErrorStatus: 401,
+      result:
+        "Failed to authenticate. API Error: 401 OAuth access token is invalid.",
+    }),
+  ).toBe(true);
+  expect(
+    isClaudeAuthFailure({
+      result:
+        "OAuth token has expired. Please obtain a new token or refresh your existing token.",
+    }),
+  ).toBe(true);
+  expect(
+    isClaudeAuthFailure({ apiErrorStatus: 429, result: "API Error: 429" }),
+  ).toBe(false);
+});
+
+test("selects API-key login only for a configured Codex token", () => {
+  expect(codexAuthentication("selected-key")).toStrictEqual({
+    kind: "api-key",
+    token: "selected-key",
+  });
+  expect(codexAuthentication()).toStrictEqual({ kind: "persistent" });
+});
+
+const AUTH_TOKENS = {
+  access_token: "access",
+  refresh_token: "refresh",
+  id_token: "id",
+  account_id: "account",
+};
+const AUTH = JSON.stringify({ auth_mode: "chatgpt", tokens: AUTH_TOKENS });
+
+test.skipIf(IS_WINDOWS)(
+  "stages and persists only a regular private Codex login",
+  async () => {
+    const root = await makeTempDir();
+    try {
+      const canonical = `${root}/persistent/auth.json`;
+      await mkdir(`${root}/persistent`);
+      await writeFile(canonical, AUTH, { mode: 0o600 });
+      const home = `${root}/profile`;
+      await mkdir(home);
+
+      const staged = await stageCodexAuth(
+        canonical,
+        home,
+        currentUid(),
+        currentGid(),
+      );
+      expect(await readFile(staged, "utf8")).toStrictEqual(AUTH);
+      const stagedStat = await stat(staged);
+      expect(stagedStat.mode & 0o777).toBe(0o600);
+
+      const refreshed = JSON.stringify({
+        auth_mode: "chatgpt",
+        tokens: { ...AUTH_TOKENS, access_token: "refreshed" },
+      });
+      await writeFile(staged, refreshed);
+      await persistCodexAuth(staged, canonical);
+      expect(await readFile(canonical, "utf8")).toStrictEqual(refreshed);
+      const canonicalStat = await stat(canonical);
+      expect(canonicalStat.mode & 0o777).toBe(0o600);
+    } finally {
+      await rm(root, { recursive: true });
+    }
+  },
+);
+
+test.skipIf(IS_WINDOWS)(
+  "rejects a symlink or malformed Codex login",
+  async () => {
+    const root = await makeTempDir();
+    try {
+      const canonical = `${root}/auth.json`;
+      const malformed = `${root}/malformed.json`;
+      const linked = `${root}/linked.json`;
+      await writeFile(canonical, AUTH, { mode: 0o600 });
+      await writeFile(malformed, '{"tokens":{}}', { mode: 0o600 });
+      await symlink(canonical, linked);
+
+      await expect(persistCodexAuth(linked, canonical)).rejects.toThrow(
+        "regular file",
+      );
+      await expect(persistCodexAuth(malformed, canonical)).rejects.toThrow(
+        "invalid Codex login",
+      );
+    } finally {
+      await rm(root, { recursive: true });
+    }
+  },
+);

src/agents/auth.ts

@@ -0,0 +1,161 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmod,
+  chown,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import nodePath from "node:path";
+
+import { field, isNotFound, isObject } from "#common";
+
+interface CodexApiKey {
+  kind: "api-key";
+  token: string;
+}
+
+interface CodexPersistent {
+  kind: "persistent";
+}
+
+export type CodexAuthentication = CodexApiKey | CodexPersistent;
+
+export function codexAuthentication(token?: string): CodexAuthentication {
+  return token === undefined
+    ? { kind: "persistent" }
+    : { kind: "api-key", token };
+}
+
+// Codex logs revoked, expired, or reused ChatGPT sign-ins and rejected API keys
+// on its own ERROR lines; tool output and the echoed prompt must not count.
+const CODEX_AUTH_FAILURE =
+  /^(?:\S+\s+)?ERROR\b.*(?:\b401\b|unauthorized|invalid_refresh_token|refresh_token_(?:expired|reused|invalidated)|token_(?:revoked|expired)|invalid_api_key|(?:log|sign) in again)/imu;
+
+export function isCodexAuthFailure(error: string): boolean {
+  return CODEX_AUTH_FAILURE.test(error);
+}
+
+// Claude Code reports a rejected CLAUDE_CODE_OAUTH_TOKEN as an is_error
+// stream-json result, e.g. "Failed to authenticate. API Error: 401 OAuth
+// access token is invalid." with api_error_status 401.
+// The fields of Claude Code's stream-json `result` event that tell a sign-in
+// failure apart, as `apiErrorStatus` and `result`.
+export interface ClaudeFailureFields {
+  apiErrorStatus?: number;
+  result?: string;
+}
+
+export function isClaudeAuthFailure(result: ClaudeFailureFields): boolean {
+  return (
+    result.apiErrorStatus === 401 ||
+    /failed to authenticate|oauth (?:access )?token (?:is invalid|has expired)|invalid api key|authentication_error|please run \/login|not logged in/iu.test(
+      result.result ?? "",
+    )
+  );
+}
+
+export interface CommandResult {
+  code: number;
+  error: string;
+}
+
+export async function retryInvalidToken<T extends CommandResult>(
+  attempt: () => Promise<T>,
+  relogin: () => Promise<void>,
+): Promise<T> {
+  let result = await attempt();
+  if (result.code !== 0 && isCodexAuthFailure(result.error)) {
+    await relogin();
+    result = await attempt();
+  }
+  return result;
+}
+
+async function readCodexAuth(path: string): Promise<string> {
+  const stat = await lstat(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error("Codex login must be a regular file");
+  }
+  if ((stat.mode & 0o077) !== 0) {
+    throw new Error("Codex login must be private");
+  }
+  const text = await readFile(path, "utf8");
+  let value: unknown = null;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error("invalid Codex login");
+  }
+  const authMode = field(value, "auth_mode");
+  const tokens = field(value, "tokens");
+  if (
+    typeof authMode !== "string" ||
+    authMode === "" ||
+    !isObject(tokens) ||
+    !["access_token", "refresh_token", "id_token", "account_id"].every(
+      (name) => {
+        const token = field(tokens, name);
+        return typeof token === "string" && token !== "";
+      },
+    )
+  ) {
+    throw new Error("invalid Codex login");
+  }
+  return text;
+}
+
+export async function stageCodexAuth(
+  canonicalPath: string,
+  profileHome: string,
+  uid: number,
+  gid: number,
+): Promise<string> {
+  const codexHome = nodePath.join(profileHome, ".codex");
+  await mkdir(codexHome, { recursive: true, mode: 0o700 });
+  await chmod(codexHome, 0o700);
+  await chown(codexHome, uid, gid);
+  const stagedPath = nodePath.join(codexHome, "auth.json");
+  try {
+    await writeFile(stagedPath, await readCodexAuth(canonicalPath), {
+      mode: 0o600,
+    });
+    await chmod(stagedPath, 0o600);
+    await chown(stagedPath, uid, gid);
+  } catch (error) {
+    if (!isNotFound(error)) {
+      throw error;
+    }
+  }
+  return stagedPath;
+}
+
+// Creates an empty private file under a fresh name.
+async function makeTempFile(directory: string): Promise<string> {
+  const path = nodePath.join(directory, `.tmp-${randomUUID()}`);
+  const handle = await open(path, "wx", 0o600);
+  await handle.close();
+  return path;
+}
+
+export async function persistCodexAuth(
+  stagedPath: string,
+  canonicalPath: string,
+): Promise<void> {
+  const text = await readCodexAuth(stagedPath);
+  const directory = nodePath.dirname(canonicalPath);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const temporary = await makeTempFile(directory);
+  try {
+    await writeFile(temporary, text, { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, canonicalPath);
+  } catch (error) {
+    await rm(temporary).catch(() => {});
+    throw error;
+  }
+}

src/agents/index.ts

@@ -0,0 +1,21 @@
+// Agent command-line specifics: Codex and Claude Code sign-in handling and
+// OpenCode's arguments and output.
+export {
+  codexAuthentication,
+  isClaudeAuthFailure,
+  isCodexAuthFailure,
+  persistCodexAuth,
+  retryInvalidToken,
+  stageCodexAuth,
+} from "./auth.ts";
+export type {
+  ClaudeFailureFields,
+  CodexAuthentication,
+  CommandResult,
+} from "./auth.ts";
+export {
+  collectOpenCodeOutput,
+  openCodeArgs,
+  openCodeError,
+  parseOpenCodeEvents,
+} from "./opencode.ts";

src/agents/opencode.test.ts

@@ -0,0 +1,112 @@
+import { assert, expect, test } from "vite-plus/test";
+
+import { AgentAuthError } from "#profiles";
+
+import {
+  collectOpenCodeOutput,
+  openCodeArgs,
+  openCodeError,
+  parseOpenCodeEvents,
+} from "./opencode.ts";
+
+test("builds a non-interactive auto-approved OpenCode command", () => {
+  expect(
+    openCodeArgs("openrouter/qwen/qwen3.8-27b", "Review this"),
+  ).toStrictEqual([
+    "run",
+    "--format",
+    "json",
+    "--auto",
+    "--model",
+    "openrouter/qwen/qwen3.8-27b",
+    "Review this",
+  ]);
+});
+
+test("returns the final visible OpenCode text event", () => {
+  expect(
+    parseOpenCodeEvents(
+      [
+        JSON.stringify({ type: "step_start", part: { type: "step-start" } }),
+        JSON.stringify({ type: "text", part: { type: "text", text: "draft" } }),
+        JSON.stringify({ type: "text", part: { type: "text", text: "done" } }),
+        JSON.stringify({ type: "step_finish", part: { type: "step-finish" } }),
+      ].join("\n"),
+    ),
+  ).toBe("done");
+});
+
+test("rejects a successful OpenCode run without visible text", async () => {
+  await expect(async () => {
+    parseOpenCodeEvents('{"type":"step_start"}');
+    await Promise.resolve();
+  }).rejects.toThrow("no text output");
+});
+
+const encode = (value: string): Uint8Array => new TextEncoder().encode(value);
+
+test("streams OpenCode output while collecting it", async () => {
+  const stdout = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encode("first\n"));
+      controller.enqueue(encode("second\n"));
+      controller.close();
+    },
+  });
+  const stderr = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encode("warning\n"));
+      controller.close();
+    },
+  });
+  const shown: string[] = [];
+
+  const result = await collectOpenCodeOutput(
+    stdout,
+    stderr,
+    (chunk: Uint8Array) => {
+      shown.push(`out:${new TextDecoder().decode(chunk)}`);
+    },
+    (chunk: Uint8Array) => {
+      shown.push(`err:${new TextDecoder().decode(chunk)}`);
+    },
+  );
+
+  expect(result).toStrictEqual({
+    stdout: "first\nsecond\n",
+    stderr: "warning\n",
+  });
+  expect(shown).toStrictEqual(["out:first\n", "err:warning\n", "out:second\n"]);
+});
+
+const openRouterError = (statusCode: number, message: string): string =>
+  JSON.stringify({
+    type: "error",
+    sessionID: "ses_test",
+    error: {
+      name: "APIError",
+      data: {
+        message,
+        statusCode,
+        isRetryable: false,
+        responseBody: JSON.stringify({ error: { message, code: statusCode } }),
+      },
+    },
+  });
+
+test("reports a rejected OpenRouter key as a sign-in failure", () => {
+  const error = openCodeError(openRouterError(401, "User not found."));
+  assert.instanceOf(error, AgentAuthError);
+  expect(error.message).toBe("opencode sign-in failed");
+  assert.instanceOf(error.cause, Error);
+  expect(error.cause.message).toBe(
+    "opencode APIError (API error 401): User not found.",
+  );
+});
+
+test("surfaces an OpenCode error event instead of empty output", () => {
+  expect(() =>
+    parseOpenCodeEvents(openRouterError(429, "Rate limit exceeded")),
+  ).toThrow("API error 429");
+  expect(openCodeError('{"type":"text","part":{"text":"ok"}}')).toBeNull();
+});

src/agents/opencode.ts

@@ -0,0 +1,104 @@
+import { field, isObject } from "#common";
+import { AgentAuthError } from "#profiles";
+
+export function openCodeArgs(model: string, prompt: string): string[] {
+  return ["run", "--format", "json", "--auto", "--model", model, prompt];
+}
+
+type ChunkWriter = (chunk: Uint8Array) => void | Promise<void>;
+
+interface OpenCodeOutput {
+  stdout: string;
+  stderr: string;
+}
+
+export async function collectOpenCodeOutput(
+  stdout: AsyncIterable<Uint8Array>,
+  stderr: AsyncIterable<Uint8Array>,
+  writeStdout: ChunkWriter,
+  writeStderr: ChunkWriter,
+): Promise<OpenCodeOutput> {
+  const collect = async (
+    stream: AsyncIterable<Uint8Array>,
+    write: ChunkWriter,
+  ): Promise<string> => {
+    const chunks: Uint8Array[] = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+      await write(chunk);
+    }
+    const length = chunks.reduce((total, chunk) => total + chunk.length, 0);
+    const joined = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+      joined.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return new TextDecoder().decode(joined);
+  };
+  const [output, error] = await Promise.all([
+    collect(stdout, writeStdout),
+    collect(stderr, writeStderr),
+  ]);
+  return { stdout: output, stderr: error };
+}
+
+// OpenCode reports provider failures, including a rejected OpenRouter key
+// (401 "User not found."), as a JSON error event on stdout and exits 1 with an
+// empty stderr.
+export function openCodeError(output: string): Error | null {
+  let failure: Error | null = null;
+  for (const line of output.split("\n")) {
+    if (line.trim() === "") {
+      continue;
+    }
+    let event: unknown = null;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const error = field(event, "error");
+    if (field(event, "type") !== "error" || !isObject(error)) {
+      continue;
+    }
+    const name = field(error, "name");
+    const data = field(error, "data");
+    const message = field(data, "message");
+    const statusCode = field(data, "statusCode");
+    const detail = `opencode ${typeof name === "string" ? name : "error"}${
+      typeof statusCode === "number" ? ` (API error ${statusCode})` : ""
+    }: ${typeof message === "string" ? message : "unknown error"}`;
+    failure =
+      statusCode === 401 || statusCode === 403
+        ? new AgentAuthError("opencode sign-in failed", {
+            cause: new Error(detail),
+          })
+        : new Error(detail);
+  }
+  return failure;
+}
+
+export function parseOpenCodeEvents(output: string): string {
+  let result: string | null = null;
+  for (const line of output.split("\n")) {
+    if (line.trim() === "") {
+      continue;
+    }
+    const event: unknown = JSON.parse(line);
+    const part = field(event, "part");
+    if (field(event, "type") !== "text" || !isObject(part)) {
+      continue;
+    }
+    const text = field(part, "text");
+    if (typeof text === "string" && text.trim() !== "") {
+      result = text;
+    }
+  }
+  if (result === null) {
+    throw (
+      openCodeError(output) ?? new Error("OpenCode produced no text output")
+    );
+  }
+  return result;
+}

src/common/errors.ts

@@ -0,0 +1,7 @@
+// A missing file or a missing process: Node reports them as ENOENT and ESRCH.
+export function isNotFound(error: unknown): boolean {
+  if (!(error instanceof Error) || !("code" in error)) {
+    return false;
+  }
+  return error.code === "ENOENT" || error.code === "ESRCH";
+}

src/common/index.ts

@@ -0,0 +1,3 @@
+// Helpers every phase shares: error and JSON value checks.
+export { isNotFound } from "./errors.ts";
+export { field, isMapping, isObject } from "./json.ts";

src/common/json.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "vite-plus/test";
+
+import { field, isMapping, isObject } from "./json.ts";
+
+test("reads a named field of a parsed object", () => {
+  const value: unknown = JSON.parse(
+    '{"login":"bot","user":{"login":"nested"}}',
+  );
+  expect(field(value, "login")).toBe("bot");
+  expect(field(field(value, "user"), "login")).toBe("nested");
+  expect(field(value, "missing")).toBeUndefined();
+});
+
+test("reads no field of a value that is not an object", () => {
+  for (const value of [null, undefined, "text", 1, true]) {
+    expect(field(value, "login")).toBeUndefined();
+  }
+});
+
+test("counts arrays as objects but not as mappings", () => {
+  expect(isObject([])).toBe(true);
+  expect(isMapping([])).toBe(false);
+  expect(isMapping({})).toBe(true);
+  expect(field(["first"], "0")).toBe("first");
+});

src/common/json.ts

@@ -0,0 +1,19 @@
+// Checks and field reads for values parsed from JSON, which arrive as
+// `unknown`. Callers read the fields they know by name into their own
+// declared interfaces.
+
+// Any non-null object, arrays included.
+export function isObject(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+// A plain mapping, which an array is not.
+export function isMapping(value: unknown): value is object {
+  return isObject(value) && !Array.isArray(value);
+}
+
+// The named field of an object, or undefined for a missing field or a value
+// that is not an object.
+export function field(value: unknown, name: string): unknown {
+  return isObject(value) ? Reflect.get(value, name) : undefined;
+}

src/post/index.ts

@@ -0,0 +1,24 @@
+// The post phase: posts the agent's result as the reviewer and removes the
+// runtime credentials.
+import process from "node:process";
+
+import { postRuntime } from "./post.ts";
+
+export { type Fetcher, type PostContext, postRuntime } from "./post.ts";
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+}
+
+if (import.meta.main) {
+  await postRuntime(required("BOT_AGENTS_MANIFEST"), {
+    apiUrl: required("GITEA_API_URL"),
+    repository: required("GITEA_REPOSITORY"),
+    issueIndex: required("ISSUE_INDEX"),
+    eventName: required("EVENT_NAME"),
+  });
+}

src/post/post.test.ts

@@ -0,0 +1,333 @@
+import { chmod, mkdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { assert, expect, test } from "vite-plus/test";
+
+import { isNotFound } from "#common";
+import type { RuntimeFailure, RuntimeManifest, RuntimeOutcome } from "#runtime";
+import { currentGid, currentUid, IS_WINDOWS, makeTempDir } from "#testing";
+
+import { type Fetcher, type PostContext, postRuntime } from "./post.ts";
+
+const context: PostContext = {
+  apiUrl: "https://gitea.example/api/v1",
+  repository: "owner/repo",
+  issueIndex: "7",
+  eventName: "issue_comment",
+};
+
+interface Fixture {
+  manifestPath: string;
+  runtimeDir: string;
+  reviewerFile: string;
+  reviewPath: string;
+  outcomeFile: string;
+}
+
+interface FixtureSuccess {
+  ok: true;
+  body: string;
+}
+
+type FixtureSource = RuntimeFailure | FixtureSuccess;
+
+// One request the fake Gitea received.
+interface RecordedRequest {
+  url: string;
+  init: RequestInit;
+}
+
+async function writePrivate(path: string, text: string): Promise<void> {
+  await writeFile(path, text, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+async function writeArtifacts(
+  outcome: RuntimeOutcome,
+  review?: string,
+  anchors?: unknown,
+): Promise<void> {
+  if (!outcome.ok) {
+    return;
+  }
+  if (review !== undefined) {
+    await writePrivate(outcome.reviewPath, review);
+  }
+  if (anchors !== undefined) {
+    await writePrivate(outcome.anchorsPath, JSON.stringify(anchors));
+  }
+}
+
+function manifestFor(runtimeDir: string, profileHome: string): RuntimeManifest {
+  return {
+    runtimeDir,
+    manifestPath: `${runtimeDir}/manifest.json`,
+    reviewerFile: `${runtimeDir}/reviewer-token`,
+    outcomeFile: `${runtimeDir}/outcome.json`,
+    profiles: [
+      {
+        index: 0,
+        type: "CLAUDE",
+        model: "test",
+        uid: currentUid(),
+        gid: currentGid(),
+        home: profileHome,
+        tokenFile: null,
+      },
+    ],
+  };
+}
+
+async function fixture(
+  source: FixtureSource,
+  review?: string,
+  anchors?: unknown,
+): Promise<Fixture> {
+  const runtimeDir = await makeTempDir();
+  const profileHome = `${runtimeDir}/profile-0`;
+  const manifest = manifestFor(runtimeDir, profileHome);
+  await mkdir(profileHome);
+  await writeFile(manifest.reviewerFile, "reviewer-secret");
+  const outcome: RuntimeOutcome = source.ok
+    ? {
+        ...source,
+        profile: { type: "CODEX", model: "gpt-test" },
+        reviewPath: `${profileHome}/review.md`,
+        anchorsPath: `${profileHome}/anchors.json`,
+      }
+    : source;
+  await writeFile(manifest.outcomeFile, JSON.stringify(outcome));
+  await writeArtifacts(outcome, review, anchors);
+  await writeFile(manifest.manifestPath, JSON.stringify(manifest));
+  const { manifestPath, reviewerFile, outcomeFile } = manifest;
+  return {
+    manifestPath,
+    runtimeDir,
+    reviewerFile,
+    reviewPath: `${profileHome}/review.md`,
+    outcomeFile,
+  };
+}
+
+const missing = async (path: string): Promise<boolean> => {
+  try {
+    await stat(path);
+    return false;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return true;
+    }
+    throw error;
+  }
+};
+
+// The JSON body of one request the fake Gitea received.
+function requestBody(init?: RequestInit): unknown {
+  return typeof init?.body === "string" ? JSON.parse(init.body) : undefined;
+}
+
+// A fake Gitea that records each request body and answers with `status`.
+function recordingFetch(bodies: unknown[], status = 201): Fetcher {
+  return async (_url, init) => {
+    bodies.push(requestBody(init));
+    const resolved = await Promise.resolve(new Response(null, { status }));
+    return resolved;
+  };
+}
+
+test("posts a successful issue result and removes runtime credentials", async () => {
+  const result = await fixture({ ok: true, body: "done" });
+  const requests: RecordedRequest[] = [];
+
+  await postRuntime(result.manifestPath, context, async (url, init) => {
+    requests.push({ url, init });
+    const resolved = await Promise.resolve(new Response(null, { status: 201 }));
+    return resolved;
+  });
+
+  expect(requests.length).toBe(1);
+  const [request] = requests;
+  expect(request?.url).toStrictEqual(
+    `${context.apiUrl}/repos/owner/repo/issues/7/comments`,
+  );
+  expect(requestBody(request?.init)).toStrictEqual({
+    body: "done\n\n> Profile: `codex` · `gpt-test`",
+  });
+  expect(request?.init?.headers).toStrictEqual({
+    Authorization: "token reviewer-secret",
+    "Content-Type": "application/json",
+  });
+  assert(await missing(result.runtimeDir));
+});
+
+test("retries a rejected inline review without anchors", async () => {
+  const result = await fixture(
+    { ok: true, body: "ignored final response" },
+    "Approved\nReady",
+    [{ path: "run.ts", line: 1, side: "NEW", body: "Finding" }],
+  );
+  const bodies: unknown[] = [];
+
+  await postRuntime(
+    result.manifestPath,
+    {
+      ...context,
+      eventName: "pull_request",
+    },
+    async (_url, init) => {
+      bodies.push(requestBody(init));
+      const resolved = await Promise.resolve(
+        new Response(null, { status: bodies.length === 1 ? 422 : 200 }),
+      );
+      return resolved;
+    },
+  );
+
+  expect(bodies[0]).toMatchObject({
+    comments: [{ body: "Finding\n\n> Profile: `codex` · `gpt-test`" }],
+  });
+  expect(bodies[1]).toMatchObject({
+    comments: [],
+    body: "✅ Approved\nReady\n\n> Profile: `codex` · `gpt-test`",
+  });
+  assert(await missing(result.runtimeDir));
+});
+
+test("reports each tried profile and keeps the action failed", async () => {
+  const result = await fixture({
+    ok: false,
+    failures: [
+      { type: "CODEX", model: "gpt-test", reason: "SIGN_IN_FAILED" },
+      { type: "CLAUDE", model: "claude-test", reason: "USAGE_EXHAUSTED" },
+      { type: "OPENCODE", model: "openrouter/test", reason: "FAILED" },
+    ],
+  });
+  const bodies: unknown[] = [];
+
+  await expect(
+    postRuntime(result.manifestPath, context, recordingFetch(bodies)),
+  ).rejects.toThrow("agent phase failed");
+
+  expect(bodies).toStrictEqual([
+    {
+      body:
+        "AI bot failed.\n\n> Tried: `codex` · `gpt-test` (sign-in failed), " +
+        "`claude` · `claude-test` (usage exhausted), " +
+        "`opencode` · `openrouter/test` (failed)",
+    },
+  ]);
+  assert(!JSON.stringify(bodies).includes("reviewer-secret"));
+  assert(await missing(result.runtimeDir));
+});
+
+test("drops failure entries that are not known labels", async () => {
+  const result = await fixture({ ok: false, failures: [] });
+  await writeFile(
+    result.outcomeFile,
+    JSON.stringify({
+      ok: false,
+      failures: [
+        { type: "CODEX", model: "gpt-test", reason: "token sk-secret leaked" },
+        { type: "shell", model: "x", reason: "FAILED" },
+        { type: "CLAUDE", model: "claude-test", reason: "SIGN_IN_FAILED" },
+      ],
+    }),
+  );
+  const bodies: unknown[] = [];
+
+  await expect(
+    postRuntime(result.manifestPath, context, recordingFetch(bodies)),
+  ).rejects.toThrow("agent phase failed");
+
+  expect(bodies).toStrictEqual([
+    {
+      body: "AI bot failed.\n\n> Tried: `claude` · `claude-test` (sign-in failed)",
+    },
+  ]);
+});
+
+test("reports a generic failure when the runner wrote no outcome", async () => {
+  const result = await fixture({ ok: false, failures: [] });
+  await rm(result.outcomeFile);
+  const bodies: unknown[] = [];
+
+  await expect(
+    postRuntime(result.manifestPath, context, recordingFetch(bodies)),
+  ).rejects.toThrow("agent phase failed");
+
+  expect(bodies).toStrictEqual([{ body: "AI bot failed.\n\n> Profile: none" }]);
+  assert(await missing(result.runtimeDir));
+});
+
+test("removes runtime credentials when posting fails", async () => {
+  const result = await fixture({ ok: true, body: "done" });
+
+  await expect(
+    postRuntime(result.manifestPath, context, async () => {
+      const resolved = await Promise.resolve(
+        new Response("failed", { status: 500 }),
+      );
+      return resolved;
+    }),
+  ).rejects.toThrow("500");
+  assert(await missing(result.runtimeDir));
+});
+
+test("preserves a Gitea transport failure without retrying a comment", async () => {
+  const result = await fixture({ ok: true, body: "done" });
+  let requests = 0;
+
+  await expect(
+    postRuntime(result.manifestPath, context, async () => {
+      requests += 1;
+      await Promise.resolve();
+      throw new Error(`network failure ${requests}`);
+    }),
+  ).rejects.toThrow("network failure 1");
+
+  expect(requests).toBe(1);
+  assert(await missing(result.runtimeDir));
+});
+
+test.skipIf(IS_WINDOWS)(
+  "refuses to follow an agent artifact symlink",
+  async () => {
+    const result = await fixture({ ok: true, body: "done" });
+    await symlink(result.reviewerFile, result.reviewPath);
+    let requests = 0;
+
+    await expect(
+      postRuntime(result.manifestPath, context, async () => {
+        requests += 1;
+        const resolved = await Promise.resolve(
+          new Response(null, { status: 200 }),
+        );
+        return resolved;
+      }),
+    ).rejects.toThrow("regular private file");
+
+    expect(requests).toBe(1);
+    assert(await missing(result.runtimeDir));
+  },
+);
+
+test("reports an attributed failure when a pull request review is missing", async () => {
+  const result = await fixture({ ok: true, body: "done" });
+  const bodies: unknown[] = [];
+
+  await expect(
+    postRuntime(
+      result.manifestPath,
+      {
+        ...context,
+        eventName: "pull_request",
+      },
+      recordingFetch(bodies),
+    ),
+  ).rejects.toThrow("did not write");
+
+  expect(bodies).toStrictEqual([
+    {
+      body: "AI bot failed.\n\n> Tried: `codex` · `gpt-test` (failed)",
+    },
+  ]);
+  assert(await missing(result.runtimeDir));
+});

src/post/post.ts

@@ -0,0 +1,298 @@
+import type { Stats } from "node:fs";
+import { lstat, readFile, rm } from "node:fs/promises";
+import nodePath from "node:path";
+
+import { field, isNotFound, isObject } from "#common";
+import {
+  failureFooter,
+  type FailureReason,
+  type ProfileFailure,
+  withProfile,
+} from "#profiles";
+import {
+  readRuntimeManifest,
+  type RuntimeManifest,
+  type RuntimeOutcome,
+} from "#runtime";
+
+export interface PostContext {
+  apiUrl: string;
+  repository: string;
+  issueIndex: string;
+  eventName: string;
+}
+
+interface Anchor {
+  path: string;
+  line: number;
+  side: "NEW" | "OLD";
+  body: string;
+}
+
+const ANSI = new RegExp(`${String.fromCodePoint(27)}\\[[0-9;]*[A-Za-z]`, "gu");
+const stripAnsi = (text: string): string => text.replace(ANSI, "");
+const VERDICTS = new Map<string, [event: string, mark: string]>([
+  ["Approved", ["APPROVED", "✅"]],
+  ["Changes requested", ["REQUEST_CHANGES", "🛑"]],
+]);
+const PROFILE_TYPES = new Set<unknown>(["CLAUDE", "CODEX", "OPENCODE"]);
+const FAILURE_REASONS = new Set<unknown>([
+  "SIGN_IN_FAILED",
+  "USAGE_EXHAUSTED",
+  "FAILED",
+]);
+// Anchors written before the UPPER_SNAKE switch spell sides in lowercase.
+const OLD_SIDES = new Map<unknown, Anchor["side"]>([
+  ["new", "NEW"],
+  ["old", "OLD"],
+]);
+const isProfileType = (value: unknown): value is ProfileFailure["type"] =>
+  PROFILE_TYPES.has(value);
+const isFailureReason = (value: unknown): value is FailureReason =>
+  FAILURE_REASONS.has(value);
+const failureComment = (failures: ProfileFailure[]): string =>
+  `AI bot failed.\n\n${failureFooter(failures)}`;
+
+// The `fetch` subset the reviewer posts through, which tests replace.
+export type Fetcher = (url: string, init: RequestInit) => Promise<Response>;
+
+class GiteaRequestError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "GiteaRequestError";
+  }
+}
+
+function parseAnchors(text: string, sourcePath: string): Anchor[] {
+  const entries: unknown = JSON.parse(text);
+  if (!Array.isArray(entries)) {
+    throw new TypeError(`${sourcePath}: not an array`);
+  }
+  return entries.map((entry: unknown, index) => {
+    const at = `${sourcePath}[${index}]`;
+    if (!isObject(entry)) {
+      throw new TypeError(`${at}: not an object`);
+    }
+    const path = field(entry, "path");
+    const line = field(entry, "line");
+    const givenSide = field(entry, "side");
+    const side =
+      givenSide === undefined ? "NEW" : (OLD_SIDES.get(givenSide) ?? givenSide);
+    const body = field(entry, "body");
+    if (typeof path !== "string" || path === "") {
+      throw new TypeError(`${at}.path: expected a repository path`);
+    }
+    if (typeof line !== "number" || !Number.isInteger(line) || line < 1) {
+      throw new TypeError(`${at}.line: expected a line number`);
+    }
+    if (side !== "NEW" && side !== "OLD") {
+      throw new Error(`${at}.side: expected "NEW" or "OLD"`);
+    }
+    if (typeof body !== "string" || body.trim() === "") {
+      throw new TypeError(`${at}.body: expected the finding`);
+    }
+    return { path, line, side, body };
+  });
+}
+
+async function readOutcome(path: string): Promise<RuntimeOutcome> {
+  const value: unknown = JSON.parse(await readFile(path, "utf8"));
+  if (!isObject(value) || !("ok" in value)) {
+    throw new Error("invalid agent outcome");
+  }
+  const ok = field(value, "ok");
+  if (ok === false) {
+    // Only known labels reach the comment, never raw agent output.
+    const listed = field(value, "failures");
+    const failures: unknown[] = Array.isArray(listed) ? listed : [];
+    return {
+      ok: false,
+      failures: failures.flatMap((entry: unknown) => {
+        const type = field(entry, "type");
+        const model = field(entry, "model");
+        const reason = field(entry, "reason");
+        return isProfileType(type) &&
+          typeof model === "string" &&
+          isFailureReason(reason)
+          ? [{ type, model, reason }]
+          : [];
+      }),
+    };
+  }
+  const body = field(value, "body");
+  const reviewPath = field(value, "reviewPath");
+  const anchorsPath = field(value, "anchorsPath");
+  const profile = field(value, "profile");
+  if (
+    ok !== true ||
+    typeof body !== "string" ||
+    typeof reviewPath !== "string" ||
+    typeof anchorsPath !== "string" ||
+    !isObject(profile)
+  ) {
+    throw new Error("invalid agent outcome");
+  }
+  const type = field(profile, "type");
+  const model = field(profile, "model");
+  if (!isProfileType(type) || typeof model !== "string") {
+    throw new Error("invalid agent outcome");
+  }
+  return { ok: true, body, reviewPath, anchorsPath, profile: { type, model } };
+}
+
+async function readAgentArtifact(
+  manifest: RuntimeManifest,
+  path: string,
+  name: string,
+): Promise<string | null> {
+  const profile = manifest.profiles.find(
+    (entry) => nodePath.join(entry.home, name) === path,
+  );
+  if (profile === undefined) {
+    throw new Error(`${name}: outside profile home`);
+  }
+  let stat: Stats | null = null;
+  try {
+    stat = await lstat(path);
+  } catch (error) {
+    if (isNotFound(error)) {
+      return null;
+    }
+    throw error;
+  }
+  if (
+    !stat.isFile() ||
+    stat.isSymbolicLink() ||
+    stat.uid !== profile.uid ||
+    (stat.mode & 0o077) !== 0
+  ) {
+    throw new Error(`${name}: expected a profile-owned regular private file`);
+  }
+  const text = await readFile(path, "utf8");
+  return text === "" ? null : text;
+}
+
+export async function postRuntime(
+  manifestPath: string,
+  context: PostContext,
+  fetcher: Fetcher = fetch,
+): Promise<void> {
+  const manifest = await readRuntimeManifest(manifestPath);
+  try {
+    const reviewerText = await readFile(manifest.reviewerFile, "utf8");
+    const reviewerToken = reviewerText.trim();
+    const request = async (path: string, body: unknown): Promise<void> => {
+      let response: Response | null = null;
+      try {
+        response = await fetcher(`${context.apiUrl}/${path}`, {
+          method: "POST",
+          headers: {
+            Authorization: `token ${reviewerToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(body),
+        });
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new GiteaRequestError(`${path}: ${detail}`, { cause: error });
+      }
+      if (!response.ok) {
+        throw new GiteaRequestError(
+          `${path}: ${response.status} ${await response.text()}`,
+        );
+      }
+    };
+    const postComment = async (body: string): Promise<void> => {
+      await request(
+        `repos/${context.repository}/issues/${context.issueIndex}/comments`,
+        {
+          body: stripAnsi(body),
+        },
+      );
+    };
+
+    let outcome: RuntimeOutcome | null = null;
+    try {
+      outcome = await readOutcome(manifest.outcomeFile);
+    } catch (error) {
+      await postComment(failureComment([]));
+      throw new Error("agent phase failed", { cause: error });
+    }
+    if (!outcome.ok) {
+      await postComment(failureComment(outcome.failures));
+      throw new Error("agent phase failed");
+    }
+
+    try {
+      const review = await readAgentArtifact(
+        manifest,
+        outcome.reviewPath,
+        "review.md",
+      );
+      if (review === null) {
+        if (context.eventName === "pull_request") {
+          throw new Error("agent did not write a pull request review");
+        }
+        await postComment(withProfile(outcome.body, outcome.profile));
+        return;
+      }
+
+      const [verdict = "", ...rest] = review.split("\n");
+      const [event, mark] = VERDICTS.get(verdict.trim()) ?? ["COMMENT", "💬"];
+      const anchorText = await readAgentArtifact(
+        manifest,
+        outcome.anchorsPath,
+        "anchors.json",
+      );
+      const anchors =
+        anchorText === null
+          ? []
+          : parseAnchors(anchorText, outcome.anchorsPath);
+      const postReview = async (entries: Anchor[]): Promise<void> => {
+        await request(
+          `repos/${context.repository}/pulls/${context.issueIndex}/reviews`,
+          {
+            body: stripAnsi(
+              withProfile(
+                [`${mark} ${verdict.trim()}`, ...rest].join("\n"),
+                outcome.profile,
+              ),
+            ),
+            event,
+            comments: entries.map(({ path, line, side, body }) => ({
+              path,
+              body: stripAnsi(withProfile(body, outcome.profile)),
+              new_position: side === "NEW" ? line : 0,
+              old_position: side === "OLD" ? line : 0,
+            })),
+          },
+        );
+      };
+      await postReview(anchors).catch(async (error: unknown) => {
+        if (anchors.length === 0) {
+          throw error;
+        }
+        console.error(
+          `inline comments rejected: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        await postReview([]);
+      });
+    } catch (error) {
+      if (error instanceof GiteaRequestError) {
+        throw error;
+      }
+      await postComment(
+        failureComment([{ ...outcome.profile, reason: "FAILED" }]),
+      );
+      throw error;
+    }
+  } finally {
+    await rm(manifest.runtimeDir, { recursive: true }).catch(
+      (error: unknown) => {
+        if (!isNotFound(error)) {
+          throw error;
+        }
+      },
+    );
+  }
+}

src/prepare/index.ts

@@ -0,0 +1,24 @@
+import { appendFile, rm } from "node:fs/promises";
+import process from "node:process";
+
+import { prepareRuntime } from "#runtime";
+
+const env = (name: string): string => {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+};
+
+const manifest = await prepareRuntime(
+  env("ACTION_PATH"),
+  env("RUNNER_TEMP"),
+  env("BOT_AGENTS_MASTER_KEY"),
+);
+try {
+  await appendFile(env("GITHUB_OUTPUT"), `manifest=${manifest.manifestPath}\n`);
+} catch (error) {
+  await rm(manifest.runtimeDir, { recursive: true }).catch(() => {});
+  throw error;
+}

src/processes/child.test.ts

@@ -0,0 +1,41 @@
+import { spawn } from "node:child_process";
+import { expect, test } from "vite-plus/test";
+
+import { isNotFound } from "#common";
+
+import { exitCode } from "./child.ts";
+
+test("reports the exit code", async () => {
+  expect(
+    await exitCode(spawn("/bin/sh", ["-c", "exit 0"], { stdio: "ignore" })),
+  ).toBe(0);
+  expect(
+    await exitCode(spawn("/bin/sh", ["-c", "exit 3"], { stdio: "ignore" })),
+  ).toBe(3);
+});
+
+test("reports a signal as 128 plus its number", async () => {
+  const child = spawn("/bin/sh", ["-c", "kill -KILL $$"], { stdio: "ignore" });
+  expect(await exitCode(child)).toBe(137);
+});
+
+test("resolves on exit while a grandchild still holds the output open", async () => {
+  const child = spawn("/bin/sh", ["-c", "sleep 2 & exit 5"], {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const started = Date.now();
+  expect(await exitCode(child)).toBe(5);
+  expect(Date.now() - started).toBeLessThan(1500);
+  child.stdout.destroy();
+  child.stderr.destroy();
+});
+
+test("rejects when the command does not exist", async () => {
+  const child = spawn("/nonexistent/command", [], { stdio: "ignore" });
+  const code = exitCode(child);
+  // The rejection must stay unhandled-safe until it is awaited.
+  await new Promise((resolve) => {
+    setTimeout(resolve, 50);
+  });
+  await expect(code).rejects.toSatisfy(isNotFound);
+});

src/processes/child.ts

@@ -0,0 +1,33 @@
+// What the child process call sites share: the exit status, read right after
+// `spawn` so the exit event cannot pass unseen while the caller reads the
+// streams, and echoing output without outrunning a slow reader.
+import type { ChildProcess } from "node:child_process";
+import { once } from "node:events";
+import { constants } from "node:os";
+import type { Writable } from "node:stream";
+
+// Resolves once the process exits, before its streams close, with its exit
+// code, or with 128 plus the signal number if a signal killed it, as a shell
+// reports. A process that fails to start rejects with the spawn error.
+export function exitCode(child: ChildProcess): Promise<number> {
+  const code = new Promise<number>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (exit, signal) => {
+      resolve(exit ?? (signal === null ? 1 : 128 + constants.signals[signal]));
+    });
+  });
+  // Callers await it after draining the streams; a failed start must not be
+  // reported as an unhandled rejection before then.
+  code.catch(() => {});
+  return code;
+}
+
+// Writes a chunk, waiting for the stream to drain when its buffer is full.
+export async function echo(
+  stream: Writable,
+  chunk: string | Uint8Array,
+): Promise<void> {
+  if (!stream.write(chunk)) {
+    await once(stream, "drain");
+  }
+}

src/processes/index.ts

@@ -0,0 +1,4 @@
+// Child processes: waiting on and echoing them, and the isolated profile
+// user's processes and files.
+export { echo, exitCode } from "./child.ts";
+export { killProfileProcesses, readProfileFile } from "./isolation.ts";

src/processes/isolation.test.ts

@@ -0,0 +1,148 @@
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import {
+  chmod,
+  chown,
+  mkdir,
+  readFile,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import process from "node:process";
+import { expect, test } from "vite-plus/test";
+
+import { isNotFound } from "#common";
+import type { RuntimeProfile } from "#runtime";
+import { currentUid, IS_ROOT, IS_WINDOWS, makeTempDir } from "#testing";
+
+import {
+  isRunnableProfileProcess,
+  killProfileProcesses,
+  readProfileFile,
+} from "./isolation.ts";
+
+const profile = (uid: number, home: string): RuntimeProfile => ({
+  index: uid - 20_000,
+  type: "CLAUDE",
+  model: "test",
+  uid,
+  gid: uid,
+  home,
+  tokenFile: null,
+});
+
+// Runs a command as the profile's user from the root directory. Without `env`
+// it inherits this process's environment.
+function runAs(
+  selected: RuntimeProfile,
+  command: string,
+  args: string[],
+  env?: ReadonlyMap<string, string>,
+): SpawnSyncReturns<string> {
+  return spawnSync(command, args, {
+    cwd: "/",
+    uid: selected.uid,
+    gid: selected.gid,
+    encoding: "utf8",
+    ...(env !== undefined && { env: Object.fromEntries(env) }),
+  });
+}
+
+test("zombie process entries are already quiescent", () => {
+  const status = "State:\tZ (zombie)\nUid:\t20010\t20010\t20010\t20010\n";
+  expect(isRunnableProfileProcess(status, 20_010)).toBe(false);
+});
+
+test.skipIf(IS_WINDOWS)(
+  "refuses to read a profile result symlink as root",
+  async () => {
+    const root = await makeTempDir();
+    try {
+      const secret = `${root}/reviewer-token`;
+      const result = `${root}/result.md`;
+      await writeFile(secret, "reviewer-secret", { mode: 0o600 });
+      await symlink(secret, result);
+
+      await expect(
+        readProfileFile(profile(currentUid(), root), result),
+      ).rejects.toThrow("regular private file");
+    } finally {
+      await rm(root, { recursive: true });
+    }
+  },
+);
+
+test.skipIf(!IS_ROOT)(
+  "a profile process can read only its own private files",
+  async () => {
+    const root = await makeTempDir();
+    await chmod(root, 0o711);
+    try {
+      const homeA = `${root}/a`;
+      const homeB = `${root}/b`;
+      await mkdir(homeA, { mode: 0o700 });
+      await mkdir(homeB, { mode: 0o700 });
+      await chown(homeA, 20_000, 20_000);
+      await chown(homeB, 20_001, 20_001);
+      await writeFile(`${homeA}/token`, "own", { mode: 0o600 });
+      await chown(`${homeA}/token`, 20_000, 20_000);
+      await writeFile(`${homeB}/token`, "sibling", { mode: 0o600 });
+      await chown(`${homeB}/token`, 20_001, 20_001);
+      await writeFile(`${root}/reviewer`, "root", { mode: 0o600 });
+
+      const selected = profile(20_000, homeA);
+      const own = runAs(selected, "/bin/cat", [`${homeA}/token`]);
+      const sibling = runAs(selected, "/bin/cat", [`${homeB}/token`]);
+      const reviewer = runAs(selected, "/bin/cat", [`${root}/reviewer`]);
+
+      expect(own.stdout).toBe("own");
+      expect(own.status).toBe(0);
+      expect(sibling.status).not.toBe(0);
+      expect(reviewer.status).not.toBe(0);
+    } finally {
+      await rm(root, { recursive: true });
+    }
+  },
+);
+
+test.skipIf(!IS_ROOT)(
+  "cleanup leaves no runnable daemonized process",
+  async () => {
+    const selected = profile(20_010, "/tmp");
+    const launched = runAs(selected, "/bin/sh", [
+      "-c",
+      "sleep 60 >/dev/null 2>&1 & echo $!",
+    ]);
+    const pid = Number(launched.stdout.trim());
+    expect(Number.isInteger(pid)).toBe(true);
+
+    await killProfileProcesses(selected.uid);
+
+    const status = await readFile(`/proc/${pid}/status`, "utf8").catch(
+      (error: unknown) => {
+        if (isNotFound(error)) {
+          return null;
+        }
+        throw error;
+      },
+    );
+    expect(
+      status === null || !isRunnableProfileProcess(status, selected.uid),
+    ).toBe(true);
+  },
+);
+
+test.skipIf(!IS_ROOT)(
+  "the agent process cannot read its coordinator environment",
+  () => {
+    const selected = profile(20_020, "/tmp");
+    const result = runAs(
+      selected,
+      "/usr/bin/cat",
+      [`/proc/${process.pid}/environ`],
+      new Map([["PARENT_SECRET", "must-not-cross-boundary"]]),
+    );
+
+    expect(result.status).not.toBe(0);
+  },
+);

src/processes/isolation.ts

@@ -0,0 +1,78 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import process from "node:process";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { isNotFound } from "#common";
+import type { RuntimeProfile } from "#runtime";
+
+export function isRunnableProfileProcess(status: string, uid: number): boolean {
+  const owner = /^Uid:\s+(?<uid>\d+)/mu.exec(status)?.groups?.["uid"];
+  const state = /^State:\s+(?<state>\w)/mu.exec(status)?.groups?.["state"];
+  return owner !== undefined && Number(owner) === uid && state !== "Z";
+}
+
+async function profileProcessIds(uid: number): Promise<number[]> {
+  const entries = await readdir("/proc", { withFileTypes: true });
+  const pids = entries
+    .filter((entry) => entry.isDirectory() && /^\d+$/u.test(entry.name))
+    .map((entry) => entry.name);
+  const statuses = await Promise.all(
+    pids.map(async (pid) => {
+      const status = await readFile(`/proc/${pid}/status`, "utf8").catch(
+        () => null,
+      );
+      return status;
+    }),
+  );
+  return pids
+    .filter((_pid, index) => {
+      const status = statuses[index];
+      return (
+        status !== null &&
+        status !== undefined &&
+        isRunnableProfileProcess(status, uid)
+      );
+    })
+    .map(Number);
+}
+
+// Kills the UID's processes every 10 ms until none is left, for up to 100 rounds.
+export async function killProfileProcesses(
+  uid: number,
+  attempt = 0,
+): Promise<void> {
+  if (attempt === 100) {
+    throw new Error(`profile UID ${uid} still owns processes after cleanup`);
+  }
+  const ids = await profileProcessIds(uid);
+  if (ids.length === 0) {
+    return;
+  }
+  for (const pid of ids) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch (error) {
+      if (!isNotFound(error)) {
+        throw error;
+      }
+    }
+  }
+  await sleep(10);
+  await killProfileProcesses(uid, attempt + 1);
+}
+
+export async function readProfileFile(
+  profile: RuntimeProfile,
+  path: string,
+): Promise<string> {
+  const stat = await lstat(path);
+  if (
+    !stat.isFile() ||
+    stat.isSymbolicLink() ||
+    stat.uid !== profile.uid ||
+    (stat.mode & 0o077) !== 0
+  ) {
+    throw new Error(`${path}: expected a profile-owned regular private file`);
+  }
+  return readFile(path, "utf8");
+}

src/profiles/index.ts

@@ -0,0 +1,17 @@
+// Bot profiles: their footers, failure reports, ordered runs, and the
+// environment each agent gets.
+export {
+  AgentAuthError,
+  agentEnvironment,
+  failureFooter,
+  profileFooter,
+  runProfiles,
+  sanitizedEnvironment,
+  withProfile,
+} from "./profiles.ts";
+export type {
+  BotProfile,
+  FailureReason,
+  ProfileFailure,
+  ProfileIdentity,
+} from "./profiles.ts";

src/profiles/profiles.test.ts

@@ -0,0 +1,255 @@
+import { expect, test } from "vite-plus/test";
+
+import {
+  AgentAuthError,
+  agentEnvironment,
+  failureFooter,
+  type ProfileFailure,
+  profileFooter,
+  runProfiles,
+  sanitizedEnvironment,
+} from "./profiles.ts";
+
+test("formats profile attribution as a Markdown quote", () => {
+  expect(
+    profileFooter({ type: "OPENCODE", model: "openrouter/qwen/qwen3.8-27b" }),
+  ).toBe("> Profile: `opencode` · `openrouter/qwen/qwen3.8-27b`");
+});
+
+test("falls through only after usage exhaustion", async () => {
+  const visited: string[] = [];
+  const result = await runProfiles(
+    [
+      { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+      { type: "CODEX", model: "gpt-5.6-terra" },
+    ],
+    async (profile) => {
+      visited.push(profile.type);
+      if (profile.type === "CLAUDE") {
+        throw new Error("You've hit your usage limit");
+      }
+      const resolved = await Promise.resolve("done");
+      return resolved;
+    },
+  );
+
+  expect(result).toBe("done");
+  expect(visited).toStrictEqual(["CLAUDE", "CODEX"]);
+});
+
+test("recognizes Claude's weekly limit message", async () => {
+  const result = await runProfiles(
+    [
+      { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+      { type: "CODEX", model: "gpt-5.6-terra" },
+    ],
+    async (profile) => {
+      if (profile.type === "CLAUDE") {
+        throw new Error("You've hit your weekly limit · resets 12am (UTC)");
+      }
+      const resolved = await Promise.resolve("fallback");
+      return resolved;
+    },
+  );
+
+  expect(result).toBe("fallback");
+});
+
+test("recognizes provider API exhaustion status", async () => {
+  const results = await Promise.all(
+    ["API Error: 402 Insufficient funds", "HTTP error: 429"].map(
+      async (message) => {
+        const result = await runProfiles(
+          [
+            { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+            { type: "CODEX", model: "gpt-5.6-terra" },
+          ],
+          async (profile) => {
+            if (profile.type === "CLAUDE") {
+              throw new Error(message);
+            }
+            const resolved = await Promise.resolve("fallback");
+            return resolved;
+          },
+        );
+        return result;
+      },
+    ),
+  );
+
+  expect(results).toStrictEqual(["fallback", "fallback"]);
+});
+
+test("falls through after a sign-in failure and records each try", async () => {
+  const failures: ProfileFailure[] = [];
+  const result = await runProfiles(
+    [
+      { type: "CODEX", model: "gpt-5.6-terra" },
+      { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+      { type: "OPENCODE", model: "openrouter/qwen/qwen3.8-27b" },
+    ],
+    async (profile) => {
+      if (profile.type === "CODEX") {
+        throw new AgentAuthError("codex sign-in failed");
+      }
+      if (profile.type === "CLAUDE") {
+        throw new Error("API Error: 429");
+      }
+      const resolved = await Promise.resolve("fallback");
+      return resolved;
+    },
+    failures,
+  );
+
+  expect(result).toBe("fallback");
+  expect(failures).toStrictEqual([
+    { type: "CODEX", model: "gpt-5.6-terra", reason: "SIGN_IN_FAILED" },
+    { type: "CLAUDE", model: "claude-sonnet-5", reason: "USAGE_EXHAUSTED" },
+  ]);
+  expect(failureFooter(failures)).toStrictEqual(
+    "> Tried: `codex` · `gpt-5.6-terra` (sign-in failed), " +
+      "`claude` · `claude-sonnet-5` (usage exhausted)",
+  );
+});
+
+test("throws the last sign-in failure when every profile fails", async () => {
+  const failures: ProfileFailure[] = [];
+  await expect(
+    runProfiles(
+      [
+        { type: "CODEX", model: "gpt-5.6-terra" },
+        { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+      ],
+      (profile) => {
+        throw new AgentAuthError(`${profile.type} sign-in failed`);
+      },
+      failures,
+    ),
+  ).rejects.toThrow(
+    expect.toSatisfy(
+      (error: unknown) =>
+        error instanceof AgentAuthError &&
+        error.message.includes("CLAUDE sign-in failed"),
+    ),
+  );
+  expect(failures.map(({ reason }) => reason)).toStrictEqual([
+    "SIGN_IN_FAILED",
+    "SIGN_IN_FAILED",
+  ]);
+});
+
+test("preserves an ordinary agent failure", async () => {
+  const visited: string[] = [];
+  await expect(
+    runProfiles(
+      [
+        { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+        { type: "CODEX", model: "gpt-5.6-terra" },
+      ],
+      (profile) => {
+        visited.push(profile.type);
+        throw new Error("tests failed");
+      },
+    ),
+  ).rejects.toThrow("tests failed");
+  expect(visited).toStrictEqual(["CLAUDE"]);
+});
+
+test("does not mistake incidental quota text for exhaustion", async () => {
+  const visited: string[] = [];
+  await expect(
+    runProfiles(
+      [
+        { type: "CLAUDE", model: "claude-sonnet-5", token: "first" },
+        { type: "CODEX", model: "gpt-5.6-terra" },
+      ],
+      (profile) => {
+        visited.push(profile.type);
+        throw new Error("quota parser test failed at line 429");
+      },
+    ),
+  ).rejects.toThrow("quota parser test failed");
+  expect(visited).toStrictEqual(["CLAUDE"]);
+});
+
+test("exposes only the selected profile credential to the agent", () => {
+  const base = new Map([
+    ["PATH", "/usr/bin"],
+    ["HOME", "/home/bot"],
+    ["UNRELATED_SECRET", "must-not-reach-agent"],
+    ["BOT_AGENTS_MASTER_KEY", "master"],
+    ["PROFILES", "contains every secret"],
+    ["REVIEWER_TOKEN", "reviewer"],
+    ["CLAUDE_CODE_OAUTH_TOKEN", "old-claude"],
+    ["ANTHROPIC_API_KEY", "old-anthropic-key"],
+    ["ANTHROPIC_AUTH_TOKEN", "old-anthropic-token"],
+    ["OPENAI_API_KEY", "old-openai"],
+    ["CODEX_API_KEY", "old-codex-key"],
+    ["CODEX_ACCESS_TOKEN", "old-codex-token"],
+  ]);
+  const profile = {
+    index: 0,
+    type: "CLAUDE" as const,
+    model: "claude-sonnet-5",
+    uid: 20_000,
+    gid: 20_000,
+    home: "/runtime/profile-0",
+    tokenFile: "/runtime/profile-0/token",
+  };
+
+  expect(agentEnvironment(base, profile, "selected")).toStrictEqual(
+    new Map([
+      ["PATH", "/usr/bin"],
+      ["HOME", "/runtime/profile-0"],
+      ["CLAUDE_CODE_OAUTH_TOKEN", "selected"],
+    ]),
+  );
+  expect(sanitizedEnvironment(base)).toStrictEqual(
+    new Map([
+      ["PATH", "/usr/bin"],
+      ["HOME", "/home/bot"],
+    ]),
+  );
+});
+
+test("uses a private Codex home without inventing an API credential", () => {
+  const profile = {
+    index: 1,
+    type: "CODEX" as const,
+    model: "gpt-5.6-terra",
+    uid: 20_001,
+    gid: 20_001,
+    home: "/runtime/profile-1",
+    tokenFile: null,
+  };
+
+  expect(agentEnvironment(new Map([["PATH", "/bin"]]), profile)).toStrictEqual(
+    new Map([
+      ["PATH", "/bin"],
+      ["HOME", "/runtime/profile-1"],
+      ["CODEX_HOME", "/runtime/profile-1/.codex"],
+    ]),
+  );
+});
+
+test("exposes an OpenRouter key only to the OpenCode profile", () => {
+  const profile = {
+    index: 2,
+    type: "OPENCODE" as const,
+    model: "openrouter/qwen/qwen3.8-27b",
+    uid: 20_002,
+    gid: 20_002,
+    home: "/runtime/profile-2",
+    tokenFile: "/runtime/profile-2/token",
+  };
+
+  expect(
+    agentEnvironment(new Map([["PATH", "/bin"]]), profile, "selected"),
+  ).toStrictEqual(
+    new Map([
+      ["PATH", "/bin"],
+      ["HOME", "/runtime/profile-2"],
+      ["OPENROUTER_API_KEY", "selected"],
+    ]),
+  );
+});

src/profiles/profiles.ts

@@ -0,0 +1,179 @@
+// The agent and model a profile runs, which every report names.
+export interface ProfileIdentity {
+  type: "CLAUDE" | "CODEX" | "OPENCODE";
+  model: string;
+}
+
+export interface BotProfile extends ProfileIdentity {
+  token?: string;
+}
+
+// The lowercase name a profile type reads as in posted comments.
+function profileName(type: ProfileIdentity["type"]): string {
+  switch (type) {
+    case "CLAUDE":
+      return "claude";
+    case "CODEX":
+      return "codex";
+    case "OPENCODE":
+      return "opencode";
+  }
+}
+
+export function profileFooter(profile: ProfileIdentity): string {
+  return `> Profile: \`${profileName(profile.type)}\` · \`${profile.model}\``;
+}
+
+export function withProfile(body: string, profile: ProfileIdentity): string {
+  return `${body}\n\n${profileFooter(profile)}`;
+}
+
+export type FailureReason = "SIGN_IN_FAILED" | "USAGE_EXHAUSTED" | "FAILED";
+
+// The words a failure reason reads as in logs and posted comments.
+function toMessage(reason: FailureReason): string {
+  switch (reason) {
+    case "SIGN_IN_FAILED":
+      return "sign-in failed";
+    case "USAGE_EXHAUSTED":
+      return "usage exhausted";
+    case "FAILED":
+      return "failed";
+  }
+}
+
+export interface ProfileFailure extends ProfileIdentity {
+  reason: FailureReason;
+}
+
+// Where a profile's isolated user keeps its home.
+interface ProfileHome {
+  type: ProfileIdentity["type"];
+  home: string;
+}
+
+// Raised once an agent's credentials are rejected and any re-login is spent.
+export class AgentAuthError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "AgentAuthError";
+  }
+}
+
+function isUsageExhausted(error: unknown): boolean {
+  return /(?:usage|rate) limit|hit your (?:weekly )?limit|insufficient_quota|exceeded your current quota|too many requests|(?:api error|http error|http|status(?: code)?)[ :]+4(?:02|29)\b/iu.test(
+    String(error),
+  );
+}
+
+function failureReason(error: unknown): FailureReason {
+  if (error instanceof AgentAuthError) {
+    return "SIGN_IN_FAILED";
+  }
+  return isUsageExhausted(error) ? "USAGE_EXHAUSTED" : "FAILED";
+}
+
+export function failureFooter(failures: ProfileFailure[]): string {
+  if (failures.length === 0) {
+    return "> Profile: none";
+  }
+  return `> Tried: ${failures
+    .map(
+      ({ type, model, reason }) =>
+        `\`${profileName(type)}\` · \`${model}\` (${toMessage(reason)})`,
+    )
+    .join(", ")}`;
+}
+
+// Tries the profiles in order, moving on only after a sign-in failure or
+// exhausted usage, and records every profile it tried.
+export async function runProfiles<T, P extends ProfileIdentity>(
+  profiles: P[],
+  attempt: (profile: P) => Promise<T>,
+  failures: ProfileFailure[] = [],
+): Promise<T> {
+  for (const [index, profile] of profiles.entries()) {
+    try {
+      return await attempt(profile);
+    } catch (error) {
+      const reason = failureReason(error);
+      failures.push({ type: profile.type, model: profile.model, reason });
+      if (reason === "FAILED" || index === profiles.length - 1) {
+        throw error;
+      }
+      console.error(
+        `${profile.type} ${toMessage(reason)}; trying next profile`,
+      );
+    }
+  }
+  throw new Error("profiles must contain at least one profile");
+}
+
+// Environments are maps from variable name to value, converted to the object
+// form only where a child process is spawned.
+export function sanitizedEnvironment(
+  environment: ReadonlyMap<string, string>,
+): Map<string, string> {
+  const result = new Map<string, string>();
+  for (const name of [
+    "PATH",
+    "HOME",
+    "LANG",
+    "LANGUAGE",
+    "LC_ALL",
+    "TERM",
+    "COLORTERM",
+    "CI",
+    "TMPDIR",
+    "GITEA_TOKEN",
+    "GITEA_API_URL",
+    "GITEA_REPOSITORY",
+    "GITHUB_WORKSPACE",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+    "no_proxy",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "NODE_EXTRA_CA_CERTS",
+  ]) {
+    const value = environment.get(name);
+    if (value !== undefined) {
+      result.set(name, value);
+    }
+  }
+  return result;
+}
+
+// The environment variable each agent CLI reads its credential from.
+function tokenVariable(type: ProfileIdentity["type"]): string {
+  switch (type) {
+    case "CLAUDE":
+      return "CLAUDE_CODE_OAUTH_TOKEN";
+    case "CODEX":
+      return "OPENAI_API_KEY";
+    case "OPENCODE":
+      return "OPENROUTER_API_KEY";
+  }
+}
+
+export function agentEnvironment(
+  environment: ReadonlyMap<string, string>,
+  profile: ProfileHome,
+  token?: string,
+): Map<string, string> {
+  const result = sanitizedEnvironment(environment);
+  result.set("HOME", profile.home);
+  if (profile.type === "CODEX") {
+    result.set("CODEX_HOME", `${profile.home}/.codex`);
+  }
+  if (token !== undefined && token !== "") {
+    const tokenName = tokenVariable(profile.type);
+    result.set(tokenName, token);
+  }
+  return result;
+}

src/run/index.ts

@@ -0,0 +1,593 @@
+// Runs one ordered agent profile. Credential decryption and reviewer posting
+// live in separate processes so neither privileged secret reaches this runner.
+import { spawn } from "node:child_process";
+import { chmod, chown, readFile, writeFile } from "node:fs/promises";
+import process from "node:process";
+import { createInterface } from "node:readline";
+import type { Readable } from "node:stream";
+import { text as readText } from "node:stream/consumers";
+import { finished } from "node:stream/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import {
+  type ClaudeFailureFields,
+  type CodexAuthentication,
+  codexAuthentication,
+  collectOpenCodeOutput,
+  type CommandResult,
+  isClaudeAuthFailure,
+  isCodexAuthFailure,
+  openCodeArgs,
+  openCodeError,
+  parseOpenCodeEvents,
+  persistCodexAuth,
+  retryInvalidToken,
+  stageCodexAuth,
+} from "#agents";
+import { field, isObject } from "#common";
+import {
+  echo,
+  exitCode,
+  killProfileProcesses,
+  readProfileFile,
+} from "#processes";
+import {
+  AgentAuthError,
+  agentEnvironment,
+  type ProfileFailure,
+  type ProfileIdentity,
+  runProfiles,
+  sanitizedEnvironment,
+  withProfile,
+} from "#profiles";
+import {
+  readRuntimeManifest,
+  type RuntimeOutcome,
+  type RuntimeProfile,
+} from "#runtime";
+
+interface AttemptResult {
+  body: string;
+  reviewPath: string;
+  anchorsPath: string;
+  profile: ProfileIdentity;
+}
+
+// Claude Code's stream-json `result` event, with camelCase field names.
+interface ClaudeResult extends ClaudeFailureFields {
+  isError?: boolean;
+  subtype: string;
+}
+
+interface RenderedPrompt {
+  prompt: string;
+  reviewPath: string;
+  anchorsPath: string;
+}
+
+const env = (name: string): string => {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+};
+
+function definedEnvironment(): Map<string, string> {
+  const result = new Map<string, string>();
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      result.set(name, value);
+    }
+  }
+  return result;
+}
+
+const API = env("GITEA_API_URL");
+const REPO = env("GITEA_REPOSITORY");
+const INDEX = env("ISSUE_INDEX");
+const EVENT = env("EVENT_NAME");
+const AUTHOR_TOKEN = env("GITEA_TOKEN");
+const WORKSPACE = env("GITHUB_WORKSPACE");
+const MANIFEST = await readRuntimeManifest(env("BOT_AGENTS_MANIFEST"));
+const PROCESS_ENV = sanitizedEnvironment(definedEnvironment());
+const RULES_PATH = "repos/commons/code-rules/raw/README.md";
+const CODEX_AUTH = "/root/.codex/auth.json";
+const SKILLS_INSTALL = "skills add obra/superpowers";
+
+async function gitea(path: string, body?: unknown): Promise<Response> {
+  const response = await fetch(`${API}/${path}`, {
+    method: body === undefined ? "GET" : "POST",
+    headers: {
+      Authorization: `token ${AUTHOR_TOKEN}`,
+      "Content-Type": "application/json",
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!response.ok) {
+    throw new Error(`${path}: ${response.status} ${await response.text()}`);
+  }
+  return response;
+}
+
+async function postAuthorComment(body: string): Promise<void> {
+  await gitea(`repos/${REPO}/issues/${INDEX}/comments`, { body });
+}
+
+async function runRoot(command: string, args: string[]): Promise<void> {
+  const code = await exitCode(
+    spawn(command, args, {
+      env: Object.fromEntries(PROCESS_ENV),
+      stdio: "ignore",
+    }),
+  );
+  if (code !== 0) {
+    throw new Error(`${command} ${args[0]} exited with ${code}`);
+  }
+}
+
+async function configureGitAuthor(): Promise<void> {
+  const userResponse = await gitea("user");
+  const user: unknown = await userResponse.json();
+  const login = field(user, "login");
+  const email = field(user, "email");
+  if (typeof login !== "string" || typeof email !== "string") {
+    throw new TypeError("user: unexpected Gitea response");
+  }
+  await runRoot("git", ["config", "user.name", login]);
+  await runRoot("git", ["config", "user.email", email]);
+}
+
+async function readProfileToken(
+  profile: RuntimeProfile,
+): Promise<string | null> {
+  const token =
+    profile.tokenFile === null
+      ? null
+      : await readFile(profile.tokenFile, "utf8");
+  return token;
+}
+
+async function runAgentCommand(
+  profile: RuntimeProfile,
+  command: string,
+  args: string[],
+  token?: string,
+): Promise<void> {
+  const child = spawn(command, args, {
+    cwd: WORKSPACE,
+    env: Object.fromEntries(agentEnvironment(PROCESS_ENV, profile, token)),
+    uid: profile.uid,
+    gid: profile.gid,
+    stdio: "ignore",
+  });
+  const code = await exitCode(child);
+  if (code !== 0) {
+    throw new Error(`${command} ${args[0]} exited with ${code}`);
+  }
+}
+
+// The agent name the skills installer knows each profile type by.
+function skillsAgent(type: RuntimeProfile["type"]): string {
+  switch (type) {
+    case "CLAUDE":
+      return "claude-code";
+    case "CODEX":
+      return "codex";
+    case "OPENCODE":
+      return "opencode";
+  }
+}
+
+async function prepareProfile(profile: RuntimeProfile): Promise<void> {
+  await runAgentCommand(profile, "git", [
+    "config",
+    "--global",
+    "--add",
+    "safe.directory",
+    WORKSPACE,
+  ]);
+  await runAgentCommand(profile, "npx", [
+    "-y",
+    ...SKILLS_INSTALL.split(" "),
+    "--global",
+    "--agent",
+    skillsAgent(profile.type),
+    "--yes",
+  ]);
+}
+
+// One issue comment as the prompt quotes it.
+function formatComment(comment: unknown): string {
+  const login = field(field(comment, "user"), "login");
+  const createdAt = field(comment, "created_at");
+  const body = field(comment, "body");
+  return `## ${String(login)} at ${String(createdAt)}\n\n${String(body)}\n`;
+}
+
+async function renderPrompt(profile: RuntimeProfile): Promise<RenderedPrompt> {
+  const reviewPath = await makeProfileFile(profile, "review.md");
+  const anchorsPath = await makeProfileFile(profile, "anchors.json");
+  const commentsResponse = await gitea(
+    `repos/${REPO}/issues/${INDEX}/comments?limit=100`,
+  );
+  const comments: unknown = await commentsResponse.json();
+  if (!Array.isArray(comments)) {
+    throw new TypeError("comments: unexpected Gitea response");
+  }
+  const rulesResponse = await gitea(RULES_PATH);
+  const codeRules = await rulesResponse.text();
+  const values = new Map<string, string>([
+    ["COMMENT", env("COMMENT")],
+    [
+      "ISSUE_COMMENTS",
+      comments.map((comment: unknown) => formatComment(comment)).join("\n"),
+    ],
+    ["CODE_RULES", codeRules],
+    ["EVENT_NAME", EVENT],
+    ["GITEA_API_URL", API],
+    ["GITEA_REPOSITORY", REPO],
+    ["ISSUE_INDEX", INDEX],
+    ["REVIEW_PATH", reviewPath],
+    ["ANCHORS_PATH", anchorsPath],
+  ]);
+  const template = await readFile(
+    new URL("../../prompt.md", import.meta.url),
+    "utf8",
+  );
+  return {
+    prompt: template.replaceAll(
+      /\$\{(?<name>\w+)\}/gu,
+      (match: string, ...args: unknown[]) => {
+        const groups = args.at(-1);
+        const name = isObject(groups) ? field(groups, "name") : undefined;
+        return typeof name === "string" ? (values.get(name) ?? match) : match;
+      },
+    ),
+    reviewPath,
+    anchorsPath,
+  };
+}
+
+async function runClaude(
+  profile: RuntimeProfile,
+  token: string,
+  prompt: string,
+): Promise<string> {
+  const claude = spawn(
+    "claude",
+    [
+      "--print",
+      "--dangerously-skip-permissions",
+      "--model",
+      profile.model,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      prompt,
+    ],
+    {
+      cwd: WORKSPACE,
+      env: Object.fromEntries(
+        agentEnvironment(PROCESS_ENV, profile, token).set("IS_SANDBOX", "1"),
+      ),
+      uid: profile.uid,
+      gid: profile.gid,
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  );
+  const status = exitCode(claude);
+  let result: ClaudeResult | null = null;
+  let error = "";
+  const copyError = (async (): Promise<void> => {
+    claude.stderr.setEncoding("utf8");
+    for await (const chunk of claude.stderr) {
+      const part = String(chunk);
+      error += part;
+      console.error(part);
+    }
+  })();
+  for await (const line of createInterface({
+    input: claude.stdout,
+    crlfDelay: Infinity,
+  })) {
+    if (line !== "") {
+      const event: unknown = JSON.parse(line);
+      if (isObject(event)) {
+        const content = field(field(event, "message"), "content");
+        for (const part of Array.isArray(content) ? content : []) {
+          if (isObject(part)) {
+            const text =
+              field(part, "thinking") ??
+              field(part, "text") ??
+              field(part, "name");
+            if (typeof text === "string" && text !== "") {
+              console.log(text);
+            }
+          }
+        }
+        if (field(event, "type") === "result") {
+          const isError = field(event, "is_error");
+          const answer = field(event, "result");
+          const subtype = field(event, "subtype");
+          const apiStatus = field(event, "api_error_status");
+          result = {
+            isError: typeof isError === "boolean" ? isError : undefined,
+            result: typeof answer === "string" ? answer : undefined,
+            subtype: String(subtype),
+            apiErrorStatus:
+              typeof apiStatus === "number" ? apiStatus : undefined,
+          };
+        }
+      }
+    }
+  }
+  const [code] = await Promise.all([status, copyError]);
+  if (result?.isError === true) {
+    const failure = new Error(
+      result.result ?? `claude ended with ${result.subtype}`,
+    );
+    if (isClaudeAuthFailure(result)) {
+      throw new AgentAuthError("claude sign-in failed", { cause: failure });
+    }
+    throw failure;
+  }
+  if (result?.result === undefined) {
+    throw new Error(
+      error.trim() || `claude ended with ${result?.subtype ?? "no result"}`,
+    );
+  }
+  if (code !== 0) {
+    throw new Error(error.trim() || `claude exited with ${code}`);
+  }
+  return result.result;
+}
+
+async function codexDeviceLogin(
+  profile: RuntimeProfile,
+  environment: ReadonlyMap<string, string>,
+): Promise<void> {
+  const login = spawn("codex", ["login", "--device-auth"], {
+    cwd: WORKSPACE,
+    env: Object.fromEntries(environment),
+    uid: profile.uid,
+    gid: profile.gid,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const status = exitCode(login);
+  let shown = "";
+  const collect = async (stream: Readable): Promise<void> => {
+    stream.setEncoding("utf8");
+    for await (const chunk of stream) {
+      shown += String(chunk);
+    }
+  };
+  const drained = Promise.all([collect(login.stdout), collect(login.stderr)]);
+  await sleep(3000);
+  while (shown.trim() === "") {
+    const exited = await Promise.race([
+      status.then(() => true),
+      sleep(100, false),
+    ]);
+    if (exited) {
+      throw new AgentAuthError("AI bot login produced no instructions");
+    }
+  }
+  await postAuthorComment(withProfile(shown, profile));
+  const [code] = await Promise.all([status, drained]);
+  if (code !== 0) {
+    throw new AgentAuthError(`codex login exited with ${code}`);
+  }
+}
+
+async function codexApiLogin(
+  profile: RuntimeProfile,
+  environment: ReadonlyMap<string, string>,
+  token: string,
+): Promise<void> {
+  const login = spawn("codex", ["login", "--with-api-key"], {
+    cwd: WORKSPACE,
+    env: Object.fromEntries(environment),
+    uid: profile.uid,
+    gid: profile.gid,
+    stdio: ["pipe", "inherit", "pipe"],
+  });
+  const status = exitCode(login);
+  login.stdin.end(`${token}\n`);
+  await finished(login.stdin);
+  const [code, error] = await Promise.all([status, readText(login.stderr)]);
+  if (code !== 0) {
+    throw new Error(error.trim() || `codex login exited with ${code}`);
+  }
+}
+
+async function makeProfileFile(
+  profile: RuntimeProfile,
+  name: string,
+): Promise<string> {
+  const path = `${profile.home}/${name}`;
+  await writeFile(path, "", { mode: 0o600 });
+  await chmod(path, 0o600);
+  await chown(path, profile.uid, profile.gid);
+  return path;
+}
+
+async function runCodex(
+  profile: RuntimeProfile,
+  prompt: string,
+  authentication: CodexAuthentication,
+): Promise<string> {
+  const token =
+    authentication.kind === "api-key" ? authentication.token : undefined;
+  const environment = agentEnvironment(PROCESS_ENV, profile, token);
+  if (authentication.kind === "api-key") {
+    await codexApiLogin(profile, environment, authentication.token);
+  } else {
+    const check = spawn("codex", ["login", "status"], {
+      cwd: WORKSPACE,
+      env: Object.fromEntries(environment),
+      uid: profile.uid,
+      gid: profile.gid,
+      stdio: "ignore",
+    });
+    if ((await exitCode(check)) !== 0) {
+      await codexDeviceLogin(profile, environment);
+    }
+  }
+  const outputPath = await makeProfileFile(profile, "result.md");
+  const attempt = async (): Promise<CommandResult> => {
+    const codex = spawn(
+      "codex",
+      [
+        "exec",
+        "--model",
+        profile.model,
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--output-last-message",
+        outputPath,
+        prompt,
+      ],
+      {
+        cwd: WORKSPACE,
+        env: Object.fromEntries(environment),
+        uid: profile.uid,
+        gid: profile.gid,
+        stdio: ["ignore", "inherit", "pipe"],
+      },
+    );
+    const status = exitCode(codex);
+    codex.stderr.setEncoding("utf8");
+    let error = "";
+    for await (const chunk of codex.stderr) {
+      const part = String(chunk);
+      await echo(process.stderr, part);
+      error += part;
+    }
+    // Codex echoes the prompt, whose comments may quote auth errors.
+    return { code: await status, error: error.replaceAll(prompt, "") };
+  };
+  const result =
+    authentication.kind === "api-key"
+      ? await attempt()
+      : await retryInvalidToken(attempt, async () => {
+          await runAgentCommand(profile, "codex", ["logout"]);
+          await codexDeviceLogin(profile, environment);
+        });
+  if (result.code !== 0) {
+    const failure = new Error(
+      result.error.trim() || `codex exited with ${result.code}`,
+    );
+    if (isCodexAuthFailure(result.error)) {
+      throw new AgentAuthError("codex sign-in failed", { cause: failure });
+    }
+    throw failure;
+  }
+  return outputPath;
+}
+
+async function runOpenCode(
+  profile: RuntimeProfile,
+  token: string,
+  prompt: string,
+): Promise<string> {
+  const child = spawn("opencode", openCodeArgs(profile.model, prompt), {
+    cwd: WORKSPACE,
+    env: Object.fromEntries(agentEnvironment(PROCESS_ENV, profile, token)),
+    uid: profile.uid,
+    gid: profile.gid,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const status = exitCode(child);
+  const collected = collectOpenCodeOutput(
+    child.stdout,
+    child.stderr,
+    async (chunk) => {
+      await echo(process.stdout, chunk);
+    },
+    async (chunk) => {
+      await echo(process.stderr, chunk);
+    },
+  );
+  const [code, streams] = await Promise.all([status, collected]);
+  const error = streams.stderr.trim();
+  if (code !== 0) {
+    throw (
+      openCodeError(streams.stdout) ??
+      new Error(error || `opencode exited with ${code}`)
+    );
+  }
+  return parseOpenCodeEvents(streams.stdout);
+}
+
+async function runProfile(profile: RuntimeProfile): Promise<AttemptResult> {
+  const token = await readProfileToken(profile);
+  const authentication =
+    profile.type === "CODEX" ? codexAuthentication(token ?? undefined) : null;
+  let stagedCodexAuth: string | null = null;
+  let body: string | null = null;
+  let resultPath: string | null = null;
+  let reviewPath: string | null = null;
+  let anchorsPath: string | null = null;
+  try {
+    if (authentication?.kind === "persistent") {
+      stagedCodexAuth = await stageCodexAuth(
+        CODEX_AUTH,
+        profile.home,
+        profile.uid,
+        profile.gid,
+      );
+    }
+    await prepareProfile(profile);
+    const rendered = await renderPrompt(profile);
+    reviewPath = rendered.reviewPath;
+    anchorsPath = rendered.anchorsPath;
+    if (profile.type === "CLAUDE") {
+      body = await runClaude(profile, token ?? "", rendered.prompt);
+    } else if (profile.type === "CODEX") {
+      resultPath = await runCodex(
+        profile,
+        rendered.prompt,
+        authentication ?? codexAuthentication(token ?? undefined),
+      );
+    } else {
+      body = await runOpenCode(profile, token ?? "", rendered.prompt);
+    }
+  } finally {
+    await killProfileProcesses(profile.uid);
+    if (stagedCodexAuth !== null) {
+      await persistCodexAuth(stagedCodexAuth, CODEX_AUTH);
+    }
+  }
+  if (resultPath !== null) {
+    body = await readProfileFile(profile, resultPath);
+  }
+  if (body === null || reviewPath === null || anchorsPath === null) {
+    throw new Error("agent attempt produced no result");
+  }
+  return {
+    body,
+    reviewPath,
+    anchorsPath,
+    profile: { type: profile.type, model: profile.model },
+  };
+}
+
+async function writeOutcome(outcome: RuntimeOutcome): Promise<void> {
+  await writeFile(MANIFEST.outcomeFile, JSON.stringify(outcome), {
+    mode: 0o600,
+  });
+  await chmod(MANIFEST.outcomeFile, 0o600);
+}
+
+const failures: ProfileFailure[] = [];
+try {
+  await configureGitAuthor();
+  await writeOutcome({
+    ok: true,
+    ...(await runProfiles(MANIFEST.profiles, runProfile, failures)),
+  });
+} catch (error) {
+  console.error(error);
+  await writeOutcome({ ok: false, failures });
+  throw error;
+}

src/runtime/credentials.test.ts

@@ -0,0 +1,95 @@
+import { expect, test } from "vite-plus/test";
+
+import {
+  decryptCredential,
+  encryptCredential,
+  parseCredentials,
+} from "./credentials.ts";
+
+const MASTER_KEY = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8";
+const OTHER_KEY = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE";
+const NONCE = Uint8Array.from({ length: 12 }, (_value, index) => index + 32);
+const ENCRYPTED = "v1:ICEiIyQlJicoKSor:oV_FAgnsN3p1FyegJxwGVdyjfyPio6qDeSUwbA";
+
+test("decrypts a known AES-256-GCM credential", async () => {
+  expect(await decryptCredential(ENCRYPTED, MASTER_KEY)).toBe("secret-token");
+});
+
+test("encrypts a credential with a fresh supplied nonce", async () => {
+  expect(
+    await encryptCredential("secret-token", MASTER_KEY, NONCE),
+  ).toStrictEqual(ENCRYPTED);
+});
+
+test("rejects a credential encrypted by another master key", async () => {
+  await expect(decryptCredential(ENCRYPTED, OTHER_KEY)).rejects.toThrow();
+});
+
+test("rejects a credential with a nonstandard nonce", async () => {
+  await expect(
+    decryptCredential(
+      "v1:AA:oV_FAgnsN3p1FyegJxwGVdyjfyPio6qDeSUwbA",
+      MASTER_KEY,
+    ),
+  ).rejects.toThrow("nonce must be 12 bytes");
+});
+
+test("decrypts the central reviewer token and ordered profiles", async () => {
+  expect(
+    await parseCredentials(
+      JSON.stringify({
+        "reviewer-token": ENCRYPTED,
+        profiles: [
+          { type: "CODEX", model: "gpt-custom" },
+          { type: "CLAUDE", token: ENCRYPTED },
+          { type: "OPENCODE", token: ENCRYPTED },
+        ],
+      }),
+      MASTER_KEY,
+    ),
+  ).toStrictEqual({
+    reviewerToken: "secret-token",
+    profiles: [
+      { type: "CODEX", model: "gpt-custom" },
+      {
+        type: "CLAUDE",
+        model: "claude-sonnet-5",
+        token: "secret-token",
+      },
+      {
+        type: "OPENCODE",
+        model: "openrouter/qwen/qwen3.8-27b",
+        token: "secret-token",
+      },
+    ],
+  });
+});
+
+test("rejects malformed central credentials", async () => {
+  await expect(
+    parseCredentials('{"profiles": []}', MASTER_KEY),
+  ).rejects.toThrow("reviewer-token");
+  await expect(
+    parseCredentials(
+      JSON.stringify({
+        "reviewer-token": ENCRYPTED,
+        profiles: [{ type: "CLAUDE" }],
+      }),
+      MASTER_KEY,
+    ),
+  ).rejects.toThrow("profiles[0].token");
+});
+
+test("reads lowercase profile types from older credentials", async () => {
+  const credentials = await parseCredentials(
+    JSON.stringify({
+      "reviewer-token": ENCRYPTED,
+      profiles: [{ type: "codex" }, { type: "claude", token: ENCRYPTED }],
+    }),
+    MASTER_KEY,
+  );
+  expect(credentials.profiles.map(({ type }) => type)).toStrictEqual([
+    "CODEX",
+    "CLAUDE",
+  ]);
+});

src/runtime/credentials.ts

@@ -0,0 +1,185 @@
+import { webcrypto } from "node:crypto";
+
+import { field, isMapping } from "#common";
+import type { BotProfile } from "#profiles";
+
+// The model a profile runs when profiles.json names none.
+function defaultModel(type: BotProfile["type"]): string {
+  switch (type) {
+    case "CLAUDE":
+      return "claude-sonnet-5";
+    case "CODEX":
+      return "gpt-5.6-terra";
+    case "OPENCODE":
+      return "openrouter/qwen/qwen3.8-27b";
+  }
+}
+
+export interface BotCredentials {
+  reviewerToken: string;
+  profiles: BotProfile[];
+}
+
+function decodeBase64Url(value: string): Uint8Array {
+  const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  return Uint8Array.from(
+    atob(padded),
+    (character) => character.codePointAt(0) ?? 0,
+  );
+}
+
+function encodeBase64Url(value: Uint8Array): string {
+  const binary = Array.from(value, (byte) => String.fromCodePoint(byte)).join(
+    "",
+  );
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+const buffer = (value: Uint8Array): ArrayBuffer =>
+  Uint8Array.from(value).buffer;
+
+async function importMasterKey(
+  encoded: string,
+  usage: webcrypto.KeyUsage,
+): Promise<webcrypto.CryptoKey> {
+  const bytes = decodeBase64Url(encoded);
+  if (bytes.length !== 32) {
+    throw new Error("master-key must be 32 bytes encoded as base64url");
+  }
+  const key = await webcrypto.subtle.importKey(
+    "raw",
+    buffer(bytes),
+    "AES-GCM",
+    false,
+    [usage],
+  );
+  return key;
+}
+
+export async function decryptCredential(
+  encrypted: string,
+  masterKey: string,
+): Promise<string> {
+  const [version, encodedNonce = "", encodedCiphertext = "", extra = ""] =
+    encrypted.split(":");
+  if (
+    version !== "v1" ||
+    encodedNonce === "" ||
+    encodedCiphertext === "" ||
+    extra !== ""
+  ) {
+    throw new Error("credential must use v1:<nonce>:<ciphertext>");
+  }
+  const nonce = decodeBase64Url(encodedNonce);
+  if (nonce.length !== 12) {
+    throw new Error("credential nonce must be 12 bytes");
+  }
+  const plaintext = await webcrypto.subtle.decrypt(
+    { name: "AES-GCM", iv: buffer(nonce) },
+    await importMasterKey(masterKey, "decrypt"),
+    buffer(decodeBase64Url(encodedCiphertext)),
+  );
+  return new TextDecoder().decode(plaintext);
+}
+
+export async function encryptCredential(
+  plaintext: string,
+  masterKey: string,
+  nonce: Uint8Array = webcrypto.getRandomValues(new Uint8Array(12)),
+): Promise<string> {
+  if (nonce.length !== 12) {
+    throw new Error("AES-GCM nonce must be 12 bytes");
+  }
+  const ciphertext = await webcrypto.subtle.encrypt(
+    { name: "AES-GCM", iv: buffer(nonce) },
+    await importMasterKey(masterKey, "encrypt"),
+    new TextEncoder().encode(plaintext),
+  );
+  return `v1:${encodeBase64Url(nonce)}:${encodeBase64Url(new Uint8Array(ciphertext))}`;
+}
+
+// profiles.json files written before the UPPER_SNAKE switch spell types in lowercase.
+const OLD_PROFILE_TYPES = new Map<unknown, BotProfile["type"]>([
+  ["claude", "CLAUDE"],
+  ["codex", "CODEX"],
+  ["opencode", "OPENCODE"],
+]);
+
+function currentSpelling(type: unknown): unknown {
+  return OLD_PROFILE_TYPES.get(type) ?? type;
+}
+
+async function parseProfile(
+  entry: unknown,
+  index: number,
+  masterKey: string,
+): Promise<BotProfile> {
+  const at = `profiles[${index}]`;
+  if (!isMapping(entry)) {
+    throw new TypeError(`${at}: expected a mapping`);
+  }
+  for (const key of Object.keys(entry)) {
+    if (key !== "type" && key !== "model" && key !== "token") {
+      throw new Error(`${at}.${key}: unknown field`);
+    }
+  }
+  const type = currentSpelling(field(entry, "type"));
+  const model = field(entry, "model");
+  const token = field(entry, "token");
+  if (type !== "CLAUDE" && type !== "CODEX" && type !== "OPENCODE") {
+    throw new Error(`${at}.type: expected "CLAUDE", "CODEX", or "OPENCODE"`);
+  }
+  if (model !== undefined && (typeof model !== "string" || model === "")) {
+    throw new Error(`${at}.model: expected a model name`);
+  }
+  if ((type === "CLAUDE" || type === "OPENCODE") && typeof token !== "string") {
+    throw new Error(`${at}.token: expected an encrypted credential`);
+  }
+  if (token !== undefined && typeof token !== "string") {
+    throw new Error(`${at}.token: expected an encrypted credential`);
+  }
+  return {
+    type,
+    model: model ?? defaultModel(type),
+    ...(typeof token === "string" && {
+      token: await decryptCredential(token, masterKey),
+    }),
+  };
+}
+
+export async function parseCredentials(
+  text: string,
+  masterKey: string,
+): Promise<BotCredentials> {
+  const value: unknown = JSON.parse(text);
+  if (!isMapping(value)) {
+    throw new TypeError("credentials must be a mapping");
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "reviewer-token" && key !== "profiles") {
+      throw new Error(`${key}: unknown field`);
+    }
+  }
+  const reviewerToken = field(value, "reviewer-token");
+  const profiles = field(value, "profiles");
+  if (typeof reviewerToken !== "string") {
+    throw new TypeError("reviewer-token: expected an encrypted credential");
+  }
+  if (!Array.isArray(profiles) || profiles.length === 0) {
+    throw new Error("profiles must contain at least one profile");
+  }
+  const parsed = await Promise.all(
+    profiles.map(async (entry: unknown, index) => {
+      const profile = await parseProfile(entry, index, masterKey);
+      return profile;
+    }),
+  );
+  return {
+    reviewerToken: await decryptCredential(reviewerToken, masterKey),
+    profiles: parsed,
+  };
+}

src/runtime/index.ts

@@ -0,0 +1,10 @@
+// The runtime the prepare phase writes for the later phases: decrypted
+// credentials laid out per profile, described by a manifest.
+export { prepareRuntime, readRuntimeManifest } from "./runtime.ts";
+export type {
+  RuntimeFailure,
+  RuntimeManifest,
+  RuntimeOutcome,
+  RuntimeProfile,
+  RuntimeSuccess,
+} from "./runtime.ts";

src/runtime/runtime.test.ts

@@ -0,0 +1,129 @@
+import { spawnSync } from "node:child_process";
+import {
+  chmod,
+  readdir,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { assert, expect, test } from "vite-plus/test";
+
+import { IS_ROOT, makeTempDir } from "#testing";
+
+import { prepareRuntime, type RuntimeProfile } from "./runtime.ts";
+
+const MASTER_KEY = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8";
+const ENCRYPTED = "v1:ICEiIyQlJicoKSor:oV_FAgnsN3p1FyegJxwGVdyjfyPio6qDeSUwbA";
+
+// Runs `command` as the profile's user, from the root directory.
+function runAs(
+  profile: RuntimeProfile,
+  command: string,
+  path: string,
+): boolean {
+  const result = spawnSync(command, [path], {
+    cwd: "/",
+    uid: profile.uid,
+    gid: profile.gid,
+  });
+  return result.status === 0;
+}
+
+async function expectPrivate(
+  path: string,
+  uid: number,
+  mode: number,
+): Promise<void> {
+  const info = await stat(path);
+  expect(info.uid).toStrictEqual(uid);
+  expect(info.mode & 0o777).toBe(mode);
+}
+
+test.skipIf(!IS_ROOT)(
+  "prepares root-only reviewer and isolated profile credentials",
+  async () => {
+    const root = await makeTempDir();
+    await chmod(root, 0o711);
+    const action = await makeTempDir();
+    try {
+      await writeFile(
+        `${action}/profiles.json`,
+        JSON.stringify({
+          "reviewer-token": ENCRYPTED,
+          profiles: [{ type: "CLAUDE", token: ENCRYPTED }, { type: "CODEX" }],
+        }),
+      );
+
+      const manifest = await prepareRuntime(action, root, MASTER_KEY);
+      const serialized = await readFile(manifest.manifestPath, "utf8");
+      assert(!serialized.includes("secret-token"));
+      expect(await readFile(manifest.reviewerFile, "utf8")).toBe(
+        "secret-token",
+      );
+      await expectPrivate(manifest.reviewerFile, 0, 0o600);
+
+      const [claude, codex] = manifest.profiles;
+      assert(claude !== undefined && codex !== undefined);
+      expect(claude.uid).not.toStrictEqual(codex.uid);
+      await expectPrivate(claude.home, claude.uid, 0o700);
+      assert(claude.tokenFile !== null);
+      expect(await readFile(claude.tokenFile, "utf8")).toBe("secret-token");
+      await expectPrivate(claude.tokenFile, claude.uid, 0o600);
+      const codexHome = await stat(codex.home);
+      expect(codexHome.uid).toStrictEqual(codex.uid);
+      expect(codex.tokenFile).toBe(null);
+
+      const ownToken = spawnSync("/bin/cat", [claude.tokenFile], {
+        cwd: "/",
+        uid: claude.uid,
+        gid: claude.gid,
+        encoding: "utf8",
+      });
+      expect(ownToken.status).toBe(0);
+      expect(ownToken.stdout).toBe("secret-token");
+      expect(runAs(claude, "/bin/cat", manifest.reviewerFile)).toBe(false);
+      expect(runAs(claude, "/bin/ls", codex.home)).toBe(false);
+    } finally {
+      await rm(root, { recursive: true });
+      await rm(action, { recursive: true });
+    }
+  },
+);
+
+test.skipIf(!IS_ROOT)(
+  "removes prepared credentials when output publication fails",
+  async () => {
+    const root = await makeTempDir();
+    const action = await makeTempDir();
+    try {
+      await writeFile(
+        `${action}/profiles.json`,
+        JSON.stringify({
+          "reviewer-token": ENCRYPTED,
+          profiles: [{ type: "CLAUDE", token: ENCRYPTED }],
+        }),
+      );
+      const result = spawnSync(
+        process.execPath,
+        [fileURLToPath(new URL("../prepare/index.ts", import.meta.url))],
+        {
+          env: Object.fromEntries([
+            ["ACTION_PATH", action],
+            ["RUNNER_TEMP", root],
+            ["BOT_AGENTS_MASTER_KEY", MASTER_KEY],
+            ["GITHUB_OUTPUT", action],
+          ]),
+        },
+      );
+
+      expect(result.status).not.toBe(0);
+      expect(await readdir(root)).toStrictEqual([]);
+    } finally {
+      await rm(root, { recursive: true });
+      await rm(action, { recursive: true });
+    }
+  },
+);

src/runtime/runtime.ts

@@ -0,0 +1,137 @@
+import {
+  chmod,
+  chown,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import nodePath from "node:path";
+
+import { field, isMapping } from "#common";
+import type { ProfileFailure, ProfileIdentity } from "#profiles";
+
+import { parseCredentials } from "./credentials.ts";
+
+const FIRST_PROFILE_UID = 20_000;
+
+export interface RuntimeProfile extends ProfileIdentity {
+  index: number;
+  uid: number;
+  gid: number;
+  home: string;
+  tokenFile: string | null;
+}
+
+export interface RuntimeManifest {
+  runtimeDir: string;
+  manifestPath: string;
+  reviewerFile: string;
+  outcomeFile: string;
+  profiles: RuntimeProfile[];
+}
+
+export interface RuntimeSuccess {
+  ok: true;
+  body: string;
+  reviewPath: string;
+  anchorsPath: string;
+  profile: ProfileIdentity;
+}
+
+export interface RuntimeFailure {
+  ok: false;
+  failures: ProfileFailure[];
+}
+
+export type RuntimeOutcome = RuntimeSuccess | RuntimeFailure;
+
+async function writePrivate(
+  path: string,
+  value: string,
+  uid: number,
+  gid: number,
+): Promise<void> {
+  await writeFile(path, value, { mode: 0o600 });
+  await chmod(path, 0o600);
+  await chown(path, uid, gid);
+}
+
+export async function prepareRuntime(
+  actionPath: string,
+  runtimeRoot: string,
+  masterKey: string,
+): Promise<RuntimeManifest> {
+  const credentials = await parseCredentials(
+    await readFile(nodePath.join(actionPath, "profiles.json"), "utf8"),
+    masterKey,
+  );
+  const runtimeDir = await mkdtemp(nodePath.join(runtimeRoot, "bot-agents-"));
+  try {
+    await chmod(runtimeDir, 0o711);
+    const reviewerFile = nodePath.join(runtimeDir, "reviewer-token");
+    await writePrivate(reviewerFile, credentials.reviewerToken, 0, 0);
+
+    // One profile at a time, in order, as each claims the next UID.
+    const profiles: RuntimeProfile[] = [];
+    for (const [index, profile] of credentials.profiles.entries()) {
+      const uid = FIRST_PROFILE_UID + index;
+      const home = nodePath.join(runtimeDir, `profile-${index}`);
+      await mkdir(home, { mode: 0o700 });
+      await chmod(home, 0o700);
+      await chown(home, uid, uid);
+      const tokenFile =
+        profile.token === undefined || profile.token === ""
+          ? null
+          : nodePath.join(home, "token");
+      if (tokenFile !== null && profile.token !== undefined) {
+        await writePrivate(tokenFile, profile.token, uid, uid);
+      }
+      profiles.push({
+        index,
+        type: profile.type,
+        model: profile.model,
+        uid,
+        gid: uid,
+        home,
+        tokenFile,
+      });
+    }
+
+    const manifestPath = nodePath.join(runtimeDir, "manifest.json");
+    const manifest: RuntimeManifest = {
+      runtimeDir,
+      manifestPath,
+      reviewerFile,
+      outcomeFile: nodePath.join(runtimeDir, "outcome.json"),
+      profiles,
+    };
+    await writePrivate(manifestPath, JSON.stringify(manifest), 0, 0);
+    return manifest;
+  } catch (error) {
+    await rm(runtimeDir, { recursive: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function isRuntimeManifest(value: unknown): value is RuntimeManifest {
+  return (
+    isMapping(value) &&
+    typeof field(value, "runtimeDir") === "string" &&
+    typeof field(value, "manifestPath") === "string" &&
+    typeof field(value, "reviewerFile") === "string" &&
+    typeof field(value, "outcomeFile") === "string" &&
+    Array.isArray(field(value, "profiles"))
+  );
+}
+
+export async function readRuntimeManifest(
+  path: string,
+): Promise<RuntimeManifest> {
+  const value: unknown = JSON.parse(await readFile(path, "utf8"));
+  if (!isRuntimeManifest(value)) {
+    throw new Error(`${path}: invalid runtime manifest`);
+  }
+  return value;
+}

src/testing/index.ts

@@ -0,0 +1,65 @@
+// Test support: the current user's IDs, a fresh temporary directory, the
+// inherited environment, and a plain command runner. It imports no source
+// module, so the repository-level tests in tests/, which reach src/ only
+// through `#testing`, never touch internals.
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import nodePath from "node:path";
+import process from "node:process";
+import { text } from "node:stream/consumers";
+
+export function currentUid(): number {
+  return process.getuid?.() ?? -1;
+}
+
+export function currentGid(): number {
+  return process.getgid?.() ?? -1;
+}
+
+// The isolation tests switch UIDs, which only root may do.
+export const IS_ROOT: boolean = currentUid() === 0;
+
+// Symlinks and POSIX modes, as these tests use them, need a Unix host.
+export const IS_WINDOWS: boolean = process.platform === "win32";
+
+export async function makeTempDir(): Promise<string> {
+  const path = await mkdtemp(nodePath.join(tmpdir(), "bot-agents-test-"));
+  return path;
+}
+
+export interface CommandResult {
+  success: boolean;
+  stderr: string;
+}
+
+// This process's environment as a map from variable name to value.
+export function inheritedEnvironment(): Map<string, string> {
+  const result = new Map<string, string>();
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      result.set(name, value);
+    }
+  }
+  return result;
+}
+
+// Runs a command with stdin closed and only the given environment, and
+// collects its stderr.
+export async function runCommand(
+  command: string,
+  args: string[],
+  env: ReadonlyMap<string, string>,
+): Promise<CommandResult> {
+  const child = spawn(command, args, {
+    env: Object.fromEntries(env),
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  const [stderr, closed] = await Promise.all([
+    text(child.stderr),
+    once(child, "close"),
+  ]);
+  const exitCode: unknown = closed[0];
+  return { success: exitCode === 0, stderr };
+}

superpowers.ts

@@ -1,147 +0,0 @@
-import { join } from "jsr:@std/path@1";
-
-export type BotType = "claude" | "codex";
-
-export type InstallCommand = {
-  command: string;
-  args: string[];
-};
-
-export type SuperpowersReviewGuide = {
-  version: string;
-  skillPath: string;
-  templatePath: string;
-  skill: string;
-  template: string;
-};
-
-export type SuperpowersFileSystem = {
-  readDir(path: string): AsyncIterable<Deno.DirEntry>;
-  readTextFile(path: string): Promise<string>;
-};
-
-const systemFileSystem: SuperpowersFileSystem = {
-  readDir: Deno.readDir,
-  readTextFile: Deno.readTextFile,
-};
-
-export function parseBotType(value: string): BotType {
-  if (value === "claude" || value === "codex") return value;
-  throw new Error(`unsupported bot type: ${value}`);
-}
-
-export function superpowersInstallCommands(
-  bot: BotType,
-): InstallCommand[] {
-  if (bot === "claude") {
-    return [
-      {
-        command: "claude",
-        args: [
-          "plugin",
-          "marketplace",
-          "add",
-          "obra/superpowers-marketplace",
-        ],
-      },
-      {
-        command: "claude",
-        args: [
-          "plugin",
-          "install",
-          "-y",
-          "superpowers@superpowers-marketplace",
-        ],
-      },
-    ];
-  }
-  return [{
-    command: "codex",
-    args: ["plugin", "add", "superpowers@openai-curated-remote"],
-  }];
-}
-
-type Candidate = SuperpowersReviewGuide & { directory: string };
-
-async function readCandidate(
-  directory: string,
-  fileSystem: SuperpowersFileSystem,
-): Promise<Candidate | null> {
-  if (!directory.split(/[\\/]/).includes("superpowers")) return null;
-  const skillPath = join(directory, "SKILL.md");
-  const templatePath = join(directory, "code-reviewer.md");
-  try {
-    const [skill, template] = await Promise.all([
-      fileSystem.readTextFile(skillPath),
-      fileSystem.readTextFile(templatePath),
-    ]);
-    return {
-      directory,
-      version: directory.split(/[\\/]/).at(-3) ?? "unknown",
-      skillPath,
-      templatePath,
-      skill,
-      template,
-    };
-  } catch (error) {
-    if (error instanceof Deno.errors.NotFound) return null;
-    throw error;
-  }
-}
-
-async function findCandidates(
-  directory: string,
-  candidates: Candidate[],
-  fileSystem: SuperpowersFileSystem,
-): Promise<void> {
-  let entries: Deno.DirEntry[];
-  try {
-    entries = [];
-    for await (const entry of fileSystem.readDir(directory)) {
-      entries.push(entry);
-    }
-  } catch (error) {
-    if (error instanceof Deno.errors.NotFound) return;
-    throw error;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory) continue;
-    const child = join(directory, entry.name);
-    if (entry.name === "requesting-code-review") {
-      const candidate = await readCandidate(child, fileSystem);
-      if (candidate !== null) candidates.push(candidate);
-    } else {
-      await findCandidates(child, candidates, fileSystem);
-    }
-  }
-}
-
-// Load the installed files rather than trusting skill discovery in a later
-// non-interactive agent process. The newest cached plugin version is the one
-// the installers activate, and the exact paths are reported by the caller.
-export async function loadSuperpowersReviewGuide(
-  bot: BotType,
-  home: string,
-  fileSystem: SuperpowersFileSystem = systemFileSystem,
-): Promise<SuperpowersReviewGuide> {
-  const root = join(
-    home,
-    bot === "codex" ? ".codex" : ".claude",
-    "plugins",
-    "cache",
-  );
-  const candidates: Candidate[] = [];
-  await findCandidates(root, candidates, fileSystem);
-  candidates.sort((left, right) =>
-    left.version.localeCompare(right.version, undefined, { numeric: true }) ||
-    left.directory.localeCompare(right.directory)
-  );
-  const guide = candidates.at(-1);
-  if (guide === undefined) {
-    throw new Error(
-      `installed Superpowers requesting-code-review files not found under ${root}`,
-    );
-  }
-  const { directory: _, ...result } = guide;
-  return result;
-}

superpowers_test.ts

@@ -1,119 +0,0 @@
-import { assertEquals, assertRejects, assertThrows } from "jsr:@std/assert@1";
-import { join } from "jsr:@std/path@1";
-import {
-  loadSuperpowersReviewGuide,
-  parseBotType,
-  type SuperpowersFileSystem,
-  superpowersInstallCommands,
-} from "./superpowers.ts";
-
-function fakeFileSystem(files: Record<string, string>): SuperpowersFileSystem {
-  return {
-    readTextFile(path) {
-      const contents = files[path];
-      return contents === undefined
-        ? Promise.reject(new Deno.errors.NotFound(path))
-        : Promise.resolve(contents);
-    },
-    async *readDir(directory) {
-      const prefix = `${directory}/`;
-      const children = new Map<string, boolean>();
-      for (const path of Object.keys(files)) {
-        if (!path.startsWith(prefix)) continue;
-        const [name, ...rest] = path.slice(prefix.length).split("/");
-        if (name !== "") children.set(name, rest.length > 0);
-      }
-      if (children.size === 0) throw new Deno.errors.NotFound(directory);
-      for (const [name, isDirectory] of children) {
-        yield {
-          name,
-          isDirectory,
-          isFile: !isDirectory,
-          isSymlink: false,
-        };
-      }
-    },
-  };
-}
-
-Deno.test("installs Superpowers from the Codex marketplace", () => {
-  assertEquals(superpowersInstallCommands("codex"), [{
-    command: "codex",
-    args: ["plugin", "add", "superpowers@openai-curated-remote"],
-  }]);
-});
-
-Deno.test("installs Superpowers from the Claude marketplace", () => {
-  assertEquals(superpowersInstallCommands("claude"), [
-    {
-      command: "claude",
-      args: [
-        "plugin",
-        "marketplace",
-        "add",
-        "obra/superpowers-marketplace",
-      ],
-    },
-    {
-      command: "claude",
-      args: [
-        "plugin",
-        "install",
-        "-y",
-        "superpowers@superpowers-marketplace",
-      ],
-    },
-  ]);
-});
-
-Deno.test("rejects an unsupported bot type", () => {
-  assertThrows(
-    () => parseBotType("other"),
-    Error,
-    "unsupported bot type: other",
-  );
-});
-
-Deno.test("loads the newest installed Superpowers review guide", async () => {
-  const home = "/home/bot";
-  const older = join(
-    home,
-    ".codex/plugins/cache/openai-curated-remote/superpowers/6.3.0/skills/requesting-code-review",
-  );
-  const newer = join(
-    home,
-    ".codex/plugins/cache/openai-curated-remote/superpowers/6.10.0/skills/requesting-code-review",
-  );
-  const guide = await loadSuperpowersReviewGuide(
-    "codex",
-    home,
-    fakeFileSystem({
-      [join(older, "SKILL.md")]: "old",
-      [join(older, "code-reviewer.md")]: "old template",
-      [join(newer, "SKILL.md")]: "new",
-      [join(newer, "code-reviewer.md")]: "template",
-    }),
-  );
-
-  assertEquals(guide.version, "6.10.0");
-  assertEquals(guide.skill, "new");
-  assertEquals(guide.template, "template");
-  assertEquals(guide.skillPath, join(newer, "SKILL.md"));
-});
-
-Deno.test("fails when the installed review guide is incomplete", async () => {
-  const home = "/home/bot";
-  const directory = join(
-    home,
-    ".claude/plugins/cache/superpowers-marketplace/superpowers/6.3.0/skills/requesting-code-review",
-  );
-  const fileSystem = fakeFileSystem({
-    [join(directory, "SKILL.md")]: "skill",
-  });
-
-  await assertRejects(
-    () => loadSuperpowersReviewGuide("claude", home, fileSystem),
-    Error,
-    "installed Superpowers requesting-code-review files not found",
-  );
-});

tests/entrypoints.test.ts

@@ -0,0 +1,27 @@
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vite-plus/test";
+
+import { runCommand } from "#testing";
+
+// Each phase runs as `node src/<phase>/index.ts` with no build step. Node loads the
+// whole import graph, stripping types, before the phase reads its first
+// variable, so failing on that variable proves every module loads.
+const PHASES: [phase: string, firstVariable: string][] = [
+  ["prepare", "ACTION_PATH"],
+  ["run", "GITEA_API_URL"],
+  ["post", "BOT_AGENTS_MANIFEST"],
+];
+
+test.each(PHASES)("Node loads the %s phase", async (phase, firstVariable) => {
+  const path = fileURLToPath(
+    new URL(`../src/${phase}/index.ts`, import.meta.url),
+  );
+  const result = await runCommand(
+    process.execPath,
+    [path],
+    new Map([["PATH", process.env["PATH"] ?? ""]]),
+  );
+  expect(result.success).toBe(false);
+  expect(result.stderr).toContain(`${firstVariable} is not set`);
+});

tests/workflow.test.ts

@@ -0,0 +1,247 @@
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import process from "node:process";
+import { assert, expect, test } from "vite-plus/test";
+import { parse } from "yaml";
+
+import { inheritedEnvironment, makeTempDir, runCommand } from "#testing";
+
+// A parsed YAML or JSON mapping, keyed by its dynamic field names.
+type Mapping = Map<string, unknown>;
+
+const mapping = (value: unknown, at: string): Mapping => {
+  assert(
+    typeof value === "object" && value !== null && !Array.isArray(value),
+    at,
+  );
+  return new Map(Object.entries(value));
+};
+
+const sequence = (value: unknown, at: string): Mapping[] => {
+  assert(Array.isArray(value), at);
+  return value.map((entry: unknown, index) =>
+    mapping(entry, `${at}[${index}]`),
+  );
+};
+
+async function yaml(path: string): Promise<Mapping> {
+  const value: unknown = parse(await readFile(path, "utf8"));
+  return mapping(value, path);
+}
+
+async function yamlFiles(): Promise<string[]> {
+  const entries = await readdir(".", { recursive: true, withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && /\.ya?ml$/u.test(entry.name))
+    .map((entry) => `${entry.parentPath}/${entry.name}`.replace(/^\.\//u, ""))
+    .filter((path) => !/^(?:\.git|\.superpowers|node_modules)\//u.test(path));
+}
+
+const findStep = (steps: Mapping[], key: string, value: string): Mapping => {
+  const step = steps.find((entry) => entry.get(key) === value);
+  assert(step !== undefined, `${key}: ${value}`);
+  return step;
+};
+
+test("all committed YAML parses", async () => {
+  const files = await yamlFiles();
+  assert(files.length > 0);
+  await Promise.all(
+    files.map(async (file) => {
+      await yaml(file);
+    }),
+  );
+});
+
+test("the action exposes only the master key and scopes it to preparation", async () => {
+  const action = await yaml("action.yml");
+  expect([...mapping(action.get("inputs"), "inputs").keys()]).toStrictEqual([
+    "master-key",
+  ]);
+  const steps = sequence(
+    mapping(action.get("runs"), "runs").get("steps"),
+    "runs.steps",
+  );
+  for (const step of steps) {
+    const run = step.get("run");
+    if (typeof run === "string") {
+      expect(run.includes("\n"), String(step.get("name"))).toBe(false);
+    }
+  }
+  const checkout = findStep(steps, "uses", "actions/checkout@v4");
+  const prepare = findStep(steps, "id", "prepare");
+  const agent = findStep(steps, "id", "agent");
+  const post = findStep(steps, "id", "post");
+  findStep(steps, "id", "source");
+  expect(mapping(checkout.get("with"), "checkout.with").get("token")).toBe(
+    "${{ gitea.token }}",
+  );
+  expect(
+    mapping(prepare.get("env"), "prepare.env").get("BOT_AGENTS_MASTER_KEY"),
+  ).toBe("${{ inputs.master-key }}");
+  expect(
+    JSON.stringify(Object.fromEntries(agent)).includes("BOT_AGENTS_MASTER_KEY"),
+  ).toBe(false);
+  expect(
+    JSON.stringify(Object.fromEntries(post)).includes("BOT_AGENTS_MASTER_KEY"),
+  ).toBe(false);
+  expect(mapping(agent.get("env"), "agent.env").get("GITEA_TOKEN")).toBe(
+    "${{ gitea.token }}",
+  );
+  assert(String(post.get("if")).includes("always()"));
+  for (const step of [prepare, agent, post]) {
+    assert(String(step.get("run")).includes("steps.source.outputs.path"));
+  }
+});
+
+test("the source protection script stages immutable action files", async () => {
+  const temp = await makeTempDir();
+  const outputFile = `${temp}/output`;
+  try {
+    const environment = inheritedEnvironment();
+    environment.set("ACTION_PATH", process.cwd());
+    environment.set("GITHUB_OUTPUT", outputFile);
+    environment.set("RUNNER_TEMP", temp);
+    const result = await runCommand(
+      "/bin/bash",
+      ["scripts/protect-source.sh"],
+      environment,
+    );
+    assert(result.success, result.stderr);
+
+    const output = await readFile(outputFile, "utf8");
+    const path = output.trim().slice(5);
+    const files = [
+      "src/prepare/index.ts",
+      "src/run/index.ts",
+      "src/post/index.ts",
+      "src/runtime/index.ts",
+      "src/agents/auth.ts",
+      "package.json",
+      "profiles.json",
+      "prompt.md",
+    ];
+    const stats = await Promise.all(
+      files.map(async (file) => {
+        const info = await stat(`${path}/${file}`);
+        return info;
+      }),
+    );
+    for (const [index, info] of stats.entries()) {
+      assert(info.isFile(), files[index]);
+      expect(info.mode & 0o022, files[index]).toStrictEqual(0);
+    }
+  } finally {
+    await rm(temp, { recursive: true });
+  }
+});
+
+test("module-relative runtime assets exist", async () => {
+  const module = new URL("../src/run/index.ts", import.meta.url);
+  const source = await readFile(module, "utf8");
+  const assets = [
+    ...source.matchAll(/new URL\("(?<asset>[^"]+)", import\.meta\.url\)/gu),
+  ].map(([, asset = ""]) => new URL(asset, module));
+  const stats = await Promise.all(
+    assets.map(async (asset) => {
+      const info = await stat(asset);
+      return info;
+    }),
+  );
+  for (const [index, info] of stats.entries()) {
+    assert(info.isFile(), assets[index]?.pathname);
+  }
+});
+
+test("the repository uses its trusted main action", async () => {
+  const workflow = await yaml(".gitea/workflows/agents.yml");
+  const job = mapping(
+    mapping(workflow.get("jobs"), "jobs").get("agent"),
+    "jobs.agent",
+  );
+  const permissions = mapping(job.get("permissions"), "jobs.agent.permissions");
+  expect(Object.fromEntries(permissions)).toStrictEqual({
+    code: "write",
+    issues: "write",
+    "pull-requests": "write",
+  });
+  const steps = sequence(job.get("steps"), "jobs.agent.steps");
+  expect(steps.findIndex((step) => step.get("uses") === "./")).toStrictEqual(
+    -1,
+  );
+  const trusted = findStep(
+    steps,
+    "uses",
+    "https://git.capsulizers.com/commons/bot-agents@main",
+  );
+  expect(mapping(trusted.get("with"), "trusted.with").get("master-key")).toBe(
+    "${{ secrets.BOT_AGENTS_MASTER_KEY }}",
+  );
+  expect(
+    JSON.stringify(Object.fromEntries(workflow)).includes(
+      "gitea.actor != 'bot'",
+    ),
+  ).toBe(true);
+});
+
+test("CI checks every phase and the root isolation suite", async () => {
+  const workflow = await yaml(".gitea/workflows/check.yml");
+  const job = mapping(
+    mapping(workflow.get("jobs"), "jobs").get("check"),
+    "jobs.check",
+  );
+  const commands = sequence(job.get("steps"), "jobs.check.steps")
+    .map((step) => {
+      const run = step.get("run");
+      return typeof run === "string" ? run : "";
+    })
+    .join("\n");
+  // `vp check` type-checks every phase, and `vp test` runs each of them under
+  // Node as well as the root-only isolation tests.
+  assert(commands.includes("npm ci"));
+  assert(commands.includes("vp check"));
+  assert(commands.includes("vp test"));
+});
+
+test("uses the standard Skills installer without custom discovery", async () => {
+  const runner = await readFile("src/run/index.ts", "utf8");
+  assert(runner.includes("skills add obra/superpowers"));
+  const removed = await stat("superpowers.ts").then(
+    () => false,
+    (error: unknown) =>
+      error instanceof Error && "code" in error && error.code === "ENOENT",
+  );
+  assert(removed, "superpowers.ts should be removed");
+});
+
+test("installs the OpenCode CLI", async () => {
+  const action = await readFile("action.yml", "utf8");
+  assert(action.includes("opencode-ai"));
+});
+
+test("does not install Deno", async () => {
+  const action = await readFile("action.yml", "utf8");
+  expect(action).not.toMatch(/\bdeno\b/iu);
+});
+
+test("profile preparation does not receive provider credentials", async () => {
+  const runner = await readFile("src/run/index.ts", "utf8");
+  assert(runner.includes("await prepareProfile(profile);"));
+  expect(runner.includes("prepareProfile(profile, token)")).toBe(false);
+});
+
+test("central profiles fall back from Claude to Codex to OpenCode", async () => {
+  const credentials: unknown = JSON.parse(
+    await readFile("profiles.json", "utf8"),
+  );
+  const profiles = sequence(
+    mapping(credentials, "profiles.json").get("profiles"),
+    "profiles",
+  );
+  expect(profiles.map((profile) => profile.get("type"))).toStrictEqual([
+    "CLAUDE",
+    "CODEX",
+    "OPENCODE",
+  ]);
+  expect(profiles[2]?.get("model")).toBe("openrouter/qwen/qwen3.8-27b");
+  assert(String(profiles[2]?.get("token")).startsWith("v1:"));
+});

tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "nodenext",
+    "lib": ["es2024"],
+    "types": ["node"],
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false
+  }
+}

vite.config.ts

@@ -0,0 +1,41 @@
+import explicitTypes from "eslint-plugin-explicit-types";
+import importStructure from "eslint-plugin-import-structure";
+import { defineConfig } from "vite-plus";
+
+import projectLint, { projectOverrides } from "./scripts/project-lint.ts";
+
+export default defineConfig({
+  fmt: {
+    printWidth: 80,
+    quoteProps: "preserve",
+    embeddedLanguageFormatting: "off",
+  },
+  lint: {
+    plugins: ["typescript", "unicorn", "oxc", "import"],
+    jsPlugins: [
+      "eslint-plugin-explicit-types",
+      "eslint-plugin-import-structure",
+      "./scripts/project-lint.ts",
+    ],
+    categories: {
+      correctness: "error",
+      suspicious: "error",
+      pedantic: "error",
+      perf: "error",
+      style: "error",
+      restriction: "error",
+    },
+    rules: {
+      ...explicitTypes.configs.all.rules,
+      ...importStructure.configs.all.rules,
+      ...projectLint.configs.project.rules,
+    },
+    overrides: projectOverrides,
+    options: {
+      typeAware: true,
+      typeCheck: true,
+      maxWarnings: 0,
+      reportUnusedDisableDirectives: "error",
+    },
+  },
+});