@ethlete/agent-rules 0.1.0-next.2 → 0.1.0-next.20

package/content/skills/angular-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: angular-patterns
-description: How to build Angular pieces the Ethlete way - templates, lifecycle, and when to reach for a component/directive/service/pipe vs a plain function. Read when writing or restructuring a component, directive, service, or pipe, wiring up lifecycle, or binding values in a template. Part of the Ethlete styleguide (judgment beyond what lint enforces).
+description: How to build Angular pieces the Ethlete way - templates, lifecycle, and when to reach for a component/directive/service/pipe vs a plain function. Read when writing or restructuring a component, directive, service, or pipe, wiring up lifecycle, or binding values in a template.
 kind: skill
 scope: both
 requires: ['@ethlete/core']
@@ -22,10 +22,20 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 
 ```html
 <!-- ❌ runs every CD cycle -->
-<button [disabled]="isDisabled()">
-  <!-- ✅ computed signal -->
-  <button [disabled]="disabled()"></button>
-</button>
+<button [disabled]="isDisabled()"></button>
+
+<!-- ✅ computed signal -->
+<button [disabled]="disabled()"></button>
+```
+
+- **Per-row formatting belongs in the data, not in a method per row.** Map the rows once
+  in a `computed()` and bind the prepared fields. A pure, module-level formatting function
+  is acceptable too; a component method called for each row in `@for` is not.
+
+```ts
+// ❌ <td>{{ formatDate(row.createdAt) }}</td> - re-runs for every row, every CD cycle
+// ✅
+rows = computed(() => this.items().map((item) => ({ ...item, createdAtLabel: formatDate(item.createdAt) })));
 ```
 
 ## Lifecycle
@@ -40,6 +50,10 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
   `createRootProvider` and the `injectX()` helper pattern from `@ethlete/core`
   rather than an `@Injectable` or `@Service`. (Both decorators are lint-banned;
   choosing a function over a service at all is the judgment.)
+- **Repeated component logic → one `injectX()` function.** When two components carry the
+  same signals, effects or subscriptions, extract them into an `injectX()` that runs in the
+  injection context and returns what the components bind. Do not copy the block, and do not
+  reach for a base class.
 - **Directives → plain functions where possible.** With signal APIs, move the core
   logic into a function so it's reusable without applying a directive; keep a
   directive only when a host element genuinely needs it. Avoid common input/output
@@ -47,12 +61,21 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 - **Pipes → a `computed()` calling a utility function.** Pipes carry no logic;
   most can be dropped in favour of a `computed`.
 
+## Query params
+
+- **Read** them with the `@ethlete/core` signals: `injectQueryParam(key)`,
+  `injectQueryParams()`. `ActivatedRoute` and `router.url` are lint-banned.
+- **Write** them with `inject(Router).navigate([], { queryParams, queryParamsHandling: 'merge' })`.
+  `merge` keeps the params you do not set; `null` removes a param.
+- **Filter, sort and page state bound to the URL** is a query form: with `@ethlete/query`,
+  use `defineQueryForm` instead of writing the params by hand.
+
 ## Components
 
 - Inline template/styles for small components; external `.html` / `.css` files
   for complex ones.
-- Component CSS is plain CSS wrapped in `@layer components`, with every colour coming
-  from a theme token — see {%skill:theming%}.
+- Component CSS is plain CSS wrapped in `@layer components`, with every primary colour
+  value coming from the repository's theme tokens.
 
 ## Reactive state
 

