Writing the doctor command your users will actually run

export const LEVELS = Object.freeze(['pass', 'warn', 'fail', 'skip']);

return {
  cwd: resolve(cwd),
  checks,
  // Only `fail` blocks. A `warn` is information for a human, the Windows PATH
  // note, low memory, an unrecognised directory, and exiting non-zero on those
  // would make the command useless, so nobody would run it.
  ok: checks.every((c) => c.level !== 'fail'),
  counts: LEVELS.reduce((acc, lvl) => {
    acc[lvl] = checks.filter((c) => c.level === lvl).length;
    return acc;
  }, {}),
};

/**
 * The project data directory. Checked by writing, not by stat: a directory can
 * exist, be owned by you, and still be read-only.
 */
export function checkDataDir(cwd = process.cwd()) {
  const dir = join(cwd, '.owl');
  const probe = join(dir, `.doctor-${process.pid}-${Date.now()}.tmp`);

  try {
    mkdirSync(dir, { recursive: true });
  } catch (e) {
    return check(
      'data-dir',
      'Project data directory',
      'fail',
      `cannot create ${dir}: ${e.message}`,
      'Check the directory permissions, or run the agent outside a read-only checkout.',
    );
  }

  try {
    writeFileSync(probe, 'ok');
    rmSync(probe, { force: true });       // leave nothing behind
  } catch (e) {
    return check(
      'data-dir',
      'Project data directory',
      'fail',
      `${dir} exists but is not writable: ${e.message}`,
      'Sessions, checkpoints and the risk ledger all live here, so nothing will persist until this is fixed.',
    );
  }

  return check('data-dir', 'Project data directory', 'pass', `writable · ${dir}`);
}

export const PROVIDER_ENV = Object.freeze({
  openai: 'OPENAI_API_KEY',
  anthropic: 'ANTHROPIC_API_KEY',
  groq: 'GROQ_API_KEY',
  // ...one per provider, so the mapping is auditable in one place
});

export function checkProviders(env = process.env) {
  const present = Object.entries(PROVIDER_ENV)
    .filter(([, varName]) => {
      const v = env[varName];
      return typeof v === 'string' && v.trim().length > 0;
    })
    .map(([provider, varName]) => ({ provider, varName }));

  if (present.length) {
    const list = present.map((p) => `${p.provider} (${p.varName})`).join(', ');
    return check(
      'providers',
      'Provider credentials',
      'pass',
      `${present.length} set · ${list}`,
      'Keys are never read back or printed; only the variable names are shown.',
    );
  }

  return check(
    'providers',
    'Provider credentials',
    'fail',
    'no provider API key found in the environment',
    'Export one, e.g. `export GROQ_API_KEY=gsk_...`, or run Ollama locally which needs no key.',
  );
}

/** The tool layer's two non-negotiables: classification runs, and the red gate works. */
export function checkTooling() {
  const probes = [
    'git status',
    'ls -la',
    'npm test',
    'git commit -m "x"',
    'rm -rf /',
    'echo hi > out.txt',
  ];

  const classified = probes.filter((c) => classifyBashCommand(c).intent !== undefined);
  if (classified.length !== probes.length) {
    return check('tooling', 'Tool layer', 'fail',
      'bash command classification is not classifying',
      'Every shell tool call depends on this; without it nothing can be gated.');
  }

  // The destructive classifier is the control that keeps an agent out of trouble.
  const rmrf = classifyBashCommand('rm -rf /');
  if (!rmrf.destructive) {
    return check('tooling', 'Tool layer', 'fail',
      'destructive pattern table is not matching',
      '`rm -rf /` must classify as destructive for the red gate to work.');
  }

  return check('tooling', 'Tool layer', 'pass',
    `classified ${probes.length} probe command(s); destructive patterns armed`);
}

export function checkWorkdir(cwd = process.cwd()) {
  const dir = resolve(cwd);
  if (!existsSync(dir)) {
    return check('workdir', 'Working directory', 'fail',
      `${dir} does not exist`, 'cd to a real directory first.');
  }

  const markers = ['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', '.git', 'src'];
  const found = markers.filter((m) => existsSync(join(dir, m)));

  if (!found.length) {
    // warn, not fail: an empty scratch directory is a legitimate place to work.
    return check('workdir', 'Working directory', 'warn',
      `${dir} has no project markers`,
      'It may be empty or not a repo root. Tools still work; expect fewer useful results.');
  }

  return check('workdir', 'Working directory', 'pass',
    `${dir} · ${found.slice(0, 3).join(', ')}`);
}

