codictator 0.0.0 → 0.1.2

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+import type { CdxError, Result } from "../kernel/index.ts";
+export interface CliOptions {
+    readonly argv: ReadonlyArray<string>;
+    readonly cwd: string;
+    readonly stdinText?: string;
+    readonly nodeVersion?: string;
+    readonly engineVersion?: string;
+}
+export declare function runHook(options: CliOptions): Promise<number>;
+export declare function runCommand(options: CliOptions): Promise<Result<number>>;
+export declare function runServer(options: CliOptions): Promise<number>;
+export type { CdxError };

package/dist/cli/index.js

@@ -0,0 +1,198 @@
+// SPEC §4.19: composition root. Commands, hook entry, server. May import
+// everything (§3.3); owns no §7 format.
+import { HOOK_PAYLOAD_MAX_BYTES, hookBudgetMs, runHookEvent, staticBlock, supportedHarness, } from "../features/adapters/index.js";
+import { appendEvent } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { err, NodeEnv, NodeFs, NodeGit, NodeNet, NodeProc, ok, readStdinText, SystemClock, } from "../kernel/index.js";
+import { COMMANDS, USAGE } from "./commands.js";
+import { loadEvalEnforcers } from "./evaluate.js";
+import { startStdioServer } from "./serve-server.js";
+import { MIN_NODE_MAJOR, nodeMajor, nodeTooOldMessage, printHuman, usageError, } from "./shared.js";
+// SPEC §4.19.3 steps 3 and 5: the verdict line lands in the resolved repo's
+// event log. An append failure is the engine's CDX-E801 path, never a throw
+// here, so writer faults stay fail-closed without crashing the hook.
+// SPEC §4.1.1: the Fs is already confined to root, so the logical root is
+// "." and every audit path stays repo-relative.
+async function appendLine(root, event, ports) {
+    const fsMade = await NodeFs.create({ root });
+    if (!fsMade.ok) {
+        return fsMade;
+    }
+    return appendEvent({
+        fs: fsMade.value,
+        proc: ports.proc,
+        net: ports.net,
+        clock: ports.clock,
+        git: new NodeGit(ports.proc, root),
+        env: ports.env,
+    }, ".", event);
+}
+// The old-node rejection: a static block when the harness has one,
+// stderr plus exit 6 otherwise.
+function oldNodeExit(harness, version) {
+    const staticReply = harness === ""
+        ? undefined
+        : staticBlock(harness, "CDX-E002", nodeTooOldMessage(version));
+    if (staticReply === undefined) {
+        process.stderr.write(`${nodeTooOldMessage(version)}\n`);
+        return 6;
+    }
+    return emitReply(staticReply.stdout, staticReply.stderr, staticReply.exitCode);
+}
+// A failed stdin wait fails closed: a static block when the harness has
+// one, stderr plus exit 1 otherwise.
+function blockedStdinExit(harness, code, message) {
+    const blocked = staticBlock(harness, code, message);
+    if (blocked === undefined) {
+        process.stderr.write(`${code} ${message}\n`);
+        return 1;
+    }
+    return emitReply(blocked.stdout, blocked.stderr, blocked.exitCode);
+}
+// The hook invocation resolves its stdin first: an idle pipe fails closed
+// with CDX-E902 instead of hanging past the time limit (§4.5.5), while an
+// unknown harness never had a payload and answers without I/O.
+async function invokeHookEvent(harness, event, stdinText, cwd, ports, append, engineVersion) {
+    let text = stdinText;
+    if (text === undefined && supportedHarness(harness)) {
+        const stdin = await readStdinText(HOOK_PAYLOAD_MAX_BYTES, hookBudgetMs(harness));
+        if (!stdin.ok) {
+            return blockedStdinExit(harness, stdin.error.code, stdin.error.message);
+        }
+        text = stdin.value;
+    }
+    const reply = await runHookEvent({
+        harness,
+        event,
+        stdinText: text ?? "",
+        cwd,
+        ports,
+        append,
+        engineVersion,
+        // SPEC §4.19.3 step 5: the hook evaluates the same pack enforcers
+        // the verify path loads (core plus the configured builtin packs),
+        // resolved against the runtime's root-confined ports.
+        loadEnforcers: loadEvalEnforcers,
+    });
+    return emitReply(reply.stdout, reply.stderr, reply.exitCode);
+}
+function emitReply(stdout, stderr, exitCode) {
+    if (stdout !== "") {
+        process.stdout.write(stdout);
+    }
+    if (stderr !== "") {
+        process.stderr.write(stderr);
+    }
+    return exitCode;
+}
+// SPEC §4.19.3: hook runtime entry; an uncaught error becomes a block. The
+// reply goes to stdout verbatim (the harness parses it; golden EC-14 pins
+// stdout exactly), diagnostics to stderr, and the harness exit code returns.
+// Nothing reads the disk before the runtime resolves the repo root, so
+// unknown harnesses and empty payloads answer without I/O.
+export async function runHook(options) {
+    const harness = options.argv[1] ?? "";
+    const event = options.argv[2] ?? "";
+    const version = options.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        return oldNodeExit(harness, version);
+    }
+    const ports = {
+        proc: new NodeProc(),
+        net: new NodeNet(),
+        clock: new SystemClock(),
+        env: new NodeEnv(),
+    };
+    const append = (root, line) => appendLine(root, line, ports);
+    return invokeHookEvent(harness, event, options.stdinText, options.cwd, ports, append, options.engineVersion ?? ENGINE_VERSION);
+}
+function scanGlobals(argv, cwd) {
+    let json = false;
+    let quiet = false;
+    let help = false;
+    let override;
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (token === "--json") {
+            json = true;
+        }
+        else if (token === "--quiet") {
+            quiet = true;
+        }
+        else if (token === "--help" || token === "-h") {
+            help = true;
+        }
+        else if (token === "--cwd") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                return undefined;
+            }
+            override = next;
+            index += 1;
+        }
+        else if (token.startsWith("--cwd=")) {
+            override = token.slice("--cwd=".length);
+        }
+        else {
+            rest.push(token);
+        }
+    }
+    return { json, quiet, cwd: override ?? cwd, help, rest };
+}
+// SPEC §4.19 + §8.2: the command entry. The node floor fails as CDX-E002
+// (exit 6); unknown commands or flags are usage errors (exit 2, no code).
+async function runCommandImpl(options) {
+    const version = options.nodeVersion ?? process.version;
+    if (nodeMajor(version) < MIN_NODE_MAJOR) {
+        process.stderr.write(`${nodeTooOldMessage(version)}\n`);
+        return err({
+            code: "CDX-E002",
+            message: nodeTooOldMessage(version),
+            remediation: "Install a newer Node, then retry the tool call.",
+        });
+    }
+    const globals = scanGlobals(options.argv, options.cwd);
+    if (globals === undefined) {
+        return usageError(USAGE);
+    }
+    if (globals.help) {
+        printHuman(USAGE, globals.quiet);
+        return ok(0);
+    }
+    if (globals.rest.length === 0) {
+        return usageError(USAGE);
+    }
+    const [command, ...args] = globals.rest;
+    const handler = COMMANDS[command];
+    if (handler === undefined) {
+        return usageError(`${USAGE}\nunknown command "${command}"`);
+    }
+    return handler({
+        args,
+        json: globals.json,
+        quiet: globals.quiet,
+        cwd: globals.cwd,
+        nodeVersion: options.nodeVersion,
+        stdinText: undefined,
+        engineVersion: options.engineVersion ?? ENGINE_VERSION,
+    });
+}
+// SPEC §4.19: command dispatch (init, regen, verify, task, review, ...).
+// The hook word routes back through the hook runtime; every other word
+// goes through the command table in commands.ts. The hook reply is already emitted
+// by runHook, so its harness exit code passes through as the value.
+export function runCommand(options) {
+    if (options.argv[0] === "hook") {
+        return runHook(options).then((exitCode) => ({ ok: true, value: exitCode }));
+    }
+    return runCommandImpl(options);
+}
+// SPEC §7.15 + §4.19.5: stdio server entry for the vscode extension. The
+// loop serves one NDJSON session on this process's stdio; commands run
+// through the same table with per-call output capture (see serve-run.ts),
+// so frames stay the only stdout bytes. A closed stdin (no piped client)
+// exits 0 without serving.
+export function runServer(options) {
+    return startStdioServer(options, runCommand);
+}