package/content/skills/api-source/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: api-source
+description: How to read the source of the API an app in this repo talks to, from a local backend checkout named in ethlete.config.local.json. Read when a response shape, a status code, an error body, an enum or an auth rule has to be confirmed rather than guessed - and never edit that checkout as part of work in this repo.
+kind: skill
+scope: consumer
+---
+
+# Reading the API source
+
+The client's types describe what the frontend _expects_. When the two disagree, the
+server is right, so a question about the contract is answered in the API repository -
+not by reading the frontend's own models harder.
+
+Reach for the checkout when:
+
+- a response arrives with a field, a shape or a `null` the frontend types do not allow
+- you need the exact status code, error body or validation message for a failure path
+- an enum, a permission or a filter parameter has to match the server's list exactly
+- a request fails and you cannot tell whether the client or the server is wrong
+- you are about to report or fix something in the API itself
+
+Do not read it to design frontend code that the API does not serve yet. An endpoint in
+the checkout is not deployed until the API team ships it.
+
+## 1. Resolve the checkout for your app
+
+One repository can hold several apps, each with its own API, so the paths are a map from
+app to checkout. They are per machine, so the map lives in the gitignored
+`ethlete.config.local.json` at the repo root:
+
+```json
+{
+  "apiRepoPaths": {
+    "hub": "../fut-hub-backend",
+    "*": "../shared-backend"
+  },
+  "apiRepoBranches": {
+    "hub": "develop",
+    "*": "main"
+  }
+}
+```
+
+Older checkouts still keep these keys in `ethlete-agents.config.local.json`. Read that file as a
+fallback when `ethlete.config.local.json` is absent.
+
+Read that file before searching anywhere. The rules:
+
+- **The key is the app** as this repo names it - the workspace project name, which is
+  normally also the folder under `apps/`. Match the app you are working in.
+- **A relative path resolves from the repo root**, not from the app folder.
+- **Require an exact app key.** If several apps intentionally share one API, configure
+  the explicit `"*"` fallback. Never treat an unrelated single entry as a fallback.
+- **No matching entry - stop and ask.** Do not guess a sibling folder and do not clone
+  the repository. Say which app you needed the API for and offer the snippet above; the
+  file is gitignored, so adding it changes nothing for anyone else.
+
+Without a checkout, fall back to what the running API tells you: the generated API
+description if the project serves one (`/openapi.json`, `/swagger`, `/api/doc`), and the
+real response body of the call you are debugging.
+
+## 2. Resolve the relevant files before judging checkout state
+
+Search by the route, field, or error you already know. Record the contract, serializer,
+handler, and tests that can answer the question. Then inspect checkout state only for
+those paths:
+
+```bash
+git -C <apiRepoPath> status -sb
+git -C <apiRepoPath> status --short -- <relevant-paths>
+git -C <apiRepoPath> diff -- <relevant-paths>
+```
+
+Unrelated dirty files are not evidence about these paths. Continue without blocking on
+them. If a relevant file is dirty, distinguish the worktree implementation from the
+committed or deployed behavior. Ask only when that difference changes the answer or the
+user has to choose which behavior matters.
+
+`apiRepoBranches` configures the expected branch per exact app key, with `"*"` as the
+only fallback. If no branch is configured, report the current branch as context; do not
+invent a blocking “development branch” requirement. A different or ahead branch matters
+only when the relevant files differ in that commit range.
+
+Use existing remote refs first. `git fetch` preserves the worktree but is not read-only:
+it uses the network and mutates remote refs. Fetch only when freshness is material, and
+request any approval the environment requires. Never switch, pull, stash, or reset the
+checkout yourself.
+
+## 3. The checkout is not the environment the app calls
+
+Even a clean, current checkout is only the source. The app talks to a deployed
+environment, which can lag it:
+
+- Read the app's API base URL from its environment config, and say which environment
+  your answer is about.
+- When the source and the observed response disagree, **the observed response wins** for
+  what the app has to handle today. Report the difference instead of writing client code
+  against the newer source.
+
+## 4. Search it, don't read it whole
+
+The stack is whatever the API team chose, so search by the thing you already know - the
+path, the field name, the error message - rather than by an expected file layout:
+
+```bash
+rg -n "api/v1/matches" <apiRepoPath> --glob '!*test*'   # the route
+rg -n "kickoffAt" <apiRepoPath>                         # a field of the payload
+rg -n "MATCH_NOT_FOUND" <apiRepoPath>                   # an error code you received
+```
+
+Two things to find first, because they answer most questions on their own:
+
+- **The API description** the project generates or checks in (OpenAPI, Swagger, GraphQL
+  schema, `.http` files). It is the contract, and it is cheaper to read than the code.
+- **The serializer, resource or DTO** for the entity - the field list the client sees,
+  which is usually a subset of the database model, and the place where a name is
+  rewritten between the two.
+
+The API's own tests describe intended behaviour more directly than the implementation:
+they name the status code and the body for each case.
+
+## 5. The checkout is read-only from here
+
+It is a different repository with its own branch, review and release process. Never edit
+it while working on a task in this repo, and never change its git state without being
+asked. A fetch also needs to meet the freshness and approval conditions above.
+
+When the fix belongs in the API, say so precisely: the endpoint, the field, and the
+behaviour it should have. Then handle the API as it is today - a client workaround for a
+server bug is a decision for the user, and it needs a comment naming what it waits on.

