@dungle-scrubs/harness-cli-normalizer 0.1.3 → 0.3.0

package/src/cli/resolve-harness.ts

@@ -0,0 +1,33 @@
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { HARNESS_NAMES } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
+
+export const resolveHarness = (name: string): HarnessDescriptor => {
+  if (!(HARNESS_NAMES as readonly string[]).includes(name)) {
+    // Use ArgvRefusalError shape for consistency but throw generic with supported list
+    // Caller will map to exit 2 with supported list
+    const err = new ArgvRefusalError({
+      issue: "unsupported-option",
+      harness: "claude",
+      supported: [...HARNESS_NAMES],
+      detail: `unknown harness ${JSON.stringify(name)}`,
+    });
+    // Overwrite message to be harness-specific
+    err.message = `unknown harness ${JSON.stringify(name)}; supported: ${[...HARNESS_NAMES].join(", ")}`;
+    throw err;
+  }
+  const map = defaultDescriptors();
+  const h = map[name as keyof typeof map];
+  if (!h) {
+    throw new ArgvRefusalError({
+      issue: "unsupported-option",
+      harness: name as "claude",
+      supported: [...HARNESS_NAMES],
+      detail: `harness ${name} not found`,
+    });
+  }
+  return h;
+};
+
+export const SUPPORTED_HARNESSES = [...HARNESS_NAMES] as const;

package/src/cli/run.ts

