@dungle-scrubs/harness-cli-normalizer 0.5.5 → 0.5.6

package/src/cli/inspect.ts

@@ -210,13 +210,16 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
       const resolvedSkills = resolveSkillNames(rawSkills, h.name);
-      const claudeTokens: string[] = [];
+      const skillTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
-        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+        skillTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      } else if (h.name === "codex") {
+        const { codexSkillConfigArg } = await import("../interpretation/skills-selection.js");
+        skillTokens.push(...codexSkillConfigArg(listKnownSkills(), resolvedSkills));
       }
       (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
-      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+      (turnOpts as unknown as Record<string, unknown>).__skillTokens = skillTokens;
     } catch (err) {
       if (err instanceof ArgvRefusalError) {
         process.stderr.write(`${err.message}\n`);
@@ -301,9 +304,8 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
   let argv: string[];
   try {
     argv = buildLaunchArgv(h, fullOpts);
-    const claudeTokens = (effectiveRest as unknown as { __claudeSkillTokens?: string[] })
-      .__claudeSkillTokens;
-    if (claudeTokens !== undefined && claudeTokens.length > 0) argv.push(...claudeTokens);
+    const skillTokens = (effectiveRest as unknown as { __skillTokens?: string[] }).__skillTokens;
+    if (skillTokens !== undefined && skillTokens.length > 0) argv.push(...skillTokens);
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       refuse(refusalOf(err as ArgvRefusalError), false);

package/src/cli/resume-guard.ts

@@ -1,4 +1,4 @@
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { storePath } from "../interpretation/store.js";
 import type { HarnessDescriptor } from "../knowledge/descriptor.js";
 
@@ -31,5 +31,29 @@ export const resumeStore = (
   } catch {
     path = null;
   }
-  return { path, exists: path !== null && existsSync(path) };
+  return { path, exists: path !== null && sessionExistsAt(path, opts.sessionId) };
+};
+
+/** A store template that resolves to a FILE names the session directly and
+ * existence is the file's. One that resolves to a DIRECTORY names where the
+ * harness files every session for this cwd, and the session is one entry in
+ * it whose name carries the id somewhere - pi writes `<timestamp>_<id>.jsonl`,
+ * so the id's position is not a template. Checking only that the directory
+ * exists reported every id as present once any session had ever run in the
+ * cwd, which made the guard pass unknown ids on pi and, once `origin` rode
+ * on it, reported a brand-new session as resumed. */
+const sessionExistsAt = (path: string, sessionId: string): boolean => {
+  if (!existsSync(path)) return false;
+  let isDir = false;
+  try {
+    isDir = statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+  if (!isDir) return true;
+  try {
+    return readdirSync(path).some((name) => name.includes(sessionId));
+  } catch {
+    return false;
+  }
 };

package/src/cli/run.ts

@@ -185,13 +185,16 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     try {
       const { resolveSkillNames, listKnownSkills } = await import("./skills-root.js");
       const resolvedSkills = resolveSkillNames(rawSkills, h.name);
-      const claudeTokens: string[] = [];
+      const skillTokens: string[] = [];
       if (h.name === "claude") {
         const { claudeSkillOverridesArg } = await import("../interpretation/skills-selection.js");
-        claudeTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+        skillTokens.push(...claudeSkillOverridesArg(listKnownSkills(), resolvedSkills));
+      } else if (h.name === "codex") {
+        const { codexSkillConfigArg } = await import("../interpretation/skills-selection.js");
+        skillTokens.push(...codexSkillConfigArg(listKnownSkills(), resolvedSkills));
       }
       (turnOpts as unknown as Record<string, unknown>).skills = resolvedSkills;
-      (turnOpts as unknown as Record<string, unknown>).__claudeSkillTokens = claudeTokens;
+      (turnOpts as unknown as Record<string, unknown>).__skillTokens = skillTokens;
     } catch (err) {
       if (err instanceof ArgvRefusalError) {
         refuse(refusalOf(err), wantJson);
@@ -209,9 +212,9 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     project?: Partial<ReturnType<typeof parseTurnOptions>>;
   } = {};
   // Config files load on EVERY run, launch or resume: the tiers feed the
-  // defaults profile on launch, and issue #41's escalateQuestions (a
+  // defaults profile on launch, and issue #41's questions (a
   // behavior instruction, not a turn option) resolves from them on resume
-  // too - otherwise a no-escalate session would flip its preamble on the
+  // too - otherwise a no-ask session would flip its preamble on the
   // answer turn. Resolution of TURN options stays launch-only.
   const tiers = resolvedTiers;
   {
@@ -256,39 +259,34 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     writeProvenance(h.name, provenance, unrenderable);
   }
 
-  // issue #41: question-escalation precedence arg > project > user >
-  // default-true (a behavior instruction, not a turn option - the
-  // default lives OUTSIDE the profile on purpose, per the spec). It
-  // applies on LAUNCH AND RESUME alike: it shapes each turn's prompt
-  // preamble and event stream, never a session setting.
-  const projectEscalate = (resolvedTiers.project as { escalateQuestions?: boolean } | undefined)
-    ?.escalateQuestions;
-  const userEscalate = (resolvedTiers.user as { escalateQuestions?: boolean } | undefined)
-    ?.escalateQuestions;
-  const escalateQuestions =
-    turnOpts.escalateQuestions !== undefined
-      ? turnOpts.escalateQuestions
-      : projectEscalate !== undefined
-        ? projectEscalate
-        : userEscalate !== undefined
-          ? userEscalate
-          : true;
-  const escalateTier =
-    turnOpts.escalateQuestions !== undefined
+  // question mode precedence arg > project > user > default (ask)
+  const projectQuestions = (resolvedTiers.project as { questions?: string } | undefined)?.questions;
+  const userQuestions = (resolvedTiers.user as { questions?: string } | undefined)?.questions;
+  const rawMode = (turnOpts as { questions?: string }).questions;
+  const questionMode =
+    rawMode !== undefined
+      ? (rawMode as import("../interpretation/question.js").QuestionMode)
+      : projectQuestions !== undefined
+        ? (projectQuestions as import("../interpretation/question.js").QuestionMode)
+        : userQuestions !== undefined
+          ? (userQuestions as import("../interpretation/question.js").QuestionMode)
+          : ("ask" as const);
+  const questionTier =
+    rawMode !== undefined
       ? "arg"
-      : projectEscalate !== undefined
+      : projectQuestions !== undefined
         ? "project-config"
-        : userEscalate !== undefined
+        : userQuestions !== undefined
           ? "user-config"
           : "default";
 
   const fullOpts = {
     ...effectiveTurnOpts,
-    prompt: composeEscalatedPrompt(prompt, escalateQuestions),
+    prompt: composeEscalatedPrompt(prompt, questionMode),
     cwd: extra.cwd,
     env: extra.env,
     resume: extra.resume,
-    escalateQuestions,
+    questions: questionMode,
     ...(passthrough.length > 0 ? { passthrough } : {}),
     ...(isExplicit ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof streamTurn>[1] & {
@@ -304,7 +302,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     if (fullOpts.resume) {
       // Resume never carries TURN-option profile resolution (launch-only
       // rule), so it builds from the raw turn options; hcn-owned behavior
-      // (escalateQuestions preamble, timeout budget) still applies.
+      // (questions preamble, timeout budget) still applies.
       preArgv = buildResumeArgv(h, {
         ...(turnOpts as object),
         prompt: fullOpts.prompt,
@@ -321,10 +319,10 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
         prompt: fullOpts.prompt,
         __explicitPrompt: isExplicit,
       } as never);
-      const claudeSkillTokens = (effectiveTurnOpts as unknown as { __claudeSkillTokens?: string[] })
-        .__claudeSkillTokens;
-      if (claudeSkillTokens !== undefined && claudeSkillTokens.length > 0) {
-        preArgv.push(...claudeSkillTokens);
+      const skillTokens = (effectiveTurnOpts as unknown as { __skillTokens?: string[] })
+        .__skillTokens;
+      if (skillTokens !== undefined && skillTokens.length > 0) {
+        preArgv.push(...skillTokens);
       }
     }
     _validated = true;
@@ -349,9 +347,7 @@ export const run = async (harnessName: string, rawArgs: string[]): Promise<void>
     }
     // issue #41: the escalation mode rides stderr as provenance, like
     // every other resolution the turn depends on.
-    process.stderr.write(
-      `provenance: escalateQuestions = ${escalateQuestions} (${escalateTier})\n`,
-    );
+    process.stderr.write(`provenance: questions = ${questionMode} (${questionTier})\n`);
     // On a harness whose include flag is not a strict allowlist (claude),
     // a name outside the curated set passes through ungated; say which
     // ones so a wrong-case name is visible. A grant with no known name at

package/src/cli/session-json.ts

@@ -4,7 +4,7 @@
  * with the control events (`session`, `turn`, `disposition`, `closed`) that
  * a program needs to drive a session it does not own the timing of. RFC-01.
  *
- * This owns the wire framing only. The turn lifecycle, the queue, and the id
+ * This owns the wire framing only. The turn lifecycle and the id
  * correlation live in `openSession`; this reads the id off the yielded turn
  * rather than shadowing the runner's delivery order.
  */
@@ -16,6 +16,7 @@ import {
   type SessionHandle,
   type SessionSendResult,
 } from "../execution/open-session.js";
+import type { QuestionMode } from "../interpretation/question.js";
 
 /** What the CLI reads back after a close, captured from the runner's
  * `session_close` boundary log. */
@@ -24,15 +25,18 @@ export interface CloseInfo {
   cause: string;
 }
 
+export type SessionOrigin = "fresh" | "resumed";
+
 export interface JsonSessionArgs {
   readonly handle: SessionHandle;
   readonly sessionId: string;
   readonly harness: string;
   readonly hcnVersion: string;
-  readonly escalateQuestions: boolean;
+  readonly questions?: QuestionMode;
+  readonly origin: SessionOrigin;
   /** Read after close - the runner's final exitCode and cause. */
   readonly getCloseInfo: () => CloseInfo;
-  /** Read after close - ids the runner accepted as queued and never
+  /** Read after close - ids the runner accepted and never
    * delivered. Each owes the consumer a rejection (RFC S003). */
   readonly getDroppedIds?: () => readonly string[];
   /** Injected for tests; defaults to process.stdin / process.stdout. */
@@ -116,12 +120,14 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
     return chain;
   };
 
+  const qMode: QuestionMode = a.questions ?? "ask";
   await emit({
     kind: "session",
     sessionId: a.sessionId,
     harness: a.harness,
     hcn: a.hcnVersion,
-    escalateQuestions: a.escalateQuestions,
+    questions: qMode,
+    origin: a.origin,
   });
 
   // Shared between the pumps: the last question asked, whether the last turn
@@ -242,7 +248,7 @@ export const runJsonSession = async (a: JsonSessionArgs): Promise<number> => {
   }
   unanswered.clear();
 
-  // Every input the runner accepted as queued and then lost gets its own
+  // Every input the runner accepted and then lost gets its own
   // rejection, before the terminal line (RFC S003).
   for (const id of a.getDroppedIds?.() ?? []) {
     await emit({ kind: "disposition", id, disposition: "rejected", reason: "closed" });

package/src/cli/session.ts

@@ -57,45 +57,96 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
   }
 
   const values = parsed.values as Record<string, unknown>;
-  const sessionId =
-    (values["session-id"] as string | undefined) ??
-    (values.resume as string | undefined) ??
-    randomUUID();
+  // --resume and --session-id are aliases for one concept: resume an existing
+  // session. Passing both is refused, matching hcn run's parseRunExtra shape
+  // (src/cli/args.ts) rather than inventing a second parser.
+  if (values.resume !== undefined && values["session-id"] !== undefined) {
+    const { ArgvRefusalError: AliasError } = await import("../interpretation/refusal.js");
+    const err = new AliasError({
+      issue: "mutually-exclusive-options",
+      harness: h.name,
+      supported: ["--resume or --session-id, not both (--session-id is an alias for --resume)"],
+      detail: "both --resume and --session-id given",
+    });
+    const { refusalOf: aliasRefusalOf, refuse: aliasRefuse } = await import("./refuse.js");
+    aliasRefuse(aliasRefusalOf(err), jsonMode, "closed");
+    return;
+  }
+  const resumeId =
+    (values.resume as string | undefined) ?? (values["session-id"] as string | undefined);
+  // The two flags are aliases for "use this session". Whether that means
+  // RESUME is decided by the store, not by which spelling was typed: an id
+  // that exists is resumed (resumeFlag rendered), an id that does not exist
+  // names a fresh session (idFlag rendered). --resume on an id that does not
+  // exist is the one combination refused, below - a caller who said "resume"
+  // and would silently get a fresh conversation is issue #86 exactly.
+  const explicitResume = values.resume !== undefined;
+  // A caller-supplied id must be the shape this harness's store files
+  // sessions under (issue #95). hcn run already holds this line through
+  // parse-resume; session only checked the safe-filename rule, so "bogus"
+  // reached the harness, rode the session and identity events, and on a
+  // create-on-unknown harness became a real file nobody can find again.
+  if (resumeId !== undefined && !h.resume.idShape.test(resumeId)) {
+    const flag = explicitResume ? "--resume" : "--session-id";
+    const { refuse: shapeRefuse } = await import("./refuse.js");
+    shapeRefuse(
+      {
+        message: `${flag} ${JSON.stringify(resumeId.slice(0, 64))} is not a ${h.name} session id`,
+        issue: "invalid-option-value",
+        supported: [`a session id matching ${String(h.resume.idShape)}`],
+      },
+      jsonMode,
+      "closed",
+    );
+    return;
+  }
+  const sessionId = resumeId ?? randomUUID();
+  let isResume = false;
   const model = values.model as string | undefined;
   const cwd = values.cwd as string | undefined;
   const provider = values.provider as string | undefined;
 
-  // issue #44: same precedence as hcn run - arg > project > user >
-  // default-true. A behavior instruction, so it rides every send's
-  // preamble, never a harness flag.
-  const argEscalate =
-    values["escalate-questions"] === true
-      ? true
-      : values["no-escalate-questions"] === true
-        ? false
-        : undefined;
-  let escalateQuestions: boolean;
-  let escalateTier: "arg" | "project-config" | "user-config" | "default";
+  // question mode precedence arg > project > user > default (ask)
+  const rawArgMode = values.questions !== undefined ? String(values.questions) : undefined;
+  if (rawArgMode !== undefined && !["ask", "assume", "none"].includes(rawArgMode)) {
+    const { refuse, refusalOf } = await import("./refuse.js");
+    const { ArgvRefusalError } = await import("../interpretation/refusal.js");
+    refuse(
+      refusalOf(
+        new ArgvRefusalError({
+          issue: "invalid-option-value",
+          harness: h.name,
+          option: "questions",
+          supported: ["ask", "assume", "none"],
+          detail: rawArgMode,
+        }),
+      ),
+      jsonMode,
+      "closed",
+    );
+    return;
+  }
+  let questionMode: import("../interpretation/question.js").QuestionMode;
+  let questionTier: "arg" | "project-config" | "user-config" | "default";
   try {
     const { loadUserConfig, loadProjectConfig } = await import("./config.js");
-    const user = loadUserConfig()?.config as { escalateQuestions?: boolean } | undefined;
-    const project = loadProjectConfig()?.config as { escalateQuestions?: boolean } | undefined;
-    escalateQuestions =
-      argEscalate !== undefined
-        ? argEscalate
-        : project?.escalateQuestions !== undefined
-          ? project.escalateQuestions
-          : user?.escalateQuestions !== undefined
-            ? user.escalateQuestions
-            : true;
-    escalateTier =
-      argEscalate !== undefined
-        ? "arg"
-        : project?.escalateQuestions !== undefined
-          ? "project-config"
-          : user?.escalateQuestions !== undefined
-            ? "user-config"
-            : "default";
+    const user = loadUserConfig()?.config as { questions?: string } | undefined;
+    const project = loadProjectConfig()?.config as { questions?: string } | undefined;
+    const userMode = user?.questions;
+    const projectMode = project?.questions;
+    if (rawArgMode !== undefined) {
+      questionMode = rawArgMode as import("../interpretation/question.js").QuestionMode;
+      questionTier = "arg";
+    } else if (projectMode !== undefined) {
+      questionMode = projectMode as import("../interpretation/question.js").QuestionMode;
+      questionTier = "project-config";
+    } else if (userMode !== undefined) {
+      questionMode = userMode as import("../interpretation/question.js").QuestionMode;
+      questionTier = "user-config";
+    } else {
+      questionMode = "ask";
+      questionTier = "default";
+    }
   } catch (configErr) {
     process.stderr.write(`config error: ${(configErr as Error).message}\n`);
     if (jsonMode) {
@@ -112,9 +163,38 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
     process.exitCode = 2;
     return;
   }
-  process.stderr.write(`provenance: escalateQuestions = ${escalateQuestions} (${escalateTier})\n`);
+  process.stderr.write(`provenance: questions = ${questionMode} (${questionTier})\n`);
 
   // Validate sessionId shape? let openSession handle via assertUsableSessionId
+  // Unknown-id refusal reuses the run resume guard (src/cli/resume-guard.ts):
+  // harnesses that create on unknown (pi, muse with onMissing === "create")
+  // are refused before spawn with the same message shape hcn run uses.
+  // claude (onMissing === "error") refuses on its own; no store check.
+  if (resumeId !== undefined) {
+    const { resumeStore: checkResumeStore } = await import("./resume-guard.js");
+    const { path: storePath, exists } = checkResumeStore(h, {
+      home: process.env.HOME ?? process.env.USERPROFILE ?? "",
+      cwd: cwd ?? process.cwd(),
+      sessionId,
+    });
+    // Exists in the store: resume it, whichever alias was typed. Absent and the
+    // caller only named an id: a fresh session under that id, as before.
+    isResume = storePath !== null && exists;
+    if (explicitResume && storePath !== null && !exists) {
+      const { refuse: guardRefuse } = await import("./refuse.js");
+      guardRefuse(
+        {
+          message: `no ${h.name} session ${sessionId} found at ${storePath}`,
+          issue: "invalid-option-value",
+          supported: [`a session id that exists in ${h.name}'s store`],
+        },
+        jsonMode,
+        "closed",
+      );
+      return;
+    }
+  }
+
   delete (process.env as Record<string, string | undefined>).HERDR_ENV;
 
   const wantJson = values.json === true;
@@ -164,7 +244,11 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
 
   let handle: ReturnType<typeof openSession>;
   try {
-    handle = openSession(h, { sessionId, model, cwd, escalateQuestions, provider }, deps);
+    handle = openSession(
+      h,
+      { sessionId, model, cwd, questions: questionMode, provider, isResume },
+      deps,
+    );
   } catch (err) {
     if (err instanceof ArgvRefusalError) {
       const { refusalOf, refuse } = await import("./refuse.js");
@@ -196,7 +280,8 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       sessionId,
       harness: h.name,
       hcnVersion: getVersion(),
-      escalateQuestions,
+      questions: questionMode,
+      origin: isResume ? "resumed" : "fresh",
       getCloseInfo: () => closeInfo,
       getDroppedIds: () => droppedIds,
     });
@@ -258,10 +343,7 @@ export const session = async (harnessName: string, rawArgs: string[]): Promise<v
       const trimmed = line.trim();
       if (trimmed === "" || trimmed === "exit") break;
 
-      const result = handle.send({ id: `you-${++sendCount}`, text: line });
-      if (result.disposition === "queued") {
-        process.stderr.write(`disposition: queued (turn in progress)\n`);
-      }
+      handle.send({ id: `you-${++sendCount}`, text: line });
 
       const turn = (await turns.next()).value as
         | AsyncIterable<import("../execution/events.js").HarnessEvent>

package/src/execution/events.ts

@@ -25,10 +25,17 @@ export type ExitCause =
   | "stall"
   | "killed"
   | "failed"
-  /** issue #41: the turn ended by asking (escalateQuestions) - a
+  /** issue #41: the turn ended by asking (questions ask) - a
    * SUCCESSFUL turn (process exit 0); the caller resumes with the answer. */
   | "awaiting-input";
 
+export type EscalationMode = "ask" | "assume" | "none";
+export type EscalationDetection = "block" | "malformed" | "none";
+export interface EscalationRecord {
+  readonly mode: EscalationMode;
+  readonly detection: EscalationDetection;
+}
+
 export type HarnessEvent =
   | {
       readonly kind: "identity";
@@ -60,6 +67,7 @@ export type HarnessEvent =
       readonly exitCode: number | null;
       readonly cause: ExitCause;
       readonly failure?: FailureSummary;
+      readonly escalation: EscalationRecord;
     };
 
 export const DROPPABLE_KINDS = new Set(["token", "progress", "context"]);