@lannguyensi/harness 0.7.0 → 0.8.1

package/dist/cli/apply/generate-codex-config.js

@@ -0,0 +1,149 @@
+// Phase 6 #6 — Codex config artefact generator.
+//
+// Output shape: a TOML document the operator copies into
+// `~/.codex/config.toml` (or layers via Codex's config-merge mechanism).
+// We do NOT emit a complete Codex config: only the harness-managed
+// hook stanzas the policy pack contributed. Operators keep their own
+// model/auth/sandbox config separately; harness owns hook wiring only.
+//
+// File layout under `harness.generated/codex/`:
+//   - config.toml: the harness-managed hook stanzas + a banner header
+//                  explaining the merge-into-codex contract.
+//
+// Stable-output rules (load-bearing for byte-equivalent regeneration on
+// a no-op apply):
+//   - Hook entries sorted by event then by command.
+//   - No timestamps, hostnames, or other run-specific data.
+//
+// What we deliberately do NOT do:
+//   - Try to merge into an existing `~/.codex/config.toml`. The
+//     operator owns that file; harness apply writes its own copy under
+//     harness.generated/codex/ and the operator decides how to compose.
+//     `harness apply --target <path>` with --runtime codex is rejected
+//     (see apply.ts).
+//   - Map Claude Code's permission-block to Codex's sandbox profile.
+//     Codex permission shaping is Phase 6 #6 follow-up scope; for v1
+//     the hooks alone are the enforcement.
+const HEADER = [
+    "# Generated by harness apply --runtime codex.",
+    "# DO NOT EDIT: re-run `harness apply --runtime codex` to regenerate.",
+    "#",
+    "# Merge into your ~/.codex/config.toml: copy the [[hooks.*]] entries below",
+    "# under your existing config, or include this file from your config via",
+    "# Codex's config-merge mechanism. Operator-owned settings (model, auth,",
+    "# sandbox profile) stay in your own config; harness owns hook wiring only.",
+    "#",
+    "# Wire format the harness adapter scripts expect on stdin (per",
+    '# docs/policy-packs/understanding-before-execution.md "Adapter notes /',
+    '# Codex"):',
+    "#",
+    "#   { session_id?: string, tool_name?: string, raw_input?: any, event?: string }",
+    "#",
+    "# PreToolUse blocker exit-code contract: 0 = allow, 2 = block (with reason",
+    "# on stderr). UserPromptSubmit injector emits the instruction template on",
+    "# stdout for Codex to prepend to additional_instructions.",
+    "",
+].join("\n");
+// Control-character regex covering U+0000..U+001F + U+007F. Constructed
+// programmatically so the source file stays free of literal control
+// bytes (which other tooling tends to mangle on edit).
+const CONTROL_CHAR_RE = new RegExp(`[\\u0000-\\u001f\\u007f]`, "g");
+function escapeTomlString(s) {
+    // Basic-string escapes per TOML 1.0: backslash and double-quote,
+    // plus every control char in U+0000..U+001F + U+007F. Tab/CR/LF
+    // and BS/FF use shorthand escapes; the rest fall back to \uXXXX.
+    // Hook fields are free-form `z.string().min(1)` and may carry a
+    // stray newline (multi-line description) or a regex backreference
+    // we cannot trust at face value; defence-in-depth is cheaper than
+    // a parse error downstream.
+    let out = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    out = out.replace(CONTROL_CHAR_RE, (ch) => {
+        switch (ch) {
+            case "\n":
+                return "\\n";
+            case "\r":
+                return "\\r";
+            case "\t":
+                return "\\t";
+            case "\b":
+                return "\\b";
+            case "\f":
+                return "\\f";
+            default:
+                return `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`;
+        }
+    });
+    return out;
+}
+function tomlString(s) {
+    return `"${escapeTomlString(s)}"`;
+}
+function eventKey(event) {
+    // Codex hook keys conventionally use snake_case. Map Claude-Code's
+    // CamelCase event names so the emitted TOML reads naturally to a
+    // Codex operator. Unknown events pass through unchanged so a future
+    // event the schema accepts but this generator hasn't learned about
+    // is not silently dropped.
+    switch (event) {
+        case "UserPromptSubmit":
+            return "user_prompt_submit";
+        case "PreToolUse":
+            return "pre_tool_use";
+        case "Stop":
+            return "stop";
+        default:
+            return event;
+    }
+}
+function emitHook(h) {
+    const lines = [];
+    lines.push(`[[hooks.${eventKey(h.event)}]]`);
+    lines.push(`name = ${tomlString(h.name)}`);
+    lines.push(`command = ${tomlString(h.command)}`);
+    if (h.match !== undefined) {
+        lines.push(`match = ${tomlString(h.match)}`);
+    }
+    lines.push(`timeout_ms = ${h.budget_ms}`);
+    if (h.blocking === "hard") {
+        lines.push("blocking = true");
+    }
+    else if (h.blocking === "soft") {
+        lines.push("blocking = false  # soft");
+    }
+    else {
+        lines.push("blocking = false");
+    }
+    if (h.description !== undefined && h.description.length > 0) {
+        lines.push(`description = ${tomlString(h.description)}`);
+    }
+    return lines.join("\n");
+}
+export function generateCodexConfig(manifest) {
+    const warnings = [];
+    const hooks = [...manifest.hooks].sort((a, b) => {
+        if (a.event !== b.event)
+            return a.event < b.event ? -1 : 1;
+        return a.command < b.command ? -1 : a.command > b.command ? 1 : 0;
+    });
+    // Surface a warning for hook entries that carry path_match / bash_match
+    // filters; we do not project those into the emitted TOML (the harness
+    // schema treats them as documentation that the underlying script
+    // enforces internally, identical to the Claude Code projection in
+    // generate-settings.ts). The warning makes the silent-drop visible
+    // to operators who might expect TOML-level filtering.
+    for (const h of hooks) {
+        if (h.path_match !== undefined) {
+            warnings.push(`hook ${JSON.stringify(h.name)}: path_match is not projected into Codex config (script-side filter only)`);
+        }
+        if (h.bash_match !== undefined) {
+            warnings.push(`hook ${JSON.stringify(h.name)}: bash_match is not projected into Codex config (script-side filter only)`);
+        }
+    }
+    if (hooks.length === 0) {
+        warnings.push("manifest contributes no hooks; the emitted Codex config has no [[hooks.*]] entries");
+    }
+    const body = hooks.map(emitHook).join("\n\n");
+    const content = `${HEADER}${body}${body.length > 0 ? "\n" : ""}`;
+    return { content, warnings };
+}
+//# sourceMappingURL=generate-codex-config.js.map