package/dist/cli/init-plan.d.ts

@@ -0,0 +1,23 @@
+import type { Result } from "../kernel/index.ts";
+import { guardrailPlan } from "./plan.ts";
+import type { CommandRequest } from "./shared.ts";
+export interface InitFlags {
+    readonly harnesses: Array<string>;
+    readonly profile: string;
+    readonly packs: Array<string>;
+    readonly tools: Array<{
+        role: string;
+        command: string;
+        pin: string;
+    }>;
+    readonly repair: boolean;
+}
+export declare function ensureBaseline(root: string, req: CommandRequest): Promise<Result<boolean>>;
+export declare function defaultHarnesses(flags: InitFlags): Array<string>;
+export declare function reportExisting(req: CommandRequest, root: string): Result<number>;
+export declare function checkFreshConfig(root: string, req: CommandRequest): Promise<Result<number>>;
+export declare function emitInitResult(req: CommandRequest, root: string, written: ReadonlyArray<{
+    path: string;
+}>, baselineWritten: boolean): Result<number>;
+export declare function initPreamble(req: CommandRequest): Promise<string | Result<number>>;
+export declare function buildGuardrailPlan(root: string, flags: InitFlags, planned: ReadonlyArray<string>, engineVersion?: string): Promise<ReturnType<typeof guardrailPlan>>;