@@ -0,0 +1,280 @@
+import type { HarnessEvent } from "../execution/events.js";
+import { nodeRunnerDeps } from "../execution/node-deps.js";
+import { KILL_GRACE_MS, redactArgv, streamTurn } from "../execution/stream-turn.js";
+import { buildLaunchArgv, buildResumeArgv } from "../interpretation/argv.js";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { parseRunExtra, parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { createRenderState, renderEvent, writeEventNdjson } from "./render.js";
+import { resolveHarness } from "./resolve-harness.js";
+
+export const run = async (harnessName: string, rawArgs: string[]): Promise<void> => {
+  const h = resolveHarness(harnessName);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    const { RUN_HELP } = await import("./help.js");
+    process.stdout.write(RUN_HELP);
+    return;
+  }
+
+  const { parseCommonFlags, detectPositionalPromptInjection } = await import("./args.js");
+  const injection = detectPositionalPromptInjection(rawArgs);
+  if (injection) {
+    const err = new ArgvRefusalError({
+      issue: "prompt-flag-injection",
+      harness: h.name,
+      supported: ["prompt must not start with '-'"],
+      detail: `it would be parsed as a flag by ${h.bin}`,
+    });
+    process.stderr.write(`${err.message}\n`);
+    process.stderr.write(`supported: prompt must not start with '-'\n`);
+    process.exitCode = 2;
+    return;
+  }
+  let parsed: ReturnType<typeof parseCommonFlags>;
+  try {
+    parsed = parseCommonFlags(rawArgs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`unknown flag: ${message}\n`);
+    process.stderr.write(`Run 'hcn run --help' for usage.\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const values = parsed.values as Record<string, unknown>;
+  const positionals = parsed.positionals as string[];
+  // positionals may contain prompt if not using flag; harness already consumed so first positional is prompt
+  const positionalPrompt = positionals.length > 0 ? positionals[0] : undefined;
+  if (positionals.length > 1) {
+    process.stderr.write(`too many positionals for run; expected one prompt\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const wantJson = values.json === true;
+
+  // Resolve prompt (async for --prompt-file -)
+  let prompt: string;
+  let promptSource: string;
+  try {
+    const resolved = await resolvePromptAsync({
+      positionalPrompt,
+      promptFlag: values.prompt as string | undefined,
+      promptFile: values["prompt-file"] as string | undefined,
+    });
+    prompt = resolved.prompt;
+    promptSource = resolved.source;
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      process.stderr.write(`prompt file not found: ${(err as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  // Build turn options
+  let turnOpts: ReturnType<typeof parseTurnOptions>;
+  try {
+    turnOpts = parseTurnOptions(values);
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  let extra: ReturnType<typeof parseRunExtra>;
+  try {
+    extra = parseRunExtra(values);
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  const isExplicit = promptSource !== "positional";
+  const fullOpts = {
+    ...turnOpts,
+    prompt,
+    cwd: extra.cwd,
+    env: extra.env,
+    resume: extra.resume,
+    ...(isExplicit ? { __explicitPrompt: true as const } : {}),
+  } as Parameters<typeof streamTurn>[1] & { resume?: string; __explicitPrompt?: boolean };
+
+  // Pre-validate via building argv to catch refusals before spawn (so we don't spawn on bad args)
+  let _validated = false;
+  let preArgv: string[] | null = null;
+  try {
+    if (fullOpts.resume) {
+      preArgv = buildResumeArgv(h, {
+        ...(turnOpts as object),
+        prompt,
+        sessionId: fullOpts.resume,
+        __explicitPrompt: isExplicit,
+      } as never);
+    } else {
+      preArgv = buildLaunchArgv(h, {
+        ...(turnOpts as object),
+        prompt,
+        __explicitPrompt: isExplicit,
+      } as never);
+    }
+    _validated = true;
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  // preArgv is already set via validated build; no extra handling needed for explicit prompt bypass
+  // since buildLaunchArgv now respects __explicitPrompt.
+
+  if (preArgv) {
+    const redacted = redactArgv(preArgv, prompt);
+    if (!wantJson) {
+      process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
+    } else {
+      // In JSON mode, diagnostics to stderr only
+      process.stderr.write(`spawn: ${redacted.join(" ")}\n`);
+    }
+  }
+
+  // Delete HERDR_ENV before spawn
+  delete (process.env as Record<string, string | undefined>).HERDR_ENV;
+
+  const deps = nodeRunnerDeps();
+
+  // Signal handling
+  const _currentProc: { signal: (sig: "SIGTERM" | "SIGKILL") => void } | null = null;
+  // We'll need to track the spawned process via deps.signal; but streamTurn owns process handle.
+  // Instead we intercept deps.signal via a wrapper that captures proc.
+  // Simpler: use deps directly and handle SIGINT by calling process.kill? But spec says via injected signal.
+  // We'll create a wrapper deps where signal captures last proc.
+  let lastProc: import("../execution/deps.js").SpawnedProcess | null = null;
+  const originalSignal = deps.signal;
+  const wrappedDeps = {
+    ...deps,
+    signal: (proc: import("../execution/deps.js").SpawnedProcess, sig: "SIGTERM" | "SIGKILL") => {
+      lastProc = proc;
+      originalSignal(proc, sig);
+    },
+    spawn: (argv: readonly string[], opts: import("../execution/deps.js").SpawnOptions) => {
+      const proc = deps.spawn(argv, opts);
+      lastProc = proc;
+      return proc;
+    },
+  };
+
+  let interrupted = false;
+  const onSig = async () => {
+    if (interrupted) return;
+    interrupted = true;
+    if (lastProc) {
+      try {
+        wrappedDeps.signal(lastProc, "SIGTERM");
+        await new Promise<void>((resolve) => {
+          setTimeout(() => {
+            if (lastProc) {
+              try {
+                wrappedDeps.signal(lastProc, "SIGKILL");
+              } catch {}
+            }
+            resolve();
+          }, KILL_GRACE_MS);
+        });
+      } catch {}
+    }
+  };
+  process.on("SIGINT", onSig);
+  process.on("SIGTERM", onSig);
+
+  const state = createRenderState();
+  let lastEvent: HarnessEvent | null = null;
+  let exitCode = 0;
+
+  try {
+    // streamTurn handles both launch and resume via TurnRunOptions
+    const events = streamTurn(h, fullOpts, wrappedDeps);
+    for await (const event of events) {
+      lastEvent = event;
+      if (wantJson) {
+        writeEventNdjson(event);
+      } else {
+        renderEvent(event, state);
+      }
+      if (event.kind === "done") {
+        if (event.cause === "clean") exitCode = 0;
+        else exitCode = 1;
+        // If failure class is rejected? But done.cause for rejected would be failed? Still 1 per mapping, but refusal before spawn is 2.
+        // The RFC says limit/auth ->1, transport ->1, refusal ->2 (already handled). So done non-clean =>1.
+      }
+      if (event.kind === "limit") {
+        // Also ensure exitCode will be 1 (handled via done)
+      }
+    }
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      process.off("SIGINT", onSig);
+      process.off("SIGTERM", onSig);
+      return;
+    }
+    // Transport / spawn failure
+    process.stderr.write(`run failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    if (wantJson && lastEvent?.kind !== "done") {
+      // Emit failure+done if stream didn't? streamTurn should already emit done, but if we crashed before spawn, synthesize?
+      const failure = {
+        kind: "failure" as const,
+        class: "transport" as const,
+        retryable: true,
+        message: String(err),
+      };
+      process.stdout.write(`${JSON.stringify(failure)}\n`);
+      process.stdout.write(
+        `${JSON.stringify({ kind: "done", exitCode: null, cause: "failed", failure })}\n`,
+      );
+    }
+    process.exitCode = 1;
+    process.off("SIGINT", onSig);
+    process.off("SIGTERM", onSig);
+    return;
+  } finally {
+    process.off("SIGINT", onSig);
+    process.off("SIGTERM", onSig);
+  }
+
+  // If no done event was seen (should not happen), exit 1
+  if (lastEvent === null) {
+    process.exitCode = 1;
+    return;
+  }
+  if (lastEvent.kind === "done") {
+    process.exitCode = exitCode;
+  } else {
+    // Stream ended without done (e.g., consumer break via head)
+    process.exitCode = interrupted ? 1 : 0;
+  }
+
+  if (interrupted && process.exitCode === 0) process.exitCode = 1;
+};

package/src/cli/session.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { nodeRunnerDeps } from "../execution/node-deps.js";
+import { CLOSE_GRACE_MS, openSession } from "../execution/open-session.js";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { createRenderState, renderEvent } from "./render.js";
+import { resolveHarness } from "./resolve-harness.js";
+
+export const session = async (harnessName: string, rawArgs: string[]): Promise<void> => {
+  // Only claude supported
+  if (harnessName !== "claude") {
+    const err = new ArgvRefusalError({
+      issue: "no-session-mode",
+      harness: harnessName as "claude",
+      supported: ["claude"],
+      detail: `session is claude-only; ${harnessName} declares no persistent headless session mode`,
+    });
+    process.stderr.write(`${err.message}\n`);
+    process.stderr.write(`supported: claude\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const h = resolveHarness(harnessName);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    const { SESSION_HELP } = await import("./help.js");
+    process.stdout.write(SESSION_HELP);
+    return;
+  }
+
+  const { parseCommonFlags } = await import("./args.js");
+  let parsed: ReturnType<typeof parseCommonFlags>;
+  try {
+    parsed = parseCommonFlags(rawArgs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`unknown flag: ${message}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const values = parsed.values as Record<string, unknown>;
+  const sessionId =
+    (values["session-id"] as string | undefined) ??
+    (values.resume as string | undefined) ??
+    randomUUID();
+  const model = values.model as string | undefined;
+  const cwd = values.cwd as string | undefined;
+
+  // Validate sessionId shape? let openSession handle via assertUsableSessionId
+  delete (process.env as Record<string, string | undefined>).HERDR_ENV;
+
+  const deps = nodeRunnerDeps();
+
+  let handle: ReturnType<typeof openSession>;
+  try {
+    handle = openSession(h, { sessionId, model, cwd }, deps);
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    process.stderr.write(
+      `could not open session: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(
+    `interactive ${h.name} session ${sessionId}\n(empty line or "exit" to quit)\n`,
+  );
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  // Handle SIGINT to close session cleanly
+  let closing = false;
+  const doClose = async () => {
+    if (closing) return;
+    closing = true;
+    try {
+      // race with CLOSE_GRACE_MS ? openSession's close does escalation internally, but we add outer guard
+      const timeout = setTimeout(() => {
+        process.stderr.write(`close timed out after ${CLOSE_GRACE_MS}ms\n`);
+      }, CLOSE_GRACE_MS + 1000);
+      await handle.close();
+      clearTimeout(timeout);
+    } catch (err) {
+      process.stderr.write(`close failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    rl.close();
+  };
+  process.on("SIGINT", doClose);
+  process.on("SIGTERM", doClose);
+
+  const turns = handle.turns[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let line: string;
+      try {
+        line = await rl.question("you › ");
+      } catch {
+        // readline closed (Ctrl-D)
+        break;
+      }
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed === "exit") break;
+
+      const result = handle.send(line);
+      if (result.disposition === "queued") {
+        process.stderr.write(`disposition: queued (turn in progress)\n`);
+      }
+
+      const turn = (await turns.next()).value as
+        | AsyncIterable<import("../execution/events.js").HarnessEvent>
+        | undefined;
+      if (turn === undefined) break;
+      const state = createRenderState();
+      for await (const event of turn) {
+        renderEvent(event, state);
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`session error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+  } finally {
+    process.off("SIGINT", doClose);
+    process.off("SIGTERM", doClose);
+    try {
+      await doClose();
+    } catch {}
+    rl.close();
+  }
+};

package/src/cli/version.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+let cached: string | null = null;
+
+export const getVersion = (): string => {
+  if (cached !== null) return cached;
+  // dist/cli.js is at dist/cli.js -> repo root is one level up from dist, or two from src/cli per build.
+  // Try to locate package.json via fileURLToPath.
+  try {
+    const current = fileURLToPath(import.meta.url);
+    // src/cli/version.ts -> ../../package.json ; dist/cli.js -> ../package.json
+    const candidates = [
+      resolve(dirname(current), "../../package.json"),
+      resolve(dirname(current), "../package.json"),
+      resolve(dirname(current), "../../../package.json"),
+    ];
+    for (const p of candidates) {
+      try {
+        const raw = readFileSync(p, "utf8");
+        const parsed = JSON.parse(raw) as { version?: string };
+        if (typeof parsed.version === "string") {
+          cached = parsed.version;
+          return cached;
+        }
+      } catch {}
+    }
+  } catch {}
+  cached = "0.0.0";
+  return cached;
+};

package/src/execution/decode.ts

@@ -75,5 +75,37 @@ export const decodeParsed = (
   // Content (message/token/tool/error) is per-harness; identity above is
   // descriptor-driven. contentEventsOf dispatches by harness name.
   for (const content of contentEventsOf(h.name, raw)) events.push(content);
+
+  // claude's rate_limit_event: only non-"allowed" statuses are failures.
+  // overageStatus is deliberately not classified - it is a separate
+  // billing signal, not a rate limit.
+  if (h.name === "claude" && typeof (raw as Record<string, unknown>).type === "string") {
+    const rec = raw as Record<string, unknown>;
+    if (rec.type === "rate_limit_event") {
+      const info = rec.rate_limit_info as Record<string, unknown> | undefined;
+      const status = info?.status as string | undefined;
+      if (status !== undefined && status !== "allowed") {
+        const rawResets = info?.resetsAt;
+        let resetsAt: number | undefined;
+        if (typeof rawResets === "number" && Number.isFinite(rawResets) && rawResets > 0) {
+          // Arithmetic conversion: resetsAt is seconds, we need milliseconds. No wall clock read.
+          resetsAt = rawResets * 1000;
+          if (!Number.isFinite(resetsAt) || resetsAt <= 0) resetsAt = undefined;
+        }
+        // Push a failure event directly - this is a structured record, not a wall scan
+        const failure: import("./failure.js").FailureSummary = {
+          class: "rate-limit",
+          retryable: true,
+          message: `Rate limit hit (rate_limit_event status=${status}) - retry after backoff or route to another provider`,
+          code: "rate-limit" as const,
+          ...(resetsAt !== undefined ? { resetsAt } : {}),
+        };
+        events.push({
+          kind: "failure",
+          ...failure,
+        } as unknown as import("./events.js").HarnessEvent);
+      }
+    }
+  }
   return events;
 };

package/src/execution/deps.ts

@@ -29,6 +29,10 @@ export interface SpawnOptions {
   /** `pipe` opens a writable stdin (sessions require it); `inherit` hands
    * the child the parent's fd 0; `close` gives it nothing (pi's rule). */
   readonly stdin: "inherit" | "close" | "pipe";
+  /** Merged over the parent environment by the spawn adapter. A key mapped
+   * to "" means DELETE the variable (not an empty string). Validated
+   * against /^[A-Za-z_][A-Za-z0-9_]*$/ and NUL-free. */
+  readonly env?: Readonly<Record<string, string>>;
 }
 
 export type TimerHandle = number;
@@ -50,8 +54,10 @@ export interface RunnerDeps {
   readonly spawn: (argv: readonly string[], opts: SpawnOptions) => SpawnedProcess;
   readonly clock: Clock;
   readonly signal: (proc: SpawnedProcess, sig: SignalName) => void;
-  /** Stall watchdog budget; armed ONLY for none-granularity invocations. */
+  /** Inactivity budget; arms at every granularity and rearms on any output chunk. */
   readonly stallMs?: number;
+  /** Wall-clock ceiling; armed once at spawn and never rearmed. */
+  readonly turnTimeoutMs?: number;
   readonly log?: BoundaryLog;
   /** Host-minted correlation id; without it the runner falls back to a
    * per-process monotonic counter (collides across processes). */

package/src/execution/events.ts

@@ -15,8 +15,9 @@
  * concatenate both.
  */
 import type { CapabilityResult } from "../interpretation/capabilities.js";
+import type { FailureSummary } from "./failure.js";
 
-export type ExitCause = "clean" | "limit" | "crash" | "stall" | "killed";
+export type ExitCause = "clean" | "limit" | "crash" | "stall" | "killed" | "failed";
 
 export type HarnessEvent =
   | {
@@ -32,6 +33,12 @@ export type HarnessEvent =
   | { readonly kind: "context"; readonly usedPct: number }
   | { readonly kind: "limit"; readonly code: string; readonly message: string }
   | { readonly kind: "error"; readonly message: string }
-  | { readonly kind: "done"; readonly exitCode: number | null; readonly cause: ExitCause };
+  | ({ readonly kind: "failure" } & FailureSummary)
+  | {
+      readonly kind: "done";
+      readonly exitCode: number | null;
+      readonly cause: ExitCause;
+      readonly failure?: FailureSummary;
+    };
 
 export const DROPPABLE_KINDS = new Set(["token", "progress", "context"]);