package/dist/cli/apply/generate-codex-config.js.map

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

package/dist/cli/apply/generate-settings.d.ts

@@ -14,14 +14,28 @@ export interface SettingsMcpServer {
     args?: string[];
     env?: Record<string, string>;
 }
+export interface SettingsPermissions {
+    allow?: string[];
+    ask?: string[];
+    deny?: string[];
+}
 export interface SettingsRoot {
     hooks: Record<string, SettingsHookGroup[]>;
     mcpServers?: Record<string, SettingsMcpServer>;
+    permissions?: SettingsPermissions;
 }
 export interface GenerateSettingsResult {
     root: SettingsRoot;
     warnings: string[];
 }
+export interface GenerateSettingsExtras {
+    /**
+     * Phase 6 #5 — pack-contributed permissions emitted into the
+     * settings.json `permissions` block. Empty buckets are dropped from
+     * the output so a no-op contribution doesn't pollute the JSON.
+     */
+    packPermissions?: SettingsPermissions;
+}
 export declare function generateSettings(manifest: Manifest): SettingsRoot;
-export declare function generateSettingsWithWarnings(manifest: Manifest): GenerateSettingsResult;
+export declare function generateSettingsWithWarnings(manifest: Manifest, extras?: GenerateSettingsExtras): GenerateSettingsResult;
 export declare function buildMcpServers(entries: McpServer[], warnings: string[]): Record<string, SettingsMcpServer>;

package/dist/cli/apply/generate-settings.js

@@ -47,7 +47,7 @@ export const DEFAULT_BUDGET_MS = 30_000;
 export function generateSettings(manifest) {
     return generateSettingsWithWarnings(manifest).root;
 }