package/dist/cli/init-plan.js

@@ -0,0 +1,135 @@
+// SPEC §4.13.1 + §4.14.1: init execution. Split from the init command
+// (init.ts) by responsibility: flag parsing stays on the command, module
+// detection, baseline, guards and plan assembly live here.
+import { CODICTATOR_MODULES } from "../features/arch/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { captureBaseline } from "../features/remediation/index.js";
+import { ok, parseJson, resolveRepoRoot, stableStringify, } from "../kernel/index.js";
+import { buildHelperTool, guardrailPlan } from "./plan.js";
+import { checkHuman, commandEnv, fail, loadRepoConfig, printHuman, printJson, readStateText, writeStateText, } from "./shared.js";
+// SPEC §4.19.2: a helper tool proposal names the helper role, the binary
+// and the exact pin from the human's registry lookup: role=command@pin.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// SPEC §4.11.2 + §3.3: on the Codictator repo itself, init proposes the
+// canonical module map the arch guard dogfoods (profiles.ts), rewritten to
+// repo-relative paths. Any other repo gets no modules; the human adds them.
+async function detectCodictatorModules(root) {
+    const text = await readStateText(root, "packages/codictator/package.json");
+    if (text === undefined) {
+        return undefined;
+    }
+    const parsed = parseJson(text);
+    if (!parsed.ok || !isRecord(parsed.value)) {
+        return undefined;
+    }
+    const nameKey = "name";
+    if (parsed.value[nameKey] !== "codictator") {
+        return undefined;
+    }
+    return CODICTATOR_MODULES.map((mod) => ({
+        name: mod.name,
+        path: `packages/codictator/${mod.path}`,
+        ...(mod.kind === undefined ? {} : { kind: mod.kind }),
+        ...(mod.entry === undefined ? {} : { entry: mod.entry }),
+        dependsOn: [...mod.dependsOn],
+    }));
+}
+// SPEC §4.13.1 step 3: init captures the baseline. On a greenfield repo the
+// first verify has no findings, so the capture is the empty ratchet. An
+// existing baseline (repair, L3 tighten, capture) is never overwritten.
+export async function ensureBaseline(root, req) {
+    const existing = await readStateText(root, ".codictator/baseline.json");
+    if (existing !== undefined) {
+        return ok(false);
+    }
+    const captured = await captureBaseline(root, []);
+    if (!captured.ok) {
+        return fail("CDX-E903", captured.error.message, captured.error.remediation, req.json);
+    }
+    const saved = await writeStateText(root, ".codictator/baseline.json", `${stableStringify(captured.value)}\n`);
+    if (!saved.ok) {
+        return fail("CDX-E903", saved.error.message, saved.error.remediation, req.json);
+    }
+    return ok(true);
+}
+// SPEC §4.19.2: init harnesses default to every known adapter id when no
+// --harness flag is given; unknown ids fail as CDX-E301 via config
+// validation, never silently.
+const DEFAULT_HARNESSES = [
+    "muse-code",
+    "universal",
+    "claude-code",
+    "copilot",
+    "codex-cli",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+];
+export function defaultHarnesses(flags) {
+    return flags.harnesses.length > 0 ? flags.harnesses : [...DEFAULT_HARNESSES];
+}
+export function reportExisting(req, root) {
+    printHuman("already a Codictator repo; rerun with --repair to regenerate", req.quiet);
+    if (req.json) {
+        printJson({ initialized: false, reason: "exists", root });
+    }
+    return ok(0);
+}
+export async function checkFreshConfig(root, req) {
+    const fresh = await loadRepoConfig(root, undefined, req.engineVersion ?? ENGINE_VERSION);
+    if (!fresh.ok) {
+        return fail("CDX-E901", fresh.error.message, "Rerun codictator init --repair; report the mismatch.", req.json, fresh.error.detail);
+    }
+    return ok(0);
+}
+export function emitInitResult(req, root, written, baselineWritten) {
+    const files = baselineWritten === false
+        ? written
+        : [...written, { path: ".codictator/baseline.json" }];
+    if (req.json) {
+        printJson({
+            initialized: true,
+            root,
+            files: files.map((entry) => entry.path),
+        });
+    }
+    else {
+        for (const entry of files) {
+            printHuman(`wrote ${entry.path}`, req.quiet);
+        }
+        printHuman("init: run npm ci, then codictator install-hooks", req.quiet);
+    }
+    return ok(0);
+}
+export async function initPreamble(req) {
+    const human = checkHuman(commandEnv(), []);
+    if (!human.ok) {
+        return fail("CDX-E107", human.error.message, human.error.remediation, req.json);
+    }
+    const root = await resolveRepoRoot(req.cwd);
+    if (!root.ok) {
+        return fail("CDX-E703", root.error.message, root.error.remediation, req.json);
+    }
+    return root.value;
+}
+// The plan assembly handleInit writes: read-only inputs in, GuardrailPlan
+// out. Writing stays on the command so the plan builder never touches
+// the disk.
+export async function buildGuardrailPlan(root, flags, planned, engineVersion = ENGINE_VERSION) {
+    const agents = await readStateText(root, "AGENTS.md");
+    const repoName = root.replaceAll("\\", "/").split("/").pop() ?? "repo";
+    const modules = await detectCodictatorModules(root);
+    const architecture = modules === undefined
+        ? undefined
+        : {
+            ...(flags.profile === "" ? {} : { profile: flags.profile }),
+            modules,
+        };
+    return guardrailPlan(planned, flags.profile, repoName, agents, {
+        packs: flags.packs.map((id) => ({ id, version: engineVersion })),
+        tools: flags.tools.map((tool) => buildHelperTool(tool)),
+        ...(architecture === undefined ? {} : { architecture }),
+    }, engineVersion);
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function handleInit(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/init.js

@@ -0,0 +1,122 @@
+// SPEC §4.19.2 + §4.13.1: human-only adoption. Writes config, steering
+// block, manifest, CI workflow, hooks and launcher; existing config needs
+// --repair, unknown harnesses fail as CDX-E301 via validation.
+import { parseArgs } from "node:util";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { isBuiltinPackId } from "../features/packs/index.js";
+import { buildGuardrailPlan, checkFreshConfig, defaultHarnesses, emitInitResult, ensureBaseline, initPreamble, reportExisting, } from "./init-plan.js";
+import { KNOWN_HELPER_ROLES, writePlan } from "./plan.js";
+import { fail, readStateText, usageError } from "./shared.js";
+const KNOWN_PROFILES = new Set([
+    "app",
+    "library",
+    "cli",
+    "service",
+]);
+function parseToolSpec(spec) {
+    const eq = spec.indexOf("=");
+    if (eq < 0) {
+        return undefined;
+    }
+    const role = spec.slice(0, eq).trim();
+    const rest = spec.slice(eq + 1);
+    const at = rest.lastIndexOf("@");
+    if (at < 0) {
+        return undefined;
+    }
+    const command = rest.slice(0, at).trim();
+    const pin = rest.slice(at + 1).trim();
+    if (!KNOWN_HELPER_ROLES.has(role) || command === "" || pin === "") {
+        return undefined;
+    }
+    return { role, command, pin };
+}
+function narrowInitProfile(profile) {
+    if (profile !== undefined && profile !== "" && !KNOWN_PROFILES.has(profile)) {
+        return undefined;
+    }
+    return profile ?? "";
+}
+function narrowInitPacks(packs) {
+    const ids = [...(packs ?? [])];
+    if (ids.some((id) => !isBuiltinPackId(id))) {
+        return undefined;
+    }
+    return ids;
+}
+function narrowInitTools(specs) {
+    const tools = [];
+    for (const spec of specs ?? []) {
+        const tool = parseToolSpec(spec);
+        if (tool === undefined) {
+            return undefined;
+        }
+        tools.push(tool);
+    }
+    return tools;
+}
+function parseInitFlags(args) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {
+                harness: { type: "string", multiple: true, default: [] },
+                profile: { type: "string", default: "" },
+                pack: { type: "string", multiple: true, default: [] },
+                tool: { type: "string", multiple: true, default: [] },
+                repair: { type: "boolean", default: false },
+            },
+            allowPositionals: true,
+        });
+        if (parsed.positionals.length > 0) {
+            return undefined;
+        }
+        const profile = narrowInitProfile(parsed.values.profile);
+        const packs = narrowInitPacks(parsed.values.pack);
+        const tools = narrowInitTools(parsed.values.tool);
+        if (profile === undefined || packs === undefined || tools === undefined) {
+            return undefined;
+        }
+        return {
+            harnesses: [...(parsed.values.harness ?? [])],
+            profile,
+            packs,
+            tools,
+            repair: parsed.values.repair ?? false,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+const INIT_USAGE = "usage: codictator init [--harness <id> ...] [--profile <app|library|cli|service>] [--pack <id> ...] [--tool <role>=<command>@<pin> ...] [--repair]";
+export async function handleInit(req) {
+    const flags = parseInitFlags(req.args);
+    if (flags === undefined) {
+        return usageError(INIT_USAGE);
+    }
+    const root = await initPreamble(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const planned = defaultHarnesses(flags);
+    const engineVersion = req.engineVersion ?? ENGINE_VERSION;
+    const existing = await readStateText(root, ".codictator/config.json");
+    if (existing !== undefined && !flags.repair) {
+        return reportExisting(req, root);
+    }
+    const plan = await buildGuardrailPlan(root, flags, planned, engineVersion);
+    const wrote = await writePlan(root, plan, engineVersion);
+    if (!wrote.ok) {
+        return fail("CDX-E903", wrote.error.message, wrote.error.remediation, req.json);
+    }
+    const fresh = await checkFreshConfig(root, req);
+    if (!fresh.ok) {
+        return fresh;
+    }
+    const baseline = await ensureBaseline(root, req);
+    if (!baseline.ok) {
+        return fail(baseline.error.code, baseline.error.message, baseline.error.remediation, req.json);
+    }
+    return emitInitResult(req, root, wrote.value, baseline.value);
+}

package/dist/cli/inspect-status.d.ts

@@ -0,0 +1,8 @@
+import type { EventLogLine } from "../features/audit/index.ts";
+import type { Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function readLogEvents(root: string): Promise<{
+    events: ReadonlyArray<EventLogLine>;
+    corrupt: number;
+} | undefined>;
+export declare function handleStatus(req: CommandRequest): Promise<Result<number>>;

package/dist/cli/inspect-status.js

@@ -0,0 +1,164 @@
+// SPEC §4.18.3: the status screen. Split from the verify command
+// (inspect.ts) by responsibility: read-only screen here, trigger evaluation
+// there. The event log, config and ports stay caller-owned.
+import { parseArgs } from "node:util";
+import { CLAUDE_CODE_CAPABILITIES, CODEX_CAPABILITIES, COPILOT_CAPABILITIES, MUSE_CAPABILITIES, OPENCODE_CAPABILITIES, UNIVERSAL_CAPABILITIES, } from "../features/adapters/index.js";
+import { buildStatusJson, buildStatusText, readEvents, summarizeTokenSaverEvidence, tokenSaverHelper, } from "../features/audit/index.js";
+import { ENGINE_VERSION } from "../features/config/index.js";
+import { REQUIRED_HELPERS_DEFAULT } from "../features/steering/index.js";
+import { ok } from "../kernel/index.js";
+import { fail, loadRepoConfig, needRoot, portsFor, printHuman, printJson, usageError, } from "./shared.js";
+// SPEC §4.18.1: the repo's event lines through caller-owned ports against
+// the logical root "." (the Fs port takes repo-relative paths only).
+export async function readLogEvents(root) {
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return undefined;
+    }
+    const read = await readEvents(ports.value, ".");
+    return read.ok ? read.value : undefined;
+}
+function harnessStates(observed) {
+    const declarations = [
+        MUSE_CAPABILITIES,
+        UNIVERSAL_CAPABILITIES,
+        CLAUDE_CODE_CAPABILITIES,
+        COPILOT_CAPABILITIES,
+        CODEX_CAPABILITIES,
+        OPENCODE_CAPABILITIES,
+    ];
+    return declarations.map((candidate) => ({
+        harness: candidate.harness,
+        state: observed.has(candidate.harness)
+            ? "active"
+            : "unverified",
+        layers: `L0:${candidate.layers.L0} L1:${candidate.layers.L1} L2:${candidate.layers.L2} L3:${candidate.layers.L3} L4:${candidate.layers.L4} L5:${candidate.layers.L5}`,
+    }));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// SPEC §4.6.6: the required helper roles come from config.steering, falling
+// back to the pack default; a role is present when config.tools declares it
+// (by role or id) at an exact pin.
+function requiredRoles(steering) {
+    if (isRecord(steering)) {
+        const key = "requiredHelpers";
+        const found = steering[key];
+        if (Array.isArray(found) &&
+            found.every((entry) => typeof entry === "string")) {
+            return [...found];
+        }
+    }
+    return [...REQUIRED_HELPERS_DEFAULT];
+}
+function matchHelper(entry, role) {
+    if (!isRecord(entry)) {
+        return undefined;
+    }
+    const idKey = "id";
+    const roleKey = "role";
+    const versionKey = "version";
+    const pinKey = "pin";
+    const id = entry[idKey];
+    if (typeof id !== "string" || id === "") {
+        return undefined;
+    }
+    if (entry[roleKey] !== role && id !== role) {
+        return undefined;
+    }
+    const version = entry[versionKey];
+    const pin = isRecord(version) ? version[pinKey] : undefined;
+    if (typeof pin === "string" && pin !== "") {
+        return { role, present: true, detail: `${id} ${pin}` };
+    }
+    return { role, present: false };
+}
+function helperDetail(tools, role) {
+    if (!Array.isArray(tools)) {
+        return { role, present: false };
+    }
+    for (const entry of tools) {
+        const matched = matchHelper(entry, role);
+        if (matched !== undefined) {
+            return matched;
+        }
+    }
+    return { role, present: false };
+}
+async function collectStatusParts(root, engineVersion) {
+    const log = await readLogEvents(root);
+    const events = log?.events ?? [];
+    const observed = new Set(events.map((event) => event.harness ?? "").filter((h) => h !== ""));
+    const packs = {};
+    let helpers = [];
+    const configured = await loadRepoConfig(root, undefined, engineVersion);
+    if (configured.ok) {
+        for (const pack of configured.value.effective.config.packs) {
+            packs[pack.id] =
+                typeof pack.version === "string" ? pack.version : "unpinned";
+        }
+        helpers = requiredRoles(configured.value.effective.config.steering).map((role) => helperDetail(configured.value.effective.config.tools, role));
+        // SPEC §4.6.6 + §4.18.3: the token-saver role is satisfied by the
+        // engine itself, so with no external pin the row carries live
+        // evidence instead of probing a binary. All-absent evidence reads
+        // missing: a finding, not a pass.
+        helpers = helpers.map((helper) => helper.role === "token-saver" && !helper.present
+            ? tokenSaverHelper(summarizeTokenSaverEvidence(events))
+            : helper);
+    }
+    return { events, corrupt: log?.corrupt ?? 0, observed, packs, helpers };
+}
+function terseArgs(args, count) {
+    try {
+        const parsed = parseArgs({
+            args: [...args],
+            options: {},
+            allowPositionals: true,
+        });
+        return parsed.positionals.length === count;
+    }
+    catch {
+        return false;
+    }
+}
+// SPEC §4.18.3: one screen with engine, packs, harness states, task, waivers,
+// ratchet, deps, integrity, escalations and remediation progress.
+export async function handleStatus(req) {
+    if (!terseArgs(req.args, 0)) {
+        return usageError("usage: codictator status");
+    }
+    const root = await needRoot(req);
+    if (typeof root !== "string") {
+        return root;
+    }
+    const ports = await portsFor(root);
+    if (!ports.ok) {
+        return fail("CDX-E903", ports.error.message, ports.error.remediation, req.json);
+    }
+    const parts = await collectStatusParts(root, req.engineVersion ?? ENGINE_VERSION);
+    const input = {
+        engineVersion: req.engineVersion ?? ENGINE_VERSION,
+        packs: parts.packs,
+        harnesses: harnessStates(parts.observed),
+        helpers: parts.helpers,
+        events: parts.events.length,
+        corrupt: parts.corrupt,
+        gap: parts.events.length === 0,
+        task: undefined,
+        waivers: undefined,
+        ratchet: undefined,
+        deps: undefined,
+        integrity: undefined,
+        escalations: undefined,
+        remediation: undefined,
+        now: ports.value.clock.now(),
+    };
+    if (req.json) {
+        printJson(buildStatusJson(input));
+    }
+    else {
+        printHuman(buildStatusText(input), req.quiet);
+    }
+    return ok(0);
+}

package/dist/cli/inspect.d.ts

@@ -0,0 +1,5 @@
+import type { Finding, Result } from "../kernel/index.ts";
+import type { CommandRequest } from "./shared.ts";
+export declare function printFinding(finding: Finding, quiet: boolean): void;
+export declare function handleVerify(req: CommandRequest): Promise<Result<number>>;
+export { handleStatus, readLogEvents } from "./inspect-status.ts";