@cleocode/core 2026.10.18 → 2026.10.19

package/dist/goal/runtime.js

@@ -0,0 +1,289 @@
+/**
+ * CLEO Goal runtime (`@cleocode/goal`, bin `cleo-goal`, alias `ocg`): health
+ * and per-project registration.
+ *
+ * CLEO Goal is a standalone package CLEO talks to only through its bin
+ * (T13791 owner decisions). CLEO works fully without it: every function here
+ * reports absence instead of throwing.
+ *
+ * Bin contracts used here: `cleo-goal --version`, `cleo-goal status --json`
+ * and `cleo-goal install --project --json` (idempotent, project-local
+ * `.opencode/opencode.json`, never user-global). JSON shapes live in
+ * `@cleocode/contracts/goal-runtime.js`; an unknown `schemaVersion` is refused.
+ *
+ * @task T13819
+ * @task T13820
+ * @task T13821
+ * @epic T13791
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { engineError, engineSuccess } from '@cleocode/contracts/engine-result.js';
+import { ExitCode } from '@cleocode/contracts/exit-codes.js';
+import { GOAL_RUNTIME_SCHEMA_VERSION, } from '@cleocode/contracts/goal-runtime.js';
+import { findOnPath } from '@cleocode/paths';
+import { joinCommandLine } from '../tasks/command-line.js';
+// shortcut: @cleocode/cleo does not list this as an optionalDependency yet, since an unpublished one 404s on every install; add it as ">=0.8.0 <1.0.0" once the package is on npm (T13819 note).
+/** The npm package that ships the CLEO Goal runtime. */
+export const GOAL_PACKAGE = '@cleocode/goal';
+/** Bin names CLEO Goal installs, primary first (`ocg` = "open cleo goal"). */
+export const GOAL_BINS = ['cleo-goal', 'ocg'];
+/** Install command shown in remedies (the fix of every `E_GOAL_RUNTIME_MISSING`). */
+export const GOAL_INSTALL_COMMAND = `npm i -g ${GOAL_PACKAGE}@latest`;
+/** Harnesses `cleo goal install` accepts, in rollout order (owner decision). */
+export const GOAL_HARNESSES = ['opencode', 'claude', 'codex', 'hermes', 'kimi'];
+/** Run a bin; its trimmed stdout, or `null` on any failure. */
+function run(file, args, env, timeout) {
+    try {
+        // shortcut: no shell, so a Windows `.cmd` shim fails here; add shell resolution when Windows is supported.
+        return execFileSync(file, args, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout,
+            env: { ...env },
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The first semver in `text` (`cleo-goal 0.5.0` → `0.5.0`), or `null`. */
+function semver(text) {
+    return text?.match(/\d+\.\d+\.\d+[\w.+-]*/)?.[0] ?? null;
+}
+/**
+ * Whether `bin` belongs to the `@cleocode/goal` package: the nearest
+ * `package.json` above its real path is named {@link GOAL_PACKAGE}. Reads
+ * files only, never runs the bin.
+ */
+function isGoalPackageBin(bin) {
+    try {
+        let dir = dirname(realpathSync(bin));
+        for (let i = 0; i < 6; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+                return pkg.name === GOAL_PACKAGE;
+            }
+            catch {
+                // No readable package.json here; keep walking up.
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return false;
+            dir = parent;
+        }
+    }
+    catch {
+        // Dangling link or unreadable path.
+    }
+    return false;
+}
+/**
+ * Locate the CLEO Goal bin on PATH without running anything: `cleo-goal`,
+ * else `ocg` only when it belongs to {@link GOAL_PACKAGE} (`ocg` is a short
+ * name another tool may own).
+ *
+ * @param env - environment whose `PATH` is searched (default `process.env`)
+ * @returns the bin, and a foreign `ocg` that was skipped
+ */
+export function locateGoalBin(env = process.env) {
+    const primary = findOnPath('cleo-goal', { env });
+    if (primary !== null)
+        return { bin: primary, foreign: null };
+    const ocg = findOnPath('ocg', { env });
+    if (ocg === null)
+        return { bin: null, foreign: null };
+    return isGoalPackageBin(ocg) ? { bin: ocg, foreign: null } : { bin: null, foreign: ocg };
+}
+/**
+ * Resolve the CLEO Goal bin on PATH: `cleo-goal`, then an `ocg` that belongs
+ * to {@link GOAL_PACKAGE}. Synchronous and spawn-free.
+ *
+ * @param env - environment whose `PATH` is searched (default `process.env`)
+ * @returns the absolute bin path, or `null`
+ */
+export function resolveGoalBin(env = process.env) {
+    return locateGoalBin(env).bin;
+}
+/**
+ * The Stop dispatcher's tick command line for the resolved bin
+ * (`<bin> tick`, shell-quoted), or `null` when CLEO Goal is not installed.
+ *
+ * @param env - environment whose `PATH` is searched (default `process.env`)
+ * @returns the command line, or `null`
+ */
+export function goalTickCommand(env = process.env) {
+    const bin = resolveGoalBin(env);
+    return bin === null ? null : joinCommandLine([bin, 'tick']);
+}
+/**
+ * Inspect the installed CLEO Goal runtime. Local only by default: the npm
+ * lookup runs only with `checkUpdates` (no network otherwise). Never throws;
+ * an unpublished package or no network leaves `latest` null.
+ *
+ * @param env - environment for the bin lookup and spawns (default `process.env`)
+ * @param options - `checkUpdates` asks npm for the latest version
+ * @returns installed path, version, npm latest and whether an update exists
+ */
+export function inspectGoalRuntime(env = process.env, options = {}) {
+    const { bin, foreign } = locateGoalBin(env);
+    const version = semver(bin === null ? null : run(bin, ['--version'], env, 2000));
+    const npm = options.checkUpdates === true ? findOnPath('npm', { env }) : null;
+    // A 404 (not published yet) or no network both leave `latest` null.
+    const latest = semver(npm === null ? null : run(npm, ['view', GOAL_PACKAGE, 'version'], env, 8000));
+    return {
+        bin,
+        foreign,
+        version,
+        latest,
+        updateAvailable: version !== null && latest !== null && version !== latest,
+    };
+}
+/** `text` parsed as a JSON object carrying a `schemaVersion`, or `null`. */
+function parseVersioned(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `bin args` in `cwd` and read its JSON reply per the CLEO Goal exit
+ * contract: 0 = the `T` shape, 1 = {@link GoalRuntimeError}, 2 = usage error
+ * on stderr. Any `schemaVersion` other than {@link GOAL_RUNTIME_SCHEMA_VERSION}
+ * is refused.
+ */
+function runGoalJson(bin, args, cwd, env, timeout) {
+    // shortcut: no shell, so a Windows `.cmd` shim fails here; add shell resolution when Windows is supported.
+    const r = spawnSync(bin, args, { cwd, encoding: 'utf-8', timeout, env: { ...env } });
+    const command = `${bin} ${args.join(' ')}`;
+    if (r.error !== undefined && 'code' in r.error && r.error.code === 'ETIMEDOUT') {
+        // @sync-invariant none:local-only the goal bin did not answer in time; nothing is written
+        return engineError('E_GOAL_RUNTIME_TIMEOUT', `${command} did not answer within ${timeout} ms`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            fix: `Run ${command} in ${cwd} to see why it is slow`,
+        });
+    }
+    const body = parseVersioned(r.stdout ?? '');
+    if ((r.status === 0 || r.status === 1) && body === null) {
+        const out = (r.stdout ?? '').trim().slice(0, 200);
+        // @sync-invariant none:local-only the goal bin replied with non-JSON; nothing is written
+        return engineError('E_GOAL_RUNTIME_FAILED', `${command} replied with non-JSON output: ${out || '(empty)'}`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            fix: `${GOAL_INSTALL_COMMAND} (this CLEO reads ${command} as JSON, schemaVersion ${GOAL_RUNTIME_SCHEMA_VERSION})`,
+        });
+    }
+    if (r.status === 2) {
+        // @sync-invariant none:input-shape the goal bin rejected CLEO's arguments; nothing is written
+        return engineError('E_GOAL_RUNTIME_USAGE', `${command}: ${(r.stderr ?? '').trim() || 'usage error'}`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            fix: `${GOAL_INSTALL_COMMAND} (this CLEO needs a cleo-goal that accepts: ${args.join(' ')})`,
+        });
+    }
+    if ((r.status === 0 || r.status === 1) && body?.schemaVersion !== GOAL_RUNTIME_SCHEMA_VERSION) {
+        // @sync-invariant none:local-only the goal bin speaks an unknown schema; nothing is written
+        return engineError('E_GOAL_RUNTIME_SCHEMA', `${command} replied with schemaVersion ${String(body?.schemaVersion)}; this CLEO understands ${GOAL_RUNTIME_SCHEMA_VERSION}`, {
+            exitCode: ExitCode.DEPENDENCY_ERROR,
+            fix: 'Upgrade both: npm i -g @cleocode/cleo@latest @cleocode/goal@latest',
+        });
+    }
+    if (r.status === 0)
+        return engineSuccess(body);
+    const reason = r.status === 1
+        ? body.error
+        : (r.error?.message ?? `exit ${String(r.status ?? r.signal)}`);
+    // @sync-invariant none:local-only the goal bin failed on this machine; no cleo.db write
+    return engineError('E_GOAL_RUNTIME_FAILED', `${command} failed: ${reason}`, {
+        exitCode: ExitCode.GENERAL_ERROR,
+        fix: `Run ${command} in ${cwd} to see the full error`,
+    });
+}
+/** The missing-bin failure, with the install command as the fix. */
+function goalRuntimeMissing() {
+    // @sync-invariant none:local-only the goal bin is absent on this machine; nothing is written
+    return engineError('E_GOAL_RUNTIME_MISSING', `CLEO Goal is not installed: neither ${GOAL_BINS.join(' nor ')} is on PATH`, { exitCode: ExitCode.DEPENDENCY_ERROR, fix: GOAL_INSTALL_COMMAND });
+}
+/**
+ * Read the live goal through `cleo-goal status --json` in the project. A
+ * project with no goal is a success with `status: 'none'`.
+ *
+ * @param projectRoot - absolute project root (the bin's cwd)
+ * @param env - environment for the bin lookup and spawn (default `process.env`)
+ * @param timeoutMs - deadline for the bin (default 15 s; `cleo doctor` passes 2 s)
+ * @returns the status shape, or a failure (`E_GOAL_RUNTIME_MISSING`,
+ *   `E_GOAL_RUNTIME_SCHEMA`, `E_GOAL_RUNTIME_USAGE`, `E_GOAL_RUNTIME_TIMEOUT`,
+ *   `E_GOAL_RUNTIME_FAILED`)
+ */
+export function readGoalStatus(projectRoot, env = process.env, timeoutMs = 15_000) {
+    const bin = resolveGoalBin(env);
+    if (bin === null)
+        return goalRuntimeMissing();
+    return runGoalJson(bin, ['status', '--json'], projectRoot, env, timeoutMs);
+}
+/**
+ * Register CLEO Goal with one harness for this project. Writes only
+ * project-level config, never `~/.claude`, `~/.codex` or `~/.config`.
+ *
+ * - `opencode`: runs `cleo-goal install --project --json` in the project.
+ * - `claude` / `codex`: installs only the project Stop dispatcher (`cleo hook
+ *   stop`, T13796), which runs the goal tick, whatever the heavy-command mode;
+ *   no separate Stop hook and no `PreToolUse` hook.
+ * - `hermes` / `kimi`: `E_NOT_IMPLEMENTED` until the pilot (T13822).
+ *
+ * @param projectRoot - absolute project root
+ * @param harness - harness to register with
+ * @param env - environment for the bin lookup and spawn (default `process.env`)
+ * @returns the registration result, or a failure with a remedy
+ */
+export async function installGoalForHarness(projectRoot, harness, env = process.env) {
+    if (!GOAL_HARNESSES.includes(harness)) {
+        // @sync-invariant none:input-shape unknown --harness value; nothing is written
+        return engineError('E_VALIDATION', `Unknown harness '${harness}'`, {
+            exitCode: ExitCode.VALIDATION_ERROR,
+            fix: `Use --harness ${GOAL_HARNESSES.join('|')}`,
+        });
+    }
+    const h = harness;
+    if (h === 'hermes' || h === 'kimi') {
+        // @sync-invariant none:input-shape harness not supported yet; nothing is written
+        return engineError('E_NOT_IMPLEMENTED', `cleo goal install --harness ${h} is not implemented yet; harness pilots are tracked in T13822`, { exitCode: ExitCode.GENERAL_ERROR, fix: 'cleo show T13822' });
+    }
+    const bin = resolveGoalBin(env);
+    if (bin === null)
+        return goalRuntimeMissing();
+    if (h === 'opencode') {
+        const installed = runGoalJson(bin, ['install', '--project', '--json'], projectRoot, env, 60_000);
+        if (installed.success)
+            return engineSuccess({ harness: h, bin, goal: installed.data });
+        // @sync-invariant none:local-only the goal bin failed writing project config; no cleo.db write
+        return engineError('E_GOAL_INSTALL_FAILED', installed.error.message, {
+            exitCode: installed.error.exitCode ?? ExitCode.GENERAL_ERROR,
+            ...(installed.error.fix === undefined ? {} : { fix: installed.error.fix }),
+        });
+    }
+    const { loadHeavyHookDelivery } = await import('../resources/heavy-command-hook-delivery.js');
+    const sync = (await loadHeavyHookDelivery()).syncProjectStopDispatch;
+    if (sync === undefined) {
+        // @sync-invariant none:local-only the installed adapters package predates Stop-only delivery; nothing is written
+        return engineError('E_GOAL_INSTALL_FAILED', '@cleocode/adapters is too old to install the Stop dispatcher alone', {
+            exitCode: ExitCode.DEPENDENCY_ERROR,
+            fix: 'npm i -g @cleocode/cleo@latest',
+        });
+    }
+    const delivery = await sync(projectRoot, h === 'claude' ? 'claude-code' : 'codex');
+    if (delivery.status === 'failed' ||
+        delivery.status === 'needs-consent' ||
+        delivery.status === 'skipped') {
+        // @sync-invariant none:local-only the project hook file could not be written; no cleo.db write
+        return engineError('E_GOAL_INSTALL_FAILED', `Stop dispatcher not installed in ${delivery.target}: ${delivery.reason ?? delivery.status}`, {
+            exitCode: ExitCode.GENERAL_ERROR,
+            details: delivery,
+            ...(delivery.remedy === undefined ? {} : { fix: delivery.remedy }),
+        });
+    }
+    return engineSuccess({ harness: h, bin, delivery });
+}
+//# sourceMappingURL=runtime.js.map

package/dist/goal/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/goal/runtime.ts"],"names":[],"mappings":"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"}

package/dist/goal/status.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `cleo goal status` — the project's drafted goals, the CLEO tasks they serve,
+ * and the live run (T13821).
+ *
+ * The live run comes only from `cleo-goal status --json` (versioned; an
+ * unknown schema version is refused), never from the runtime's internal files.
+ * The drafted goals come from their `goal.yaml`, the contract CLEO writes.
+ * Read-only.
+ *
+ * @epic T13791
+ * @task T13821
+ */
+import type { EngineResult, GoalDraftEntry, GoalStatusReport } from '@cleocode/contracts';
+/**
+ * The drafted goals of a project, from each `.opencode/goals/<slug>/goal.yaml`.
+ *
+ * @param projectRoot - Project root.
+ * @returns One entry per goal directory holding a `goal.yaml`, by slug.
+ */
+export declare function draftedGoals(projectRoot: string): GoalDraftEntry[];
+/**
+ * The drafted goals and the live run. A missing CLEO Goal bin is a report
+ * (`runtime: 'not-installed'` with the install commands), not a failure; an
+ * unknown status schema or a failing bin is a failure.
+ *
+ * @param opts - Project root, a task to filter by, and the environment.
+ * @returns The report, or the runtime's refusal.
+ * @example
+ * ```ts
+ * const r = goalStatus({ taskId: 'T123' });
+ * if (r.success) r.data.live?.status; // the live run, when there is one
+ * ```
+ */
+export declare function goalStatus(opts?: {
+    projectRoot?: string;
+    taskId?: string;
+    env?: Readonly<Record<string, string | undefined>>;
+}): EngineResult<GoalStatusReport>;
+//# sourceMappingURL=status.d.ts.map

package/dist/goal/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/goal/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA4B1F;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,EAAE,CAoBlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC/C,GACL,YAAY,CAAC,gBAAgB,CAAC,CAiBhC"}

package/dist/goal/status.js

@@ -0,0 +1,101 @@
+/**
+ * `cleo goal status` — the project's drafted goals, the CLEO tasks they serve,
+ * and the live run (T13821).
+ *
+ * The live run comes only from `cleo-goal status --json` (versioned; an
+ * unknown schema version is refused), never from the runtime's internal files.
+ * The drafted goals come from their `goal.yaml`, the contract CLEO writes.
+ * Read-only.
+ *
+ * @epic T13791
+ * @task T13821
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { engineSuccess } from '@cleocode/contracts/engine-result.js';
+import { parse as parseYaml } from 'yaml';
+import { getProjectRoot } from '../paths.js';
+import { GOAL_INSTALL_COMMAND, readGoalStatus } from './runtime.js';
+const record = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The tasks a contract serves: `cleo.tasks` and every task a criterion `proves`. */
+function contractTasks(contract) {
+    const ids = new Set();
+    const cleo = contract.cleo;
+    if (record(cleo) && Array.isArray(cleo.tasks)) {
+        for (const t of cleo.tasks) {
+            const id = typeof t === 'string' ? t : record(t) && typeof t.id === 'string' ? t.id : '';
+            if (id)
+                ids.add(id);
+        }
+    }
+    for (const c of Array.isArray(contract.criteria) ? contract.criteria : []) {
+        if (!record(c) || !Array.isArray(c.proves))
+            continue;
+        for (const ref of c.proves)
+            if (typeof ref === 'string')
+                ids.add(ref.split('#')[0] ?? ref);
+    }
+    return [...ids].sort();
+}
+/**
+ * The drafted goals of a project, from each `.opencode/goals/<slug>/goal.yaml`.
+ *
+ * @param projectRoot - Project root.
+ * @returns One entry per goal directory holding a `goal.yaml`, by slug.
+ */
+export function draftedGoals(projectRoot) {
+    const dir = join(projectRoot, '.opencode', 'goals');
+    if (!existsSync(dir))
+        return [];
+    const entries = [];
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+        const contractPath = join(dir, d.name, 'goal.yaml');
+        if (!d.isDirectory() || !existsSync(contractPath))
+            continue;
+        const entry = { slug: d.name, title: null, tasks: [] };
+        try {
+            const contract = parseYaml(readFileSync(contractPath, 'utf8'));
+            if (record(contract)) {
+                entry.title = typeof contract.title === 'string' ? contract.title : null;
+                entry.tasks = contractTasks(contract);
+            }
+        }
+        catch (err) {
+            entry.problem = `goal.yaml does not parse: ${err.message}`;
+        }
+        entries.push(entry);
+    }
+    return entries.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+/**
+ * The drafted goals and the live run. A missing CLEO Goal bin is a report
+ * (`runtime: 'not-installed'` with the install commands), not a failure; an
+ * unknown status schema or a failing bin is a failure.
+ *
+ * @param opts - Project root, a task to filter by, and the environment.
+ * @returns The report, or the runtime's refusal.
+ * @example
+ * ```ts
+ * const r = goalStatus({ taskId: 'T123' });
+ * if (r.success) r.data.live?.status; // the live run, when there is one
+ * ```
+ */
+export function goalStatus(opts = {}) {
+    const root = opts.projectRoot ?? getProjectRoot();
+    const goals = draftedGoals(root).filter((g) => !opts.taskId || g.tasks.includes(opts.taskId));
+    const live = readGoalStatus(root, opts.env);
+    if (!live.success) {
+        if (live.error.code !== 'E_GOAL_RUNTIME_MISSING')
+            return live;
+        return engineSuccess({
+            runtime: 'not-installed',
+            install: [GOAL_INSTALL_COMMAND, 'cleo goal install --harness opencode'],
+            live: null,
+            goals,
+        });
+    }
+    // With --task, the live run counts only when it is one of that task's goals.
+    const relevant = !opts.taskId || (live.data.goal !== null && goals.some((g) => g.slug === live.data.goal));
+    return engineSuccess({ runtime: 'installed', live: relevant ? live.data : null, goals });
+}
+//# sourceMappingURL=status.js.map

package/dist/goal/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/goal/status.ts"],"names":[],"mappings":"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"}

package/dist/hooks/project-runner.d.ts

@@ -1,10 +1,15 @@
-import { type HookExecutionReceipt, type HookExecutor, type HookInvocation, type HookOutcome } from '@cleocode/contracts/project-hooks.js';
+import { type HookExecutionReceipt, type HookExecutor, type HookInvocation, type HookOutcome, type ProjectHookBinding } from '@cleocode/contracts/project-hooks.js';
 /** Execute activated definitions in source order; internal faults always allow locally. */
 export declare function executeProjectHooks(invocation: HookInvocation, id?: string, activationRoot?: string, signal?: AbortSignal): Promise<HookOutcome[]>;
 /** Contracts port for worktree and other consumers; no internal registry coupling. */
 export declare const projectHookExecutor: HookExecutor;
 /** Bind worktree inheritance to an explicitly activated source checkout. */
 export declare function createProjectHookExecutor(activationRoot: string): HookExecutor;
-/** Read only a bounded last execution record and validate its safe shape. */
-export declare function readLastProjectHookExecution(cwd: string): Promise<HookExecutionReceipt | undefined>;
+/**
+ * Read a bounded redacted execution record, validating its shape and optional binding.
+ * @param cwd - Active checkout whose private receipts are inspected.
+ * @param binding - Select a retained source/event result; omitted reads the overall latest result.
+ * @returns The matching record, or undefined when absent, malformed or mismatched.
+ */
+export declare function readLastProjectHookExecution(cwd: string, binding?: ProjectHookBinding): Promise<HookExecutionReceipt | undefined>;
 //# sourceMappingURL=project-runner.d.ts.map

package/dist/hooks/project-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-runner.d.ts","sourceRoot":"","sources":["../../src/hooks/project-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAIjB,MAAM,sCAAsC,CAAC;AAgS9C,2FAA2F;AAC3F,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,cAAc,EAC1B,EAAE,CAAC,EAAE,MAAM,EACX,cAAc,CAAC,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,EAAE,CAAC,CAmKxB;AAED,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,EAAE,YAA+C,CAAC;AAElF,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAE9E;AAED,6EAA6E;AAC7E,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAW3C"}
+{"version":3,"file":"project-runner.d.ts","sourceRoot":"","sources":["../../src/hooks/project-runner.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,WAAW,EAEhB,KAAK,kBAAkB,EAIxB,MAAM,sCAAsC,CAAC;AAwX9C,2FAA2F;AAC3F,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,cAAc,EAC1B,EAAE,CAAC,EAAE,MAAM,EACX,cAAc,CAAC,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,EAAE,CAAC,CAwKxB;AAED,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,EAAE,YAA+C,CAAC;AAElF,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAE9E;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAa3C"}

package/dist/hooks/project-runner.js

@@ -1,6 +1,10 @@
 /** Ordered project executor, separate from the best-effort internal registry (T13343). */
-import { spawn } from 'node:child_process';
-import { ProjectHookVerdictSchema, } from '@cleocode/contracts/project-hooks.js';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { lstat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { HookNativeSessionSchema, ProjectHookVerdictSchema, } from '@cleocode/contracts/project-hooks.js';
 import { discoveryEnv } from '../git/work-tree.js';
 import { atomicWrite } from '../store/atomic.js';
 import { computeHookActivation, HookInputUnavailableError, hookBindingsDigest, inspectProjectHooks, matchesProjectHook, readProjectHookRecord, readProjectHooksLocalState, readProjectHooksManifest, resolveProjectHookContext, resolveProjectHookExecutable, resolveProjectHookFile, resolveProjectHookStateFile, } from './project-state.js';
@@ -9,6 +13,78 @@ const MAX_INPUT_BYTES = 65536;
 const MAX_OUTPUT_BYTES = 65536;
 const MAX_INVOCATION_MS = 120000;
 const REACTIVATE = 'Hook inputs changed since activation; review them, then run `cleo hook sync --activate`.';
+/** Fixed-length per-binding slot; event text never becomes a filesystem path. */
+function executionRecordName(binding) {
+    const hash = createHash('sha256').update(binding.event).digest('hex');
+    return `last-execution-${binding.source}-${hash}.json`;
+}
+/**
+ * Sandbox receipt fallback (T13775): Codex workspace-write keeps `.git` read-only, so a receipt the
+ * Git-private directory refuses goes to this self-ignoring checkout directory instead.
+ */
+const FALLBACK_RECEIPTS = ['.cleo', 'hook-receipts'];
+/** Whether Git tracks a checkout path; an unanswerable probe counts as tracked. */
+function trackedByGit(context, file) {
+    return (spawnSync('git', [
+        '-C',
+        context.projectRoot,
+        'ls-files',
+        '--error-unmatch',
+        '--',
+        relative(context.projectRoot, file),
+    ], { stdio: 'ignore', timeout: 5000, env: discoveryEnv() }).status !== 1);
+}
+/**
+ * The lexical fallback path for one slot. Every component is checked with lstat before anything
+ * resolves it, so a symlinked slot or parent can never redirect a write, and a tracked file is
+ * never a destination or a source.
+ */
+async function fallbackReceiptFile(context, name) {
+    if (!/^(?:[a-z0-9-]+\.json|\.gitignore)$/.test(name))
+        // @sync-invariant none:local-only Reject unsafe machine-local hook records or executable inputs; no synced rows are written.
+        throw new Error('HOOK_STATE_PATH_INVALID');
+    let path = context.projectRoot;
+    for (const part of [...FALLBACK_RECEIPTS, name]) {
+        path = join(path, part);
+        const info = await lstat(path).catch(() => undefined);
+        if (info && (info.isSymbolicLink() || (part === name ? !info.isFile() : !info.isDirectory())))
+            // @sync-invariant none:local-only Reject unsafe machine-local hook records or executable inputs; no synced rows are written.
+            throw new Error('HOOK_STATE_SYMLINK');
+    }
+    if (trackedByGit(context, path))
+        // @sync-invariant none:local-only Reject unsafe machine-local hook records or executable inputs; no synced rows are written.
+        throw new Error('HOOK_STATE_TRACKED');
+    return path;
+}
+/** Write one receipt slot to the Git-private directory, else the sandbox-writable fallback. */
+async function writeReceipt(context, name, serialized) {
+    try {
+        await atomicWrite(await resolveProjectHookStateFile(context, name), serialized, {
+            mode: 0o600,
+        });
+        return;
+    }
+    catch {
+        // Fall through to the checkout directory a workspace-write sandbox leaves writable.
+    }
+    await atomicWrite(await fallbackReceiptFile(context, name), serialized, { mode: 0o600 });
+    const ignore = await fallbackReceiptFile(context, '.gitignore');
+    if (!existsSync(ignore))
+        await atomicWrite(ignore, '*\n');
+}
+/** Resolve and read one receipt location; any fault leaves only this candidate out. */
+async function readReceipt(locate) {
+    try {
+        const file = await locate();
+        if ((await lstat(file)).isSymbolicLink())
+            return undefined;
+        const { HookExecutionReceiptSchema } = await import('@cleocode/contracts/project-hooks.js');
+        return HookExecutionReceiptSchema.parse(JSON.parse(await readProjectHookRecord(file, MAX_OUTPUT_BYTES)));
+    }
+    catch {
+        return undefined;
+    }
+}
 function fault(invocation, code, id = 'cleo.project-hooks') {
     return {
         id,
@@ -340,18 +416,27 @@ export async function executeProjectHooks(invocation, id, activationRoot, signal
             }
             outcomes.push(await executeOne(hook, invocation, remainingMs, signal));
         }
-        // A last-result record is bounded and contains only executor-owned metadata.
+        // Last-result records are bounded and contain only executor-owned metadata.
+        // Preserve the agent binding even when the subsequent Git hook records its result.
         // A failed receipt write is visible as infrastructure fault, never a fake pass.
         try {
+            const nativeSession = invocation.nativeSession
+                ? HookNativeSessionSchema.parse(invocation.nativeSession)
+                : undefined;
             const receipt = {
                 schemaVersion: 1,
+                ...nativeSession,
                 manifestHash: approved?.manifestHash ?? '',
                 source: invocation.source,
                 event: invocation.event.slice(0, 128),
                 recordedAt: new Date().toISOString(),
                 outcomes: outcomes.map(({ message: _message, ...safe }) => safe),
             };
-            await atomicWrite(await resolveProjectHookStateFile(inspection.context, 'last-execution.json'), `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+            const serialized = `${JSON.stringify(receipt)}\n`;
+            // Each source/event keeps its own slot, so a Git write never replaces an agent receipt.
+            await writeReceipt(inspection.context, executionRecordName(invocation), serialized);
+            // Keep the existing overall-last diagnostic API compatible.
+            await writeReceipt(inspection.context, 'last-execution.json', serialized);
         }
         catch {
             outcomes.push(fault(invocation, 'HOOK_RECEIPT_WRITE_FAILED'));
@@ -368,16 +453,21 @@ export const projectHookExecutor = { execute: executeProjectHooks };
 export function createProjectHookExecutor(activationRoot) {
     return { execute: (invocation) => executeProjectHooks(invocation, undefined, activationRoot) };
 }
-/** Read only a bounded last execution record and validate its safe shape. */
-export async function readLastProjectHookExecution(cwd) {
+/**
+ * Read a bounded redacted execution record, validating its shape and optional binding.
+ * @param cwd - Active checkout whose private receipts are inspected.
+ * @param binding - Select a retained source/event result; omitted reads the overall latest result.
+ * @returns The matching record, or undefined when absent, malformed or mismatched.
+ */
+export async function readLastProjectHookExecution(cwd, binding) {
     const inspection = await inspectProjectHooks(cwd);
-    const file = await resolveProjectHookStateFile(inspection.context, 'last-execution.json');
-    try {
-        const { HookExecutionReceiptSchema } = await import('@cleocode/contracts/project-hooks.js');
-        return HookExecutionReceiptSchema.parse(JSON.parse(await readProjectHookRecord(file, MAX_OUTPUT_BYTES)));
-    }
-    catch {
-        return undefined;
-    }
+    const name = binding ? executionRecordName(binding) : 'last-execution.json';
+    // The newer of the Git-private record and the sandbox fallback (T13775) is the latest result.
+    const candidates = [
+        await readReceipt(() => resolveProjectHookStateFile(inspection.context, name)),
+        await readReceipt(() => fallbackReceiptFile(inspection.context, name)),
+    ].filter((receipt) => receipt !== undefined &&
+        (!binding || (receipt.source === binding.source && receipt.event === binding.event)));
+    return candidates.sort((a, b) => b.recordedAt.localeCompare(a.recordedAt))[0];
 }
 //# sourceMappingURL=project-runner.js.map