package/content/skills/app-testing/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: app-testing
+description: How to unit-test an app built on the Ethlete SDK - views that fetch through @ethlete/query (HttpTestingController and the @ethlete/query/testing helpers), components that open overlays, and views that read the URL with injectQueryParam under provideRouter. Read before writing or fixing a spec for a component, view or service that uses @ethlete/query, @ethlete/core router signals or @ethlete/components overlays.
+kind: skill
+scope: consumer
+requires: ['@ethlete/core']
+vars: [docsBaseUrl]
+---
+
+# Testing an Ethlete app
+
+Specs run in jsdom under `TestBed`. Test through the public API the view uses - mount the
+component, answer its requests, move the URL - and assert on what it renders or exposes. The full
+reference for the query helpers is {%docsBaseUrl%}/query/testing.
+
+## Views that fetch
+
+A client made with `createQueryClient` is provided in root, so a spec provides nothing for it. It
+needs Angular's HTTP testing backend, and answers each request by hand:
+
+```ts
+import { provideHttpClient } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+
+beforeEach(() => {
+  TestBed.configureTestingModule({ providers: [provideHttpClient(), provideHttpClientTesting()] });
+});
+
+afterEach(() => TestBed.inject(HttpTestingController).verify());
+
+it('renders the players', async () => {
+  const http = TestBed.inject(HttpTestingController);
+  const fixture = TestBed.createComponent(PlayersComponent);
+  fixture.detectChanges();
+  TestBed.tick();
+
+  http.expectOne((req) => req.url.includes('/players')).flush({ items: ['Müller'] });
+  await fixture.whenStable();
+
+  expect(fixture.nativeElement.textContent).toContain('Müller');
+});
+```
+
+- A GET query executes once its args resolve, which happens on change detection -
+  `TestBed.tick()` before `expectOne`, and again after `flush` before reading the query's
+  `response()`, `loading()` or `error()`.
+- `req.url` carries the query string, so `expectOne('https://api.example.com/players?search=mul')`
+  matches the full URL. Match with a predicate, as above, when the params are not the point.
+- Fail a request with `flush(body, { status: 422, statusText: 'Unprocessable Entity' })`.
+- Mutations (`POST`, `PUT`, `PATCH`, `DELETE`) never auto-execute - call `.execute({ args })`,
+  then expect the request.
+
+From `@ethlete/query/testing`:
+
+| Export                                                                        | Use                                                                                                                                 |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `expectAndFlush(http, url, body, status?)`                                    | `expectOne(url).flush(body)` in one call.                                                                                           |
+| `expectFlushAndWait(http, url, body, status?)`                                | The same, then `TestBed.tick()`.                                                                                                    |
+| `setupQueryTest(config?)`                                                     | A scratch client, `HttpTestingController`, `createGet` … `createDelete` creators - for testing code that takes a creator or client. |
+| `setupAuthTest({ querySetup })`                                               | A bearer auth provider on that scratch client, with `login()` / `refresh()` helpers that answer the requests.                       |
+| `createFakeQueryPersistenceStore()`                                           | In-memory persistence adapter - jsdom has no IndexedDB.                                                                             |
+| `installFakeBroadcastChannel()`, `installFakeWebLocks()`, `flushMultiTabSync` | Two clients in one spec behave as two tabs.                                                                                         |
+| `createWebSocketTestDouble()`                                                 | A scripted socket.io `io` for `createWebSocketClient({ io })`.                                                                      |
+
+`setupQueryTest` calls `TestBed.configureTestingModule` itself and replaces `ErrorHandler` with a
+no-op (`mockErrorHandler: false` keeps the real one). Call it inside `beforeEach`, and call
+`restoreConsole()` in `afterEach` if the file spies on `console`.
+
+## Views that read the URL
+
+`injectQueryParam`, `injectQueryParams`, `injectPathParam` and the other router signals from
+`@ethlete/core` read the router, so the spec provides one and navigates it:
+
+```ts
+import { provideRouter, Router } from '@angular/router';
+
+TestBed.configureTestingModule({
+  providers: [provideHttpClient(), provideHttpClientTesting(), provideRouter([])],
+});
+
+await TestBed.inject(Router).navigateByUrl('/?search=mul');
+const fixture = TestBed.createComponent(PlayersComponent);
+fixture.detectChanges();
+TestBed.tick();
+
+http.expectOne((req) => req.urlWithParams.includes('search=mul')).flush({ items: [] });
+
+await TestBed.inject(Router).navigateByUrl('/?search=x');
+TestBed.tick();
+http.expectOne((req) => req.urlWithParams.includes('search=x')).flush({ items: [] });
+```
+
+Navigate to change a param - never set the signal or mock the inject function. A view that also
+reads path params needs the real route in the config (`provideRouter([{ path: 'players/:id',
+component: PlayersComponent }])`) and `RouterTestingHarness` from `@angular/router/testing` to
+render it.
+
+## Components that open overlays
+
+An overlay mounts at the end of `document.body`, not in the fixture, and it opens and closes over
+animation frames. Query the document, wait two frames, and close what is left after each test:
+
+```ts
+import { injectOverlayManager } from '@ethlete/components';
+
+const flushFrames = () =>
+  new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+
+afterEach(async () => {
+  TestBed.runInInjectionContext(() => injectOverlayManager())
+    .openOverlays()
+    .forEach((ref) => ref.forceClose());
+  await flushFrames();
+});
+
+it('opens the edit dialog', async () => {
+  const fixture = TestBed.createComponent(PlayerListComponent);
+  fixture.detectChanges();
+
+  fixture.nativeElement.querySelector('button.edit').click();
+  await flushFrames();
+
+  expect(document.querySelector('.player-edit-dialog')).not.toBeNull();
+});
+```
+
+- Count open overlays with `injectOverlayManager().openOverlays().length` (inside
+  `TestBed.runInInjectionContext`).
+- The `OverlayRef` that `createOverlayOpener(...).open()` returns has `componentInstance()`,
+  `close(result)` and `afterClosed()` - enough to test what the opener does with the result.
+- A query-param overlay (`defineQueryParamOverlay`) opens from the URL: provide the router and
+  navigate with the param set, as above.
+- jsdom has no `ResizeObserver`, `IntersectionObserver`, `matchMedia` or `Element.animate`. If a
+  spec throws on one of them, stub it once in the test setup file with an inert class or function,
+  not per spec.
+
+## Before you call it done
+
+A spec for a bug fix must fail without the fix - revert it, run the spec, see it fail, restore it.
+To check the same change in the running app, read {%skill:verify-in-app%}.