export async function checkLocalModels(entries) {
  const reachable = [];
  const unreachable = [];

  for (const [name, host] of entries) {
    try {
      const ac = new AbortController();
      const timer = setTimeout(() => ac.abort(), 1200);
      const res = await fetch(host, { signal: ac.signal });
      clearTimeout(timer);
      // Any HTTP answer means something is listening and speaking HTTP.
      (res.ok || res.status ? reachable : unreachable).push(`${name} (${host})`);
    } catch {
      unreachable.push(`${name} (${host})`);
    }
  }

  if (reachable.length) return check('local-models', 'Local model servers', 'pass', `up · ${reachable.join(', ')}`);
  if (!unreachable.length) return check('local-models', 'Local model servers', 'skip', 'not probed');

  // warn: a hosted provider is a perfectly good reason for Ollama to be down.
  return check('local-models', 'Local model servers', 'warn',
    `not reachable · ${unreachable.join(', ')}`,
    'Expected if you use a hosted provider. To run fully offline, start `ollama serve`.');
}

program
  .command('doctor')
  .description('Check the runtime, data directory, provider keys and tool layer')
  .option('-d, --dir <path>', 'Project to check (default: cwd)')
  .option('--network', 'Also probe local model servers over HTTP (Ollama, LM Studio)')
  .option('--json', 'Print the report as JSON')
  .action(async (options) => {
    const { runDoctor, renderDoctor } = await import('../src/agent/doctor.js');
    const cwd = path.resolve(options.dir || process.cwd());

    const report = await runDoctor({ cwd, probeNetwork: !!options.network });

    if (options.json) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
    else console.log(renderDoctor(report));

    process.exit(report.ok ? 0 : 1);
  });

- run: node bin/owl.js doctor --json
  id: agent-preflight
  continue-on-error: false

- run: node bin/owl.js doctor --network --json > doctor.json
  if: always()
  continue-on-error: true   # upload the report either way; it is the artifact you want

$ node bin/owl.js doctor
owl doctor · /home/you/projects/myapp
✓ Node runtime, v22.23.2
✓ Working directory, /home/you/projects/myapp · package.json, .git, src
✓ Project data directory, writable · /home/you/projects/myapp/.owl
✗ Provider credentials, no provider API key found in the environment
  Export one, e.g. `export GROQ_API_KEY=gsk_...`, or run Ollama locally which needs no key.
✓ Host resources, linux 6.8.0 · 32 GB RAM (24 GB free)
✓ Tool layer, classified 6 probe command(s); destructive patterns armed
! Shell PATH. PATH separator ":" on linux
· Local model servers, not probed (--network)

5 passed · 1 warning(s) · 1 failed · 1 skipped
Not ready. Fix the failures above before starting a turn.
$ echo $?
1

$ export GROQ_API_KEY=gsk_...
$ node bin/owl.js doctor
...
6 passed · 1 warning(s) · 0 failed · 1 skipped
Ready. Try `owl ask "what is this project?"`
$ echo $?
0

import { describe, it, test } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, mkdir, rm, chmod } from 'node:fs/promises';
import { tmpdir, platform } from 'node:os';
import { join } from 'node:path';

// 1. A temp directory per test, so tests never touch the real project and never
//    collide with each other.
async function tempDir(prefix = 'owl-doctor-') {
  return mkdtemp(join(tmpdir(), prefix));
}

describe('checkDataDir', () => {
  test('passes and creates .owl on demand', async () => {
    const dir = await tempDir();
    try {
      const c = checkDataDir(dir);
      assert.equal(c.level, 'pass');
      // 2. Assert the *absence* of litter, not just the return value.
      const entries = await readdir(join(dir, '.owl'));
      assert.deepEqual(entries, []);
    } finally {
      await rm(dir, { recursive: true, force: true });
    }
  });

  test('fails when .owl exists but is a file', async () => {
    const dir = await tempDir();
    try {
      await writeFile(join(dir, '.owl'), 'not a directory');
      const c = checkDataDir(dir);
      assert.equal(c.level, 'fail');
      assert.match(c.detail, /cannot create/);
    } finally {
      await rm(dir, { recursive: true, force: true });
    }
  });

  test('fails when the directory is read-only', async (t) => {
    // 3. Skip when the precondition does not hold, rather than asserting
    //    something the platform will not deliver.
    if (platform() === 'win32') return t.skip('POSIX mode bits only');
    if (typeof process.getuid === 'function' && process.getuid() === 0) {
      return t.skip('root bypasses permission bits');
    }
    const dir = await tempDir();
    try {
      const data = join(dir, '.owl');
      await mkdir(data);
      await chmod(data, 0o500);
      assert.equal(checkDataDir(dir).level, 'fail');
    } finally {
      await chmod(join(dir, '.owl'), 0o700).catch(() => {});
      await rm(dir, { recursive: true, force: true });
    }
  });
});

// 4. Assert the exit code of the real binary, because "it printed something" and
//    "it exits correctly" are different contracts and scripts depend on the second.
it('exits 0 when healthy and 1 when a check fails', async () => {
  const dir = await tempDir();
  const ok = await run(process.execPath, [bin, 'doctor', '--json', '-d', dir], {
    env: { ...process.env, GROQ_API_KEY: 'gsk_x' },
  });
  assert.equal(JSON.parse(ok.stdout).ok, true);

  await assert.rejects(
    () => run(process.execPath, [bin, 'doctor', '--json'], {
      env: stripKeys(process.env),
    }),
    (e) => e.code === 1,
  );
});