fix(providers/codex): synchronous abort check at stream entry, plus review-pass fixes

`streamCodexEvents` now checks `abortSignal?.aborted` before entering
the `for await` so a caller abort that lands between attempt setup and
the first event surfaces immediately instead of waiting on the next
event or end-of-stream. The existing between-events check is retained.

Also from the same review pass:
- Pi shim: wrap `mkdirSync`/`writeFileSync` in try/catch so EACCES/
  ENOSPC surfaces as a classified "Pi shim setup failed at <dir>"
  instead of a raw node:fs error.
- Codex retry path: `getLog().debug` before throwing the
  model-access error from a retry-attempt `startThread`; the outer
  query_error log only runs for retryable errors.
- Docs: ai-assistants.md and configuration.md updated for Claude
  `~/.local/bin/claude` autodetect; ai-assistants.md gains a Codex
  autodetect bullet listing the five probed paths.
- Tests: `homedir()` instead of `process.env.HOME ?? '/Users/test'`
  to match the implementation; Windows autodetect probe covered;
  config-over-autodetect precedence covered.

Author: truffle-dev

packages/docs-web/src/content/docs/getting-started/ai-assistants.md

@@ -43,7 +43,7 @@ See [Anthropic's setup guide](https://code.claude.com/docs/en/setup) for the ful
 
 ### Binary path configuration (compiled binaries only)
 
-Compiled Archon binaries cannot auto-discover Claude Code at runtime. Supply the path via either:
+In compiled Archon binaries, if `claude` is not on the default install path Archon autodetects, supply the path via either:
 
 1. **Environment variable** (highest precedence):
    ```ini
@@ -55,8 +55,9 @@ Compiled Archon binaries cannot auto-discover Claude Code at runtime. Supply the
      claude:
        claudeBinaryPath: /absolute/path/to/claude
    ```
+3. **Autodetect** (zero-config fallback): Archon probes `~/.local/bin/claude` (POSIX) and `%USERPROFILE%\.local\bin\claude.exe` (Windows), matching the native curl/PowerShell installer layouts.
 
-If neither is set in a compiled binary, Archon throws with install instructions on first Claude query.
+If none of the three resolves in a compiled binary, Archon throws with install instructions on first Claude query.
 
 The Claude Agent SDK accepts either the native compiled binary or a JS `cli.js`.
 
@@ -171,6 +172,7 @@ In compiled Archon binaries, if `codex` is not on the default PATH Archon expect
        codexBinaryPath: /absolute/path/to/codex
    ```
 3. **Vendor directory** (zero-config fallback): drop the native binary at `~/.archon/vendor/codex/codex` (or `codex.exe` on Windows).
+4. **Autodetect** (zero-config fallback): if the vendor directory is empty, Archon probes the common npm-global install layouts: `~/.npm-global/bin/codex` (POSIX), `/opt/homebrew/bin/codex` (macOS Apple Silicon), `/usr/local/bin/codex` (macOS Intel and Linux), `%APPDATA%\npm\codex.cmd` and `%USERPROFILE%\.npm-global\codex.cmd` (Windows). For other npm prefixes or custom layouts, set `CODEX_BIN_PATH` or the config path explicitly.
 
 Dev mode (`bun run`) does not require any of the above — the SDK resolves `codex` via `node_modules`.
 

packages/docs-web/src/content/docs/getting-started/configuration.md

@@ -14,7 +14,7 @@ Set these in your shell or `.env` file:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `CLAUDE_BIN_PATH` | Yes (binary builds) | Absolute path to the Claude Code SDK's `cli.js`. Required in compiled Archon binaries unless `assistants.claude.claudeBinaryPath` is set. Dev mode (`bun run`) auto-resolves via `node_modules`. |
+| `CLAUDE_BIN_PATH` | No (binary builds autodetect `~/.local/bin/claude`) | Absolute path to the Claude Code binary or SDK `cli.js`. Overrides autodetection in compiled Archon binaries. Falls back to `assistants.claude.claudeBinaryPath`, then to the native-installer path. Dev mode (`bun run`) auto-resolves via `node_modules`. |
 | `CLAUDE_USE_GLOBAL_AUTH` | No | Set to `true` to use credentials from `claude /login` (default when no other Claude token is set) |
 | `CLAUDE_CODE_OAUTH_TOKEN` | No | OAuth token from `claude setup-token` (alternative to global auth) |
 | `CLAUDE_API_KEY` | No | Anthropic API key for pay-per-use (alternative to global auth) |

packages/providers/src/codex/binary-resolver.test.ts

@@ -4,6 +4,8 @@
  * Must run in its own bun test invocation because it mocks @archon/paths
  * with BUNDLED_IS_BINARY=true, which conflicts with other test files.
  */
+import { homedir } from 'node:os';
+
 import { describe, test, expect, mock, beforeEach, afterAll, spyOn } from 'bun:test';
 import { createMockLogger } from '../test/mocks/logger';
 
@@ -89,8 +91,7 @@ describe('resolveCodexBinaryPath (binary mode)', () => {
 
   test('autodetects npm global install at ~/.npm-global/bin/codex (POSIX)', async () => {
     if (process.platform === 'win32') return; // POSIX-only probe
-    const home = process.env.HOME ?? '/Users/test';
-    const expected = `${home}/.npm-global/bin/codex`;
+    const expected = `${homedir()}/.npm-global/bin/codex`;
     fileExistsSpy = spyOn(resolver, 'fileExists').mockImplementation(
       (path: string) => path === expected
     );
@@ -103,6 +104,33 @@ describe('resolveCodexBinaryPath (binary mode)', () => {
     );
   });
 
+  test('autodetects npm global install at %APPDATA%\\npm\\codex.cmd (Windows)', async () => {
+    if (process.platform !== 'win32') return; // Windows-only probe
+    const appData = process.env.APPDATA ?? 'C:\\Users\\test\\AppData\\Roaming';
+    const expected = `${appData}\\npm\\codex.cmd`;
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockImplementation(
+      (path: string) => path === expected
+    );
+
+    const result = await resolver.resolveCodexBinaryPath();
+    expect(result).toBe(expected);
+    expect(mockLogger.info).toHaveBeenCalledWith(
+      { binaryPath: expected, source: 'autodetect' },
+      'codex.binary_resolved'
+    );
+  });
+
+  test('config codexBinaryPath takes precedence over autodetect', async () => {
+    // Both the explicit config path AND a typical autodetect path are
+    // present on disk; config must win. Mirrors the env-over-config and
+    // env-over-autodetect tests above so the four-tier precedence
+    // (env → config → vendor → autodetect) is fully covered.
+    fileExistsSpy = spyOn(resolver, 'fileExists').mockReturnValue(true);
+
+    const result = await resolver.resolveCodexBinaryPath('/explicit/config/codex');
+    expect(result).toBe('/explicit/config/codex');
+  });
+
   test('autodetects homebrew install on Apple Silicon', async () => {
     if (process.platform !== 'darwin' || process.arch !== 'arm64') {
       // `/opt/homebrew/bin/codex` is only probed on darwin-arm64; on other

packages/providers/src/codex/provider.ts

@@ -197,6 +197,11 @@ async function* streamCodexEvents(
   const state: CodexStreamState = {};
   let accumulatedText = '';
 
+  if (abortSignal?.aborted) {
+    getLog().info('query_aborted_before_stream');
+    throw new Error('Query aborted');
+  }
+
   for await (const event of events) {
     if (abortSignal?.aborted) {
       getLog().info('query_aborted_between_events');
@@ -593,6 +598,7 @@ export class CodexProvider implements IAgentProvider {
           } catch (startError) {
             const err = startError as Error;
             if (isModelAccessError(err.message)) {
+              getLog().debug({ attempt, errorClass: 'model_access' }, 'query_error_pre_retry');
               throw new Error(buildModelAccessMessage(requestOptions?.model));
             }
             throw new Error(`Codex query failed: ${err.message}`);

packages/providers/src/community/pi/provider.test.ts

@@ -1,3 +1,7 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
 import { beforeEach, describe, expect, mock, test } from 'bun:test';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
 
@@ -222,6 +226,21 @@ describe('PiProvider', () => {
     await consume(new PiProvider().sendQuery('hi', '/tmp'));
     expect(process.env.PI_PACKAGE_DIR).toBeDefined();
     expect(process.env.PI_PACKAGE_DIR).toContain('archon-pi-shim');
+
+    // Stub contents are load-bearing: Pi reads `version` to populate its
+    // user-agent and `piConfig` (even when empty) to opt into the defaults
+    // path instead of erroring on missing config. Asserting on shape so a
+    // regression here surfaces in the test suite, not in a Pi runtime crash.
+    const shimDir = process.env.PI_PACKAGE_DIR;
+    expect(shimDir).toBe(join(tmpdir(), 'archon-pi-shim'));
+    const stub = JSON.parse(readFileSync(join(shimDir!, 'package.json'), 'utf8')) as {
+      name: string;
+      version: string;
+      piConfig: Record<string, unknown>;
+    };
+    expect(stub.name).toBe('archon-pi-shim');
+    expect(stub.version).toBe('0.0.0');
+    expect(stub.piConfig).toEqual({});
   });
 
   test('throws when no model is configured', async () => {

packages/providers/src/community/pi/provider.ts

@@ -52,17 +52,24 @@ function ensurePiPackageDirShim(): void {
   const shimDir = join(tmpdir(), 'archon-pi-shim');
   const shimPkgJson = join(shimDir, 'package.json');
   if (!existsSync(shimPkgJson)) {
-    mkdirSync(shimDir, { recursive: true });
     // `piConfig: {}` is explicit so Pi's defaults (`name: 'pi'`,
     // `configDir: '.pi'`) kick in — matches Pi's standalone behavior.
-    writeFileSync(
-      shimPkgJson,
-      JSON.stringify({
-        name: 'archon-pi-shim',
-        version: '0.0.0',
-        piConfig: {},
-      })
-    );
+    try {
+      mkdirSync(shimDir, { recursive: true });
+      writeFileSync(
+        shimPkgJson,
+        JSON.stringify({
+          name: 'archon-pi-shim',
+          version: '0.0.0',
+          piConfig: {},
+        })
+      );
+    } catch (error) {
+      // Surface as a classified error so the executor's catch sees a known
+      // shape instead of a raw EACCES/ENOSPC from node:fs.
+      const err = error as NodeJS.ErrnoException;
+      throw new Error(`Pi shim setup failed at ${shimDir}: ${err.message}`);
+    }
   }
   process.env.PI_PACKAGE_DIR = shimDir;
 }