Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The skill-resolver hook lane (`GBRAIN_HOOK_LANE=skill-resolver`): its own
* hook entry in Claude Code and its own hooks.json groups in Codex, each
* UserPromptSubmit plus SessionStart for the compaction reset,
* written by `gbrain setup <claude-code|codex> --skill-loading resolve`
* (src/core/setup/skill-resolver-hook.ts), and Hermes's pre_llm_call shell
* hook (`hook user-prompt --harness hermes`). It never shares output with the
* turn-rule, setup or plugin lanes: it prints only the <relevant_skills> block.
*
* Wire shapes (LANE_IO): Claude Code and Codex send the prompt, session_id
* and cwd at the top level (read whole, up to LANE_STDIN_CAP_BYTES) and take
* hookSpecificOutput.additionalContext; Hermes sends extra.user_message,
* session_id and maybe cwd beside the whole extra.conversation_history, read
* by the bounded streaming reader (hook-input.ts) over Bun's native stdin
* stream (about 4x faster than process.stdin on a multi-MB payload) so no
* history size is refused, and takes {"context": block}. Hermes has no
* compaction event and compacts in place (same session id), so the same
* pass counts extra.conversation_history and reads extra.is_first_turn: a
* first turn, or a history shorter than the last committed turn saw
* (session.ts historyShrank), starts the session's dedupe fresh. With
* per_harness.hermes.owner_sender_ids set, a turn whose extra.sender_id is
* not listed (or is empty) gets no block, as in the OpenClaw plugin.
*
* It runs the resolver in this process (never over serve's IPC), so it works
* with serve down and with no brain, and it always fails open: every path
* exits 0, and a path that cannot deliver a block prints nothing.
*
* Deadline (50 ms from lane entry): the main thread does only async I/O (the
* config, stdin, the carriers, the commit) and every synchronous step (index
* and session reads, ranking, rendering) runs in a worker thread
* (hook-worker.ts) that checks the deadline inside each stage. The worker is
* started before that I/O (by the CLI's lane fast path, before the lane
* module even loads, else at lane entry), so its start-up overlaps it; a turn
* that ends before the worker is needed terminates it. At the
* deadline the main thread prints nothing and exits the process at once,
* abandoning the worker, and commits no dedupe state: a commit starts only
* after the block was written, on the main thread, before the deadline. Once
* the turn is logged, the lane awaits the commit's session GC pass, bounded by
* LANE_GC_FILES files and by the time left before the deadline; a deadline
* that lands during it exits without changing the logged outcome.
*
* One owner per event: like the harness, plugin and turn-rule lanes, it parses
* the carriers the harness merges (Claude Code: managed settings, the
* workspace's settings.local.json and settings.json, the user settings;
* Codex: CODEX_HOME/hooks.json) and runs only when the first skill-resolver
* entry there whose home has the lane on names its own GBRAIN_HOME, so two
* wirings of different homes never deliver two blocks. (Identical commands
* are deduplicated by the harness itself.) Hermes has no carrier read yet,
* so its lane always runs under its own GBRAIN_HOME.
*
* Catalogs, each searched only once its receipt exists (none: outcome
* no_catalog, no output): <harness>-user (built by setup), for Claude Code
* claude-code-plugins (built by setup from enabled plugins), then a project
* catalog built out of the turn by a detached `gbrain skills index build` on
* first sight and merged at rank time (names only: scope project). Claude
* Code's covers the project's .claude/skills, keyed by a hash of the real
* project root; Codex's covers every existing .agents/skills from the project
* root (the nearest ancestor of cwd holding a .git entry, else cwd) down to
* cwd, root first, as Codex 0.165 loads them (codex-rs host_roots.rs), keyed
* by a hash of that real dir list and leaving out the user's own
* ~/.agents/skills. A stale catalog is rebuilt the same way, at most once a
* minute per catalog, unless skills.resolver.auto_rebuild is false or
* GBRAIN_SKILLS_NO_AUTOREBUILD=1.
*
* Turn settings: skills.resolver.top_k, min_match, top_gate, pinned (sent as
* exclude) and per_harness.<harness>.{top_k,min_match,top_gate} (config.ts
* laneTurnSettings); unset, a turn is top_k 5 with every match, the resolver's
* default top_gate (TOP_GATE_DEFAULT; 0 turns it off) and nothing excluded.
*
* Payload: the lane's own budget (skills.resolver.lane_payload_chars, default
* 4000 characters of hook JSON, Hermes's included); a block that does not fit
* is dropped whole and counted (outcome payload_dropped in the lane log).
*
* Lane log: <home>/skill-index/logs/lane-<UTC day>.jsonl (daily-log.ts, kept
* 14 days), one line per turn that got past the on/off check (outcome, error
* code, duration, catalogs; never turn text); doctor's skill_resolver check
* reads the last day of it.
*/
import { createHash } from 'node:crypto';
import { mkdirSync, unlinkSync } from 'node:fs';
import { mkdir, readFile, realpath, stat, unlink, writeFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { dirname, join } from 'node:path';
import type { Worker } from 'node:worker_threads';
import { spawn } from '../../spawn.ts';
import { claudeManagedSettingsPaths, claudeUserSettingsPath, codexHooksPath } from '../../bootstrap/host-specs.ts';
import { shellWords } from '../../setup/hook-launcher.ts';
import { isSkillResolverCommand, isSkillResolverEntry } from '../../setup/skill-resolver-lane.ts';
import { laneOwnerSenders, laneTurnSettings, type LaneTurnSettings } from './config.ts';
import { appendDailyLog, appendDailyLogSync, LANE_LOG } from './daily-log.ts';
import { HOOK_FIELD_CAP, readHookFields } from './hook-input.ts';
import { assertCatalogName, catalogFile, CLAUDE_PLUGINS_CATALOG, logsDir, resolverHome } from './paths.ts';
import { type CommitHold, commitSessionAsync, historyShrank, LANE_GC_FILES, sessionGcSettled, sessionKey, type TurnDelta } from './session.ts';
import type { TurnOutput } from './resolve.ts';
import type { LaneWorkerTurn } from './hook-worker.ts';
import { laneWorkerFailed, startLaneWorker } from './lane-worker.ts';
import { releaseLease } from './lock.ts';
export { WORKER_SRC_PATH } from './lane-worker.ts';
export const LANE_DEADLINE_MS = 50;
export const LANE_STDIN_CAP_BYTES = 256 * 1024;
export const LANE_PAYLOAD_CHARS_DEFAULT = 4000;
export const LANE_PAYLOAD_CHARS_MIN = 500;
export const LANE_PAYLOAD_CHARS_MAX = 10_000;
const CONFIG_CAP_BYTES = 1024 * 1024;
const SPAWN_INTERVAL_MS = 60_000;
/** Time kept back from the worker's own deadline for delivery and the commit. */
const COMMIT_RESERVE_MS = 10;
/** Time kept back from the deadline after the session GC pass, for the exit. */
const GC_RESERVE_MS = 5;
export type LaneHarness = 'claude-code' | 'codex' | 'hermes';
export { CLAUDE_PLUGINS_CATALOG };
export const userCatalogName = (harness: LaneHarness) => `${harness}-user`;
export const projectCatalogPrefix = (harness: LaneHarness) => `${harness}-project-`;
/** The GBRAIN_HOME a lane command pins ('' for none). */
function commandHome(command: string): string {
const words = shellWords(command) ?? [];
return (words.find(w => w.startsWith('GBRAIN_HOME='))?.slice('GBRAIN_HOME='.length) ?? '').trim();
}
async function readJsonFile(path: string, cap = CONFIG_CAP_BYTES): Promise<unknown> {
if ((await stat(path)).size > cap) throw new Error('too large');
return JSON.parse(await readFile(path, 'utf8'));
}
/**
* The GBRAIN_HOME of the skill-resolver wiring that owns this event: the
* first lane entry, in carrier order, whose home has the lane on for this
* harness. Undefined when none does (a manual run, or every wiring off).
* Async reads only; an unreadable carrier or home is skipped.
*/
export async function skillResolverOwner(harness: LaneHarness, event: 'user-prompt' | 'session-start', cwd: string, managedDir?: string): Promise<string | undefined> {
if (harness === 'hermes') return undefined;
const eventKey = event === 'user-prompt' ? 'UserPromptSubmit' : 'SessionStart';
const carriers = harness === 'codex' ? [codexHooksPath()]
: [...claudeManagedSettingsPaths(managedDir), join(cwd, '.claude', 'settings.local.json'), join(cwd, '.claude', 'settings.json'), claudeUserSettingsPath()];
for (const path of carriers) {
let doc: unknown;
try { doc = await readJsonFile(path); } catch { continue; }
const groups = (doc as { hooks?: Record<string, unknown> } | null)?.hooks?.[eventKey];
if (!Array.isArray(groups)) continue;
for (const g of groups) {
const entries = (g as { hooks?: unknown })?.hooks;
if (!Array.isArray(entries)) continue;
for (const e of entries) {
const command = (e as { command?: unknown } | null)?.command;
if (typeof command !== 'string' || !(harness === 'codex' ? isSkillResolverCommand(command) : isSkillResolverEntry(e))) continue;
const home = commandHome(command);
try {
const s = await readLaneSettings(resolverHome(home ? { GBRAIN_HOME: home } : {}), {});
if (s.enabled && s.harnesses.includes(harness)) return home;
} catch { /* a home gbrain cannot use owns nothing */ }
}
}
}
return undefined;
}
export interface LaneSettings { state: 'absent' | 'unreadable' | 'invalid' | 'ok'; enabled: boolean; harnesses: string[]; payloadChars: number; autoRebuild: boolean; section: Record<string, unknown> }
/** skills.resolver from <home>/config.json, async. absent: no file; unreadable: a file gbrain cannot read or parse. */
export async function readLaneSettings(home: string, env: NodeJS.ProcessEnv): Promise<LaneSettings> {
const base: LaneSettings = { state: 'ok', enabled: false, harnesses: [], payloadChars: LANE_PAYLOAD_CHARS_DEFAULT, autoRebuild: env.GBRAIN_SKILLS_NO_AUTOREBUILD !== '1', section: {} };
let cfg: unknown;
try { cfg = await readJsonFile(join(home, 'config.json')); } catch (e) {
return { ...base, state: (e as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'unreadable' };
}
if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return { ...base, state: 'unreadable' };
const r = (cfg as { skills?: { resolver?: Record<string, unknown> } }).skills?.resolver;
if (!r || typeof r !== 'object') return base;
const chars = r.lane_payload_chars;
const validChars = chars === undefined || (Number.isInteger(chars) && (chars as number) >= LANE_PAYLOAD_CHARS_MIN && (chars as number) <= LANE_PAYLOAD_CHARS_MAX);
return {
state: validChars ? 'ok' : 'invalid',
enabled: r.enabled === true,
harnesses: Array.isArray(r.harnesses) ? r.harnesses.filter((h): h is string => typeof h === 'string') : [],
payloadChars: validChars && chars !== undefined ? chars as number : LANE_PAYLOAD_CHARS_DEFAULT,
autoRebuild: base.autoRebuild && r.auto_rebuild !== false,
section: r,
};
}
export interface LaneLogLine { at: string; harness: string; event: string; outcome: string; code?: string; ms: number; catalogs?: string[]; dropped_chars?: number }
async function appendLaneLog(home: string, line: LaneLogLine): Promise<void> {
try {
const dir = logsDir(home);
await mkdir(dir, { recursive: true, mode: 0o700 });
await appendDailyLog(dir, LANE_LOG, `${JSON.stringify(line)}\n`);
} catch { /* logging never fails a turn */ }
}
async function readStdinBounded(stream: NodeJS.ReadableStream & { isTTY?: boolean }, cap: number): Promise<string | null> {
if (stream.isTTY) return null;
const chunks: Buffer[] = [];
let n = 0;
for await (const c of stream as AsyncIterable<Buffer | string>) {
const b = typeof c === 'string' ? Buffer.from(c) : c;
n += b.length;
if (n > cap) return null;
chunks.push(b);
}
return Buffer.concat(chunks).toString('utf8');
}
type LaneStdin = NodeJS.ReadableStream & { isTTY?: boolean };
/** One hook event's fields as the harness sent them, not yet checked. */
interface HookEvent { prompt: string; sessionId?: unknown; cwd?: unknown; source?: unknown; history?: number; firstTurn?: boolean; senderId?: string }
/** `stdin` is the injected stream, else undefined for the process's own. */
interface HarnessIo { read: (stdin: LaneStdin | undefined) => Promise<HookEvent | null>; render: (block: string) => string }
const HOOK_SPECIFIC_IO: HarnessIo = {
read: async (stdin) => {
let j: unknown;
try { j = JSON.parse(await readStdinBounded(stdin ?? process.stdin, LANE_STDIN_CAP_BYTES) ?? ''); } catch { return null; }
if (!j || typeof j !== 'object') return null;
const o = j as Record<string, unknown>;
return { prompt: typeof o.prompt === 'string' ? o.prompt : '', sessionId: o.session_id, cwd: o.cwd, source: o.source };
},
render: (block) => JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block } }),
};
/** Each lane harness's stdin and stdout shapes. */
const LANE_IO: Record<LaneHarness, HarnessIo> = {
'claude-code': HOOK_SPECIFIC_IO,
codex: HOOK_SPECIFIC_IO,
hermes: {
read: async (stdin) => {
const source = stdin ?? (process.stdin.isTTY ? process.stdin : Bun.stdin.stream());
const f = await readHookFields(source, { strings: ['session_id', 'cwd', 'extra.user_message', 'extra.sender_id'], counts: ['extra.conversation_history'], flags: ['extra.is_first_turn'] }, HOOK_FIELD_CAP);
return f && { prompt: f.strings['extra.user_message'] ?? '', sessionId: f.strings.session_id, cwd: f.strings.cwd, history: f.counts['extra.conversation_history'], firstTurn: f.flags['extra.is_first_turn'], senderId: f.strings['extra.sender_id'] ?? '' };
},
render: (block) => JSON.stringify({ context: block }),
},
};
function selfArgv(args: string[]): string[] {
const exec = process.execPath;
return /[/\\]gbrain(\.exe)?$/.test(exec) ? [exec, ...args] : [exec, process.argv[1]!, ...args];
}
function spawnDetached(argv: string[]): void {
const child = spawn(argv[0]!, argv.slice(1), { detached: true, stdio: 'ignore', env: process.env });
child.on('error', () => { /* best effort */ });
child.unref();
}
/** Start a detached build at most once a minute per catalog (stamp under logs/). */
async function scheduleBuild(home: string, catalog: string, args: string[], spawnFn: (argv: string[]) => void): Promise<boolean> {
const stamp = join(logsDir(home), `spawn-${assertCatalogName(catalog)}.stamp`);
try { if (Date.now() - (await stat(stamp)).mtimeMs < SPAWN_INTERVAL_MS) return false; } catch { /* none */ }
try {
await mkdir(logsDir(home), { recursive: true, mode: 0o700 });
await writeFile(stamp, '', { mode: 0o600 });
spawnFn(selfArgv(args));
return true;
} catch { return false; }
}
export interface LaneIo {
stdin?: NodeJS.ReadableStream & { isTTY?: boolean };
/** Resolves once the text was handed to stdout. */
write?: (s: string) => Promise<void>;
exit?: (code: number) => void;
env?: NodeJS.ProcessEnv;
cwd?: string;
deadlineMs?: number;
spawn?: (argv: string[]) => void;
managedDir?: string;
}
const writeStdout = (s: string) => new Promise<void>((resolve, reject) => { process.stdout.write(s, (e) => (e ? reject(e) : resolve())); });
interface Turn { outcome: string; code?: string; catalogs?: string[]; dropped_chars?: number }
/** Run one lane event. Always resolves 0; at the deadline it exits the process itself. */
export async function runSkillResolverLane(event: string, harness: LaneHarness, io: LaneIo = {}): Promise<number> {
const t0 = performance.now();
if (event !== 'user-prompt' && (event !== 'session-start' || harness === 'hermes')) return 0;
const env = io.env ?? process.env;
let home: string;
try { home = resolverHome(env); } catch { return 0; }
const deadlineMs = io.deadlineMs ?? (Number(env.GBRAIN_TEST_SKILL_LANE_DEADLINE_MS) || LANE_DEADLINE_MS);
const elapsed = () => performance.now() - t0;
const ctl: LaneCtl = { expired: false, worker: null, logged: false, commit: {} };
if (event === 'user-prompt') ctl.worker = startLaneWorker(env);
const line = (t: Turn): LaneLogLine => ({ at: new Date().toISOString(), harness, event, outcome: t.outcome, ...(t.code ? { code: t.code } : {}), ms: Math.round(elapsed() * 10) / 10, ...(t.catalogs ? { catalogs: t.catalogs } : {}), ...(t.dropped_chars ? { dropped_chars: t.dropped_chars } : {}) });
const log = (t: Turn) => appendLaneLog(home, line(t));
const exit = io.exit ?? ((c: number) => process.exit(c));
let timer: ReturnType<typeof setTimeout> | undefined;
const deadline = new Promise<'deadline'>((resolve) => { timer = setTimeout(() => resolve('deadline'), deadlineMs); });
const work = laneTurn(event, harness, home, env, io, ctl, elapsed, deadlineMs).catch((): Turn => ({ outcome: 'error', code: 'skill_resolver_internal' }));
const result = await Promise.race([work, deadline]);
if (result === 'deadline') {
ctl.expired = true;
void ctl.worker?.terminate();
const { tmp, lease } = ctl.commit;
if (tmp) try { unlinkSync(tmp); } catch { /* renamed or never created */ }
if (lease) releaseLease(lease);
if (ctl.logged) try {
mkdirSync(logsDir(home), { recursive: true, mode: 0o700 });
appendDailyLogSync(logsDir(home), LANE_LOG, `${JSON.stringify(line({ outcome: 'timeout', code: 'skill_resolve_timeout' }))}\n`);
} catch { /* logging never fails a turn */ }
exit(0);
return 0;
}
void ctl.worker?.terminate();
if (result.outcome !== 'off' && result.outcome !== 'yield') await log(result);
const gcDone = env.GBRAIN_TEST_SKILL_LANE_STALL === 'gc' ? new Promise<void>(() => {}) : sessionGcSettled();
if ((await Promise.race([gcDone, deadline])) === 'deadline') exit(0);
clearTimeout(timer);
return 0;
}
interface LaneCtl { expired: boolean; worker: Worker | null; logged: boolean; commit: CommitHold }
async function laneTurn(event: 'user-prompt' | 'session-start', harness: LaneHarness, home: string, env: NodeJS.ProcessEnv, io: LaneIo, ctl: LaneCtl, elapsed: () => number, deadlineMs: number): Promise<Turn> {
const settings = await readLaneSettings(home, env);
if (settings.state === 'absent') return { outcome: 'off' };
if (settings.state === 'unreadable') { ctl.logged = true; return { outcome: 'error', code: 'skill_resolver_config_unreadable' }; }
if (!settings.enabled || !settings.harnesses.includes(harness)) return { outcome: 'off' };
ctl.logged = true;
if (settings.state === 'invalid') return { outcome: 'error', code: 'skill_resolver_config_invalid' };
let turnSettings: LaneTurnSettings;
try { turnSettings = laneTurnSettings(settings.section, harness); } catch { return { outcome: 'error', code: 'skill_resolver_config_invalid' }; }
const hookEvent = await LANE_IO[harness].read(io.stdin);
if (!hookEvent) return { outcome: 'error', code: 'skill_resolve_no_input' };
const cwd = io.cwd ?? env.GBRAIN_HOOK_CWD ?? (typeof hookEvent.cwd === 'string' ? hookEvent.cwd : process.cwd());
const owner = await skillResolverOwner(harness, event, cwd, io.managedDir);
if (owner !== undefined && owner !== (env.GBRAIN_HOME ?? '').trim()) return { outcome: 'yield' };
const sessionId = typeof hookEvent.sessionId === 'string' && /^[\x21-\x7e]{1,256}$/.test(hookEvent.sessionId) ? hookEvent.sessionId : undefined;
if (event === 'session-start') {
if (hookEvent.source !== 'compact' || !sessionId) return { outcome: 'off' };
await Promise.all(['on', 'shadow'].map(scope => unlink(join(home, 'skill-index', 'sessions', `${sessionKey(scope as 'on' | 'shadow', harness, sessionId)}.json`)).catch(() => {})));
return { outcome: 'reset' };
}
const owners = laneOwnerSenders(settings.section, harness);
if (owners && !owners.includes(hookEvent.senderId ?? '')) return { outcome: 'skipped_sender' };
const reset = harness === 'hermes' && !!sessionId && (hookEvent.firstTurn === true || await historyShrank(home, sessionKey('on', harness, sessionId), hookEvent.history));
const prompt = hookEvent.prompt;
if (!prompt.trim() || /^\s*<(task-notification|teammate-message)[\s>]/.test(prompt)) return { outcome: 'empty' };
const spawnFn = io.spawn ?? spawnDetached;
const [userBuilt, pluginsBuilt, project] = await Promise.all([
isBuilt(home, userCatalogName(harness)),
harness === 'claude-code' && isBuilt(home, CLAUDE_PLUGINS_CATALOG),
harness === 'hermes' ? null : projectCatalog(harness, harness === 'claude-code' ? env.CLAUDE_PROJECT_DIR || cwd : cwd, home),
]);
const catalogs = [...(userBuilt ? [userCatalogName(harness)] : []), ...(pluginsBuilt ? [CLAUDE_PLUGINS_CATALOG] : [])];
if (project?.built) catalogs.push(project.name);
else if (project && settings.autoRebuild) await scheduleBuild(home, project.name, ['skills', 'index', 'build', '--catalog', project.name, ...project.dirs.flatMap(d => ['--dir', d]), '--scope', 'project', '--harness', harness], spawnFn);
if (catalogs.length === 0) return { outcome: 'no_catalog' };
const worker = ctl.worker;
if (!worker || laneWorkerFailed()) return { outcome: 'error', code: 'skill_resolver_internal', catalogs };
const posted = await new Promise<{ output?: TurnOutput; pending?: { key: string; delta: TurnDelta } | null; error?: { code: string } }>((resolve) => {
worker.once('message', resolve);
worker.once('error', () => resolve({ error: { code: 'skill_resolver_internal' } }));
worker.once('exit', () => resolve({ error: { code: 'skill_resolver_internal' } }));
worker.postMessage({ input: { message: prompt, harness, ...turnSettings, ...(sessionId ? { session_id: sessionId } : {}), ...(reset ? { reset_session: true } : {}) }, home, catalogs, deadlineMs: Math.max(1, deadlineMs - elapsed() - COMMIT_RESERVE_MS) } satisfies LaneWorkerTurn);
});
if (posted.error || !posted.output) return { outcome: 'error', code: posted.error?.code ?? 'skill_resolver_internal', catalogs };
const out = posted.output;
if (out.meta.index_stale && settings.autoRebuild) await scheduleStaleRebuilds(home, catalogs, spawnFn);
if (out.error) return { outcome: 'error', code: out.error.code, catalogs };
if (ctl.expired) return { outcome: 'timeout', code: 'skill_resolve_timeout', catalogs };
const outcome = out.block ? 'delivered' : out.budget_exhausted ? 'budget_exhausted' : out.no_skill ? 'no_skill' : 'empty';
if (out.block) {
const payload = LANE_IO[harness].render(out.block);
if (payload.length > settings.payloadChars) return { outcome: 'payload_dropped', catalogs, dropped_chars: payload.length };
await (io.write ?? writeStdout)(`${payload}\n`);
}
const stall = env.GBRAIN_TEST_SKILL_LANE_STALL;
if (stall === 'commit-held' || stall === 'commit-written') ctl.commit.at = (stage) => (`commit-${stage}` === stall ? new Promise(() => {}) : Promise.resolve());
if (posted.pending && !ctl.expired) {
const gc = { files: LANE_GC_FILES, until: performance.now() + deadlineMs - elapsed() - GC_RESERVE_MS };
await commitSessionAsync(home, posted.pending.key, { ...posted.pending.delta, ...(hookEvent.history !== undefined ? { history: hookEvent.history } : {}) }, ctl.commit, gc);
}
return { outcome, catalogs };
}
const isBuilt = (home: string, name: string) => stat(catalogFile(home, name, 'receipt.json')).then(() => true, () => false);
const isDir = (path: string) => stat(path).then(s => s.isDirectory(), () => false);
/**
* Codex's repo skill dirs: each existing <dir>/.agents/skills from the
* project root (the nearest ancestor of `cwd` holding a .git entry, else
* `cwd`) down to `cwd`, root first, as real paths, without the user's own
* ~/.agents/skills (the user catalog has it).
*/
async function codexProjectSkillDirs(cwd: string, home: string): Promise<string[]> {
const chain = [cwd];
for (let d = cwd; dirname(d) !== d;) chain.push(d = dirname(d));
const marked = await Promise.all(chain.map(d => stat(join(d, '.git')).then(() => true, () => false)));
const root = marked.indexOf(true);
const below = chain.slice(0, root < 0 ? 1 : root + 1).reverse();
const [user, ...found] = await Promise.all([realpath(join(home, '.agents', 'skills')).catch(() => null),
...below.map(async d => (await isDir(join(d, '.agents', 'skills')) ? realpath(join(d, '.agents', 'skills')) : null))]);
return [...new Set(found.filter((p): p is string => p !== null && p !== user))];
}
/**
* The project catalog for `root`: Claude Code's .claude/skills, named by the
* real root; Codex's .agents/skills dirs, named by their real list. Null when
* there is none (or it is the user's own dir).
*/
async function projectCatalog(harness: 'claude-code' | 'codex', root: string, home: string): Promise<{ name: string; dirs: string[]; built: boolean } | null> {
try {
const real = await realpath(root);
const user = await realpath(homedir()).catch(() => homedir());
const claudeDir = join(real, '.claude', 'skills');
const dirs = harness === 'codex' ? await codexProjectSkillDirs(real, user) : real !== user && await isDir(claudeDir) ? [claudeDir] : [];
if (dirs.length === 0) return null;
const name = `${projectCatalogPrefix(harness)}${createHash('sha256').update(harness === 'codex' ? dirs.join('\0') : real).digest('hex').slice(0, 16)}`;
return { name, dirs, built: await isBuilt(home, name) };
} catch { return null; }
}
/** Rebuild each catalog the turn marked stale (stale.stamp) from its receipt's recorded command; an adapter-owned (stdin) catalog has none and is skipped. */
async function scheduleStaleRebuilds(home: string, catalogs: string[], spawnFn: (argv: string[]) => void): Promise<void> {
for (const name of catalogs) {
try {
await stat(catalogFile(home, name, 'stale.stamp'));
const receipt = await readJsonFile(catalogFile(home, name, 'receipt.json')) as { build?: { rebuild_argv?: unknown } };
const argv = receipt.build?.rebuild_argv;
if (!Array.isArray(argv) || argv[0] !== 'gbrain' || argv.some(a => typeof a !== 'string')) continue;
await scheduleBuild(home, name, (argv as string[]).slice(1), spawnFn);
} catch { /* not stale, or no receipt */ }
}
}