-export function generateSettingsWithWarnings(manifest) {
+export function generateSettingsWithWarnings(manifest, extras = {}) {
     const warnings = [];
     const byEvent = new Map();
     for (const h of manifest.hooks) {
@@ -64,8 +64,23 @@ export function generateSettingsWithWarnings(manifest) {
     const mcp = buildMcpServers(manifest.tools.mcp, warnings);
     if (Object.keys(mcp).length > 0)
         out.mcpServers = mcp;
+    const permissions = compactPermissions(extras.packPermissions);
+    if (permissions)
+        out.permissions = permissions;
     return { root: out, warnings };
 }
+function compactPermissions(p) {
+    if (!p)
+        return null;
+    const out = {};
+    if (p.allow && p.allow.length > 0)
+        out.allow = [...p.allow].sort();
+    if (p.ask && p.ask.length > 0)
+        out.ask = [...p.ask].sort();
+    if (p.deny && p.deny.length > 0)
+        out.deny = [...p.deny].sort();
+    return Object.keys(out).length > 0 ? out : null;
+}
 // Translate manifest `tools.mcp[]` into Claude Code's `mcpServers` map.
 // - `enabled: false` entries are dropped (matches ARCHITECTURE §3 and the
 //   asset-locking surface in harness-lock.ts: disabled MCPs are removed

package/dist/cli/apply/generate-settings.js.map

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

package/dist/cli/apply/index.d.ts

@@ -1,2 +1,3 @@
-export { apply, DRIFT_HINT_MESSAGE, GENERATED_DIRNAME, MANIFEST_BASENAME, MEMORY_BASENAME, SETTINGS_BASENAME, type ApplyOptions, type ApplyOutcome, type ApplyResult, type FileApplyOutcome, } from "./apply.js";
+export { apply, CODEX_CONFIG_BASENAME, DRIFT_HINT_MESSAGE, GENERATED_DIRNAME, MANIFEST_BASENAME, MEMORY_BASENAME, SETTINGS_BASENAME, type ApplyOptions, type ApplyOutcome, type ApplyResult, type FileApplyOutcome, } from "./apply.js";
 export { formatNextSteps, type NextStepsContext } from "./next-steps.js";
+export { generateCodexConfig, type CodexConfigResult } from "./generate-codex-config.js";

package/dist/cli/apply/index.js

@@ -1,3 +1,4 @@
-export { apply, DRIFT_HINT_MESSAGE, GENERATED_DIRNAME, MANIFEST_BASENAME, MEMORY_BASENAME, SETTINGS_BASENAME, } from "./apply.js";
+export { apply, CODEX_CONFIG_BASENAME, DRIFT_HINT_MESSAGE, GENERATED_DIRNAME, MANIFEST_BASENAME, MEMORY_BASENAME, SETTINGS_BASENAME, } from "./apply.js";
 export { formatNextSteps } from "./next-steps.js";
+export { generateCodexConfig } from "./generate-codex-config.js";
 //# sourceMappingURL=index.js.map

package/dist/cli/apply/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/apply/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,GAKlB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAyB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/apply/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,GAKlB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAyB,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC"}

package/dist/cli/approve/understanding.d.ts

@@ -0,0 +1,39 @@
+import type { Manifest } from "../../schema/index.js";
+import { type LoaderOptions } from "../loader.js";
+export interface ApproveUnderstandingOptions extends LoaderOptions {
+    /** Explicit session id (overrides $CLAUDE_SESSION_ID). */
+    session?: string;
+    /** Override the reports directory (test injection). */
+    reportsDir?: string;
+    /** Override "now" for deterministic tests. */
+    now?: Date;
+    /** Override the actor recorded in the persisted report. */
+    approvedBy?: string;
+    /** Inject a manifest (test). */
+    manifest?: Manifest;
+    /** Override the ledger writer (test). */
+    ledgerAdd?: (sessionId: string, content: string) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+}
+export interface ApproveUnderstandingResult {
+    sessionId: string;
+    ledger: {
+        ok: boolean;
+        tag: string;
+        reason?: string;
+    };
+    persistedReport: {
+        ok: true;
+        filePath: string;
+        previousStatus: string | null;
+        approvedAt: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+}
+export declare function approveUnderstanding(opts?: ApproveUnderstandingOptions): Promise<ApproveUnderstandingResult>;

package/dist/cli/approve/understanding.js

@@ -0,0 +1,122 @@
+// Phase 6 #4 — `harness approve understanding [--session <id>]` CLI verb.
+//
+// Round-trips both approval sources for the
+// `understanding-before-execution` pack:
+//
+//   1. Writes the evidence-ledger tag `understanding-approved:${SESSION_ID}`
+//      via `grounding-mcp`'s `ledger_add` (best-effort: degraded ledger
+//      surfaces as a warning, not a hard failure).
+//   2. Flips `approvalStatus: "approved"` on the latest persisted JSON
+//      report under `.understanding-gate/reports/`. Atomic rewrite.
+//
+// Rationale for writing both: harnessed sessions consult the ledger as
+// canonical, but a solo `@lannguyensi/understanding-gate` user without
+// `grounding-mcp` wired only sees the persisted JSON. Round-tripping
+// both means switching between the two stacks doesn't lose history.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { approvedLedgerTagFor, defaultReportsDir, findLatestReportForSession, listPersistedReports, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import { addLedgerFact } from "../../runtime/ledger-add.js";
+import { EX_FAIL, HarnessExitError } from "../exit-codes.js";
+import { loadManifest } from "../loader.js";
+const DEFAULT_APPROVED_BY = "harness-approve-cli";
+function findGroundingMcp(manifest) {
+    return manifest.tools.mcp.find((m) => m.name === "grounding-mcp") ?? null;
+}
+function expandHomePath(p) {
+    if (p === "~")
+        return process.env.HOME ?? os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(process.env.HOME ?? os.homedir(), p.slice(2));
+    return p;
+}
+async function writeLedgerTag(manifest, sessionId, content, opts) {
+    if (opts.ledgerAdd)
+        return opts.ledgerAdd(sessionId, content);
+    const server = findGroundingMcp(manifest);
+    if (!server) {
+        return { ok: false, reason: "grounding-mcp not declared in manifest" };
+    }
+    const command = Array.isArray(server.command)
+        ? server.command.map(expandHomePath)
+        : server.command.trim().split(/\s+/).map(expandHomePath);
+    return addLedgerFact({
+        mcpCommand: command,
+        ...(server.env && { mcpEnv: server.env }),
+        timeoutMs: server.health?.timeout_ms ?? 5_000,
+        sessionId,
+        content,
+        source: "harness-approve-understanding",
+    });
+}
+function rewriteReportApproved(filePath, approvedAt, approvedBy) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    const previousStatus = typeof parsed["approvalStatus"] === "string" ? parsed["approvalStatus"] : null;
+    parsed["approvalStatus"] = "approved";
+    parsed["approvedAt"] = approvedAt;
+    parsed["approvedBy"] = approvedBy;
+    atomicWriteFile(filePath, `${JSON.stringify(parsed, null, 2)}\n`);
+    return { previousStatus };
+}
+export async function approveUnderstanding(opts = {}) {
+    const sessionId = opts.session ?? process.env.CLAUDE_SESSION_ID ?? "";
+    if (sessionId === "") {
+        throw new HarnessExitError("no session id available. Pass --session <id> or set $CLAUDE_SESSION_ID.", EX_FAIL);
+    }
+    // Manifest is required for the ledger write path; if it can't load,
+    // we still try to flip the persisted report so a solo user benefits.
+    let manifest = null;
+    try {
+        manifest = opts.manifest ?? loadManifest(opts).manifest;
+    }
+    catch {
+        /* swallow; ledger write becomes a degraded-ok */
+    }
+    const tag = approvedLedgerTagFor(sessionId);
+    const ledgerResult = manifest
+        ? await writeLedgerTag(manifest, sessionId, tag, opts)
+        : { ok: false, reason: "manifest unreadable; skipped ledger write" };
+    // Persisted report: flip the latest matching one.
+    const reportsDir = opts.reportsDir ?? defaultReportsDir();
+    const reports = listPersistedReports(reportsDir);
+    const latest = findLatestReportForSession(reports, sessionId);
+    let persistedReport;
+    if (!latest) {
+        persistedReport = {
+            ok: false,
+            reason: reports.length === 0
+                ? `no reports found at ${reportsDir}`
+                : `no report matched session_id=${sessionId} (${reports.length} report(s) for other sessions)`,
+        };
+    }
+    else {
+        const approvedAt = (opts.now ?? new Date()).toISOString();
+        const approvedBy = opts.approvedBy ?? DEFAULT_APPROVED_BY;
+        try {
+            const { previousStatus } = rewriteReportApproved(latest.filePath, approvedAt, approvedBy);
+            persistedReport = {
+                ok: true,
+                filePath: latest.filePath,
+                previousStatus,
+                approvedAt,
+            };
+        }
+        catch (err) {
+            persistedReport = {
+                ok: false,
+                reason: `failed to rewrite ${latest.filePath}: ${err.message}`,
+            };
+        }
+    }
+    return {
+        sessionId,
+        ledger: ledgerResult.ok
+            ? { ok: true, tag }
+            : { ok: false, tag, reason: ledgerResult.reason },
+        persistedReport,
+    };
+}
+//# sourceMappingURL=understanding.js.map

package/dist/cli/approve/understanding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"understanding.js","sourceRoot":"","sources":["../../../src/cli/approve/understanding.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,4CAA4C;AAC5C,yCAAyC;AACzC,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,mDAAmD;AACnD,uEAAuE;AACvE,oEAAoE;AACpE,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AAEpE,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAyBhE,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAElD,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,IAAI,CAAC;AAC5E,CAAC;AAED,SAAS,cAAc,CAAC,CAAS;IAC/B,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IACvD,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,QAAkB,EAClB,SAAiB,EACjB,OAAe,EACf,IAAiC;IAEjC,IAAI,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IACzE,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAC3C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QACpC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC3D,OAAO,aAAa,CAAC;QACnB,UAAU,EAAE,OAAO;QACnB,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,IAAI,KAAK;QAC7C,SAAS;QACT,OAAO;QACP,MAAM,EAAE,+BAA+B;KACxC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,qBAAqB,CAC5B,QAAgB,EAChB,UAAkB,EAClB,UAAkB;IAElB,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;IAC1D,MAAM,cAAc,GAClB,OAAO,MAAM,CAAC,gBAAgB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAM,CAAC,gBAAgB,CAAY,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7F,MAAM,CAAC,gBAAgB,CAAC,GAAG,UAAU,CAAC;IACtC,MAAM,CAAC,YAAY,CAAC,GAAG,UAAU,CAAC;IAClC,MAAM,CAAC,YAAY,CAAC,GAAG,UAAU,CAAC;IAClC,eAAe,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAoC,EAAE;IAEtC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC;IACtE,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,gBAAgB,CACxB,yEAAyE,EACzE,OAAO,CACR,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,qEAAqE;IACrE,IAAI,QAAQ,GAAoB,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;IAED,MAAM,GAAG,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,QAAQ;QAC3B,CAAC,CAAC,MAAM,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC;QACtD,CAAC,CAAC,EAAE,EAAE,EAAE,KAAc,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IAEhF,kDAAkD;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,0BAA0B,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,eAA8D,CAAC;IACnE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,eAAe,GAAG;YAChB,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,OAAO,CAAC,MAAM,KAAK,CAAC;gBAClB,CAAC,CAAC,uBAAuB,UAAU,EAAE;gBACrC,CAAC,CAAC,gCAAgC,SAAS,KAAK,OAAO,CAAC,MAAM,gCAAgC;SACnG,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,EAAE,cAAc,EAAE,GAAG,qBAAqB,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;YAC1F,eAAe,GAAG;gBAChB,EAAE,EAAE,IAAI;gBACR,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,cAAc;gBACd,UAAU;aACX,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,eAAe,GAAG;gBAChB,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,qBAAqB,MAAM,CAAC,QAAQ,KAAM,GAAa,CAAC,OAAO,EAAE;aAC1E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS;QACT,MAAM,EAAE,YAAY,CAAC,EAAE;YACrB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE;YACnB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,MAAM,EAAE;QACnD,eAAe;KAChB,CAAC;AACJ,CAAC"}

package/dist/cli/doctor/codex.d.ts

@@ -0,0 +1,34 @@
+import type { Manifest } from "../../schema/index.js";
+export type CodexCheckStatus = "ok" | "warn" | "error";
+export interface CodexCheckEntry {
+    name: string;
+    status: CodexCheckStatus;
+    message: string;
+}
+export interface CodexTargetReport {
+    target: "codex";
+    checks: CodexCheckEntry[];
+}
+export interface RunCodexCheckOptions {
+    /** Manifest directory; the codex config is at <dir>/harness.generated/codex/config.toml. */
+    manifestDir: string;
+    /** Working directory used to resolve the persisted-report path. Defaults to cwd. */
+    cwd?: string;
+    /** Override for $PATH lookup (test injection). */
+    pathEnv?: string;
+    /** Override for path existence + executable check (test injection). */
+    isExecutable?: (p: string) => boolean;
+    /** Override for the `harness` binary location (test injection). */
+    harnessBinary?: string;
+    /**
+     * Override for the `harness --version` probe. Returns null when the
+     * probe could not run (binary missing, spawn error, non-zero exit).
+     * Returns the trimmed stdout otherwise. Test injection only.
+     */
+    versionProbe?: (binary: string) => string | null;
+}
+export declare function runCodexTargetChecks(manifest: Manifest, opts: RunCodexCheckOptions): CodexTargetReport;
+export declare function countCodexDiagnostics(report: CodexTargetReport): {
+    errorCount: number;
+    warningCount: number;
+};