package/content/skills/codex-subagent/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: codex-subagent
+description: Delegate a task to a Codex agent (gpt-5.6-luna, gpt-5.6-sol, gpt-5.6-terra, gpt-6-astra) instead of a Claude subagent - a second opinion from another model family, a review, or a cheap parallel lookup. Read before spawning a subagent when another model would answer better, and whenever the user says codex, GPT, or "second opinion".
+kind: skill
+scope: both
+---
+
+# Codex as a subagent
+
+`codex exec` runs one Codex agent to completion without a terminal. It is a subagent with its
+own context, its own tools and its own model family. It reads the repository's `AGENTS.md` by
+itself, so it starts with the same rules you have.
+
+Use it when the task gains from a model that is not Claude: a second opinion on a design, a
+review of your own diff, a bug hunt that your reading already failed, or work you want to run
+beside your own. Use it also when the Claude usage limit is close, because a Codex run does not
+draw on it - move the delegatable work there and keep the limit for the work you lead. For
+everything else, a Claude subagent stays the cheaper choice.
+
+## The call
+
+The wrapper is {%resource:codex-agent.mjs%}. It keeps the Codex trace in a log file and prints
+only the final message, so one run costs you a few hundred tokens instead of the whole trace.
+Below, `<skill-dir>` is the directory this file sits in.
+
+```bash
+node <skill-dir>/codex-agent.mjs -m gpt-5.6-terra -e medium "<prompt>"
+```
+
+Options: `-m` model, `-e` effort (`low`, `medium`, `high`, `xhigh`), `-C` working root,
+`--write`, `--resume <thread>`, `--prompt-file <file>`, `--schema <json-schema-file>`,
+`--timeout <seconds>`, `--trace`. Run it with `--help` for the full list.
+
+The run prints a footer with the model, the sandbox, the time, the output tokens, the resume
+id and the log path. Read the log only when a run fails.
+
+## Pick the model
+
+| Model           | The work it fits                                                                                                 |
+| --------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `gpt-5.6-luna`  | Fast and cheap: a lookup, a grep, a question about one file.                                                     |
+| `gpt-5.6-terra` | Balanced agentic coding. The default for real work, and the wrapper's default.                                   |
+| `gpt-5.6-sol`   | A reliable workhorse for a straight task. It costs about what `fable` costs, so ask the user before you pick it. |
+| `gpt-6-astra`   | Complex, demanding work. The most expensive of the four, so ask the user before you pick it.                     |
+
+Effort follows both the flag and the prompt. Pass `-e low` for a lookup and `-e high` for a
+hard bug. Say "keep it brief" in the prompt when you want a short answer.
+
+## Read-only by default
+
+A run without `--write` gets the `read-only` sandbox. Codex can read and run commands, but it
+cannot change a file. This is the right mode for a review, a second opinion and research.
+
+Pass `--write` only when the user asked for a code change from Codex. Two rules hold then:
+
+1. **Codex must not commit, push, or run `git add`.** Say so in the prompt. Other sessions
+   share this checkout, so a broad stage takes work that is not yours.
+2. **Name the files it may touch.** An open brief in a shared checkout is how two agents edit
+   the same file.
+
+`--resume` carries the sandbox and the working root of the thread it resumes. A thread that
+started read-only stays read-only, so start a new run when you need write access.
+
+## Run several at once
+
+The wrapper blocks until the agent is done, which takes minutes for real work. Start each run
+as a background command, and collect the answers when they arrive. Give each run its own
+question. Two agents on one question waste a model.
+
+## Write the prompt for a stranger
+
+The Codex agent shares no context with you. It sees your prompt, the repository and
+`AGENTS.md`. So:
+
+- State the task as one question, and name what "done" means.
+- Give the file paths you already know. It costs a model minutes to find what you can name.
+- Ask for the shape of the answer: a verdict, a list of findings with `file:line`, a patch in
+  a fenced block.
+- Do not paste the repository rules. It reads them itself.
+
+Pass `--schema` with a JSON Schema file when you want the answer as JSON you can parse.
+
+## Before you reach for it
+
+- `codex` must be on `PATH` and logged in. If it is not, tell the user and stop. Do not
+  install it, and do not write a token into the repository.
+- If Codex reports that the project is not trusted, ask the user to run `codex` once in the
+  repository and trust it there.
+- A Codex run is not free. Prefer it where a second model earns its cost, not for the
+  twentieth grep.

package/content/skills/codex-subagent/codex-agent.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Run one Codex agent to completion and print only its final message.
+ *
+ * `codex exec` streams its whole reasoning and command trace to stdout. That trace costs a
+ * calling agent more context than the answer is worth, so it stays in a log file here.
+ *
+ * Usage: node codex-agent.mjs [options] "<prompt>"
+ */
+
+import { spawn } from 'node:child_process';
+import { createWriteStream, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const DEFAULT_MODEL = 'gpt-5.6-terra';
+const DEFAULT_TIMEOUT_SECONDS = 900;
+
+const USAGE = `Usage: node codex-agent.mjs [options] "<prompt>"
+
+  -m, --model <id>        Model id (default ${DEFAULT_MODEL})
+  -e, --effort <level>    Reasoning effort: low | medium | high | xhigh
+  -w, --write             Let the agent edit the working tree (default: read-only)
+  -C, --cd <dir>          Working root for the agent (default: the current directory)
+      --resume <thread>   Continue an earlier thread instead of starting one
+      --prompt-file <f>   Read the prompt from a file
+      --schema <file>     JSON Schema the final message must match
+      --timeout <sec>     Give up after this many seconds (default ${DEFAULT_TIMEOUT_SECONDS})
+      --trace             Also print the command and file-change trace
+  -h, --help              Print this help`;
+
+const parseArgs = (argv) => {
+  const options = {
+    model: DEFAULT_MODEL,
+    effort: '',
+    write: false,
+    cd: process.cwd(),
+    resume: '',
+    promptFile: '',
+    schema: '',
+    timeout: DEFAULT_TIMEOUT_SECONDS,
+    trace: false,
+    prompt: '',
+  };
+
+  const rest = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const next = () => {
+      index += 1;
+      if (index >= argv.length) throw new Error(`${arg} needs a value.`);
+      return argv[index];
+    };
+
+    if (arg === '-m' || arg === '--model') options.model = next();
+    else if (arg === '-e' || arg === '--effort') options.effort = next();
+    else if (arg === '-w' || arg === '--write') options.write = true;
+    else if (arg === '-C' || arg === '--cd') options.cd = next();
+    else if (arg === '--resume') options.resume = next();
+    else if (arg === '--prompt-file') options.promptFile = next();
+    else if (arg === '--schema') options.schema = next();
+    else if (arg === '--timeout') options.timeout = Number(next());
+    else if (arg === '--trace') options.trace = true;
+    else if (arg === '-h' || arg === '--help') options.help = true;
+    else if (arg.startsWith('-') && arg !== '-') throw new Error(`Unknown option ${arg}.`);
+    else rest.push(arg);
+  }
+
+  options.prompt = options.promptFile ? readFileSync(options.promptFile, 'utf8') : rest.join(' ');
+
+  return options;
+};
+
+const readStdin = () =>
+  new Promise((resolve) => {
+    let buffer = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (buffer += chunk));
+    process.stdin.on('end', () => resolve(buffer));
+  });
+
+const buildArgs = (options, lastMessageFile) => {
+  const args = ['exec'];
+
+  if (options.resume) args.push('resume');
+
+  args.push('--json', '--skip-git-repo-check', '-o', lastMessageFile, '-m', options.model);
+
+  // `codex exec resume` carries the sandbox and the working root of the session it resumes,
+  // and rejects both flags, so only a fresh run may pass them.
+  if (!options.resume) {
+    args.push('-C', options.cd, '--sandbox', options.write ? 'workspace-write' : 'read-only');
+  }
+
+  if (options.effort) args.push('-c', `model_reasoning_effort="${options.effort}"`);
+  if (options.schema) args.push('--output-schema', options.schema);
+  if (options.resume) args.push(options.resume);
+
+  args.push('-');
+
+  return args;
+};
+
+const describeItem = (item) => {
+  if (item.type === 'command_execution') return `$ ${String(item.command ?? '').split('\n')[0]}`;
+  if (item.type === 'file_change') {
+    const changes = Array.isArray(item.changes) ? item.changes : [];
+    return `~ ${changes.map((change) => `${change.kind ?? 'edit'} ${change.path ?? ''}`).join(', ')}`;
+  }
+  if (item.type === 'error') return `! ${item.message ?? 'unknown error'}`;
+  return '';
+};
+
+const duration = (milliseconds) => {
+  const seconds = Math.round(milliseconds / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`;
+};
+
+const run = async () => {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  if (!options.prompt.trim() && !process.stdin.isTTY) options.prompt = await readStdin();
+
+  if (!options.prompt.trim()) {
+    process.stderr.write(`${USAGE}\n`);
+    return 2;
+  }
+
+  const logDir = join(tmpdir(), 'codex-agent');
+  mkdirSync(logDir, { recursive: true });
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logFile = join(logDir, `${stamp}.jsonl`);
+  const lastMessageFile = join(logDir, `${stamp}.last.md`);
+  const log = createWriteStream(logFile);
+  const started = Date.now();
+
+  const child = spawn('codex', buildArgs(options, lastMessageFile), {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: process.env,
+  });
+
+  child.stdin.end(options.prompt);
+
+  const state = { thread: '', usage: null, errors: [], trace: [], failed: false };
+
+  createInterface({ input: child.stdout }).on('line', (line) => {
+    log.write(`${line}\n`);
+
+    let event;
+
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    if (event.type === 'thread.started') state.thread = event.thread_id ?? '';
+    else if (event.type === 'turn.completed') state.usage = event.usage ?? null;
+    else if (event.type === 'turn.failed') {
+      state.failed = true;
+      state.errors.push(event.error?.message ?? 'the turn failed');
+    } else if (event.type === 'item.completed') {
+      const description = describeItem(event.item ?? {});
+      if (description) state.trace.push(description);
+      if (event.item?.type === 'error') state.errors.push(event.item.message ?? 'unknown error');
+    }
+  });
+
+  let stderrText = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => (stderrText += chunk));
+
+  const timer = setTimeout(() => child.kill('SIGKILL'), Math.max(1, options.timeout) * 1000);
+  const code = await new Promise((resolve) => child.on('close', resolve));
+
+  clearTimeout(timer);
+  log.end();
+
+  let finalMessage;
+
+  try {
+    finalMessage = readFileSync(lastMessageFile, 'utf8').trim();
+    rmSync(lastMessageFile, { force: true });
+  } catch {
+    finalMessage = '';
+  }
+
+  const failed = code !== 0 || state.failed || (!finalMessage && state.errors.length > 0);
+
+  if (options.trace && state.trace.length > 0) process.stdout.write(`${state.trace.join('\n')}\n\n`);
+  if (finalMessage) process.stdout.write(`${finalMessage}\n`);
+
+  if (failed) {
+    const reason = state.errors.join('\n') || stderrText.trim() || `codex exited with code ${code}`;
+    process.stdout.write(`\ncodex agent FAILED: ${reason}\n`);
+  }
+
+  const parts = [
+    `codex ${options.model}`,
+    options.write ? 'workspace-write' : 'read-only',
+    duration(Date.now() - started),
+  ];
+
+  if (state.usage) parts.push(`${state.usage.output_tokens ?? 0} out tok`);
+
+  process.stdout.write(`\n--- ${parts.join(' · ')}\n`);
+
+  if (state.thread) process.stdout.write(`resume: --resume ${state.thread}\n`);
+
+  process.stdout.write(`log: ${logFile}\n`);
+
+  return failed ? 1 : 0;
+};
+
+run().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(2);
+  },
+);