@dungle-scrubs/harness-cli-normalizer 0.1.1

package/src/interpretation/parse-resume.ts

@@ -0,0 +1,117 @@
+/**
+ * Resume-command parsing: recognizes a pasted "resume this session" shell
+ * command and recovers {harness, sessionId, autonomy} - or a resume-last
+ * request where the harness supports one. The inverse of buildResumeArgv,
+ * tolerant of what shell history actually carries (quoted ids, resolved
+ * bin paths, --flag=value, flag aliases, root options on either side of a
+ * subcommand). Anchoring rules ported from v1 (D-011): the id must follow
+ * the harness's own resume grammar, match its id shape, and be the ONLY
+ * id-shaped token - a UUID inside quoted prompt text must never be
+ * returned as the session id. Position independence is safe because
+ * tokenize collapses quoted text into single words: a bare resume word can
+ * only come from a real argv slot.
+ */
+import type { HarnessDescriptor, HarnessName } from "../knowledge/descriptor.js";
+import { isUsableSessionId } from "./session-id.js";
+import { basenameOf, tokenize } from "./shape.js";
+
+export interface ParsedResume {
+  readonly harness: HarnessName;
+  readonly sessionId: string;
+  readonly autonomy: boolean;
+}
+
+/** A recorded `--last` resume: no id to anchor - corroboration ranking
+ * (rankResumeLast) decides what it names. */
+export interface ParsedResumeLast {
+  readonly harness: HarnessName;
+  readonly resumeLast: true;
+  readonly autonomy: boolean;
+}
+
+const flagTokens = (h: HarnessDescriptor): readonly string[] => [
+  h.resume.flag,
+  ...h.resume.aliases,
+];
+
+/** The id token per the descriptor's resume grammar, or null. */
+const idTokenOf = (h: HarnessDescriptor, words: readonly string[]): string | null => {
+  const positionalWords: string[] = [];
+  if (h.resume.style === "positional") positionalWords.push(h.resume.flag);
+  if (h.resume.positionalParseWord !== undefined) {
+    positionalWords.push(h.resume.positionalParseWord);
+  }
+  if (positionalWords.length > 0) {
+    // Walk consuming `--flag value` pairs so an option VALUE spelled
+    // "resume" (muse exec --workspace resume <uuid>) is never mistaken for
+    // the resume word. Root options may sit on either side of a subcommand,
+    // so position alone is not the anchor - a bare, unconsumed resume word
+    // followed by an id-shaped token is. Conservative direction: a boolean
+    // flag directly before the resume word reads as a pair and yields null
+    // (display-only false negative), never a stranger's session.
+    for (let i = 1; i < words.length; i++) {
+      const word = words[i];
+      if (word === undefined) break;
+      if (word.startsWith("-")) {
+        const next = words[i + 1];
+        if (!word.includes("=") && next !== undefined && !next.startsWith("-")) i++;
+        continue;
+      }
+      if (positionalWords.includes(word)) {
+        const candidate = words[i + 1];
+        if (candidate !== undefined && h.resume.idShape.test(candidate)) return candidate;
+      }
+    }
+  }
+  if (h.resume.style === "flag" || h.resume.positionalParseWord === undefined) {
+    for (const token of flagTokens(h)) {
+      if (h.resume.style === "positional") break;
+      const at = words.indexOf(token, 1);
+      if (at !== -1) return words[at + 1] ?? null;
+      const eqForm = words.find((w) => w.startsWith(`${token}=`));
+      if (eqForm !== undefined) return eqForm.slice(token.length + 1);
+    }
+  }
+  return null;
+};
+
+/** True when the command asks for the harness's resume-most-recent form. */
+const isResumeLast = (h: HarnessDescriptor, words: readonly string[]): boolean => {
+  if (h.resumeLast === null) return false;
+  if (!words.includes(h.resumeLast.flag)) return false;
+  // --last only means "resume last" in the resume grammar's context: after
+  // the positional resume word, or anywhere for flag-style harnesses.
+  const anchor =
+    h.resume.style === "positional" ? h.resume.flag : (h.resume.positionalParseWord ?? null);
+  if (anchor !== null) {
+    const at = words.indexOf(anchor, 1);
+    return at !== -1 && words.indexOf(h.resumeLast.flag) > at;
+  }
+  return true;
+};
+
+export const parseResumeCommand = (
+  known: readonly HarnessDescriptor[],
+  command: string,
+): ParsedResume | ParsedResumeLast | null => {
+  const words = tokenize(command);
+  const bin = words[0];
+  if (bin === undefined) return null;
+  const h = known.find((d) => basenameOf(bin) === d.bin);
+  if (h === undefined) return null;
+
+  const autonomy = h.autonomy !== null && words.includes(h.autonomy.flag);
+
+  const id = idTokenOf(h, words);
+  if (id === null) {
+    return isResumeLast(h, words) ? { harness: h.name, resumeLast: true, autonomy } : null;
+  }
+  if (!h.resume.idShape.test(id) || !isUsableSessionId(id)) return null;
+
+  // D-011: any OTHER id-shaped token means the command is ambiguous -
+  // refuse rather than resume a stranger.
+  const idShaped = words.filter((w) => w !== id && h.resume.idShape.test(w));
+  if (idShaped.length > 0) return null;
+
+  return { harness: h.name, sessionId: id, autonomy };
+};

package/src/interpretation/presence.ts

@@ -0,0 +1,49 @@
+/**
+ * Presence: does an INTERACTIVE process for this session id exist in the
+ * given process listing? Pure over injected rows - the host polls `ps` and
+ * feeds rows in. Presence says a process exists; it never creates a tap,
+ * never proves a channel, and never decides attachment (that is the chat
+ * layer's liveness state machine). Known blind spot, inherent to argv
+ * matching and shared with v1: an interactive session whose argv carries no
+ * id (`claude --continue`) is invisible here - false-negative is the safe
+ * direction, because presence only ever corroborates.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { basenameOf, tokenize } from "./shape.js";
+
+export interface ProcessRow {
+  readonly argv: string;
+}
+
+const idBearingFlags = (h: HarnessDescriptor): readonly string[] => [
+  h.resume.flag,
+  ...h.resume.aliases,
+  ...(h.sessionMode === null ? [] : [h.sessionMode.idFlag]),
+  // muse's interactive process IS `muse resume <id>` - the parse-only
+  // spelling is exactly what a live interactive argv looks like.
+  ...(h.resume.positionalParseWord === undefined ? [] : [h.resume.positionalParseWord]),
+];
+
+export const isInteractive = (
+  h: HarnessDescriptor,
+  sessionId: string,
+  rows: readonly ProcessRow[],
+): boolean => {
+  const flags = idBearingFlags(h);
+  return rows.some((row) => {
+    // Cheap rejection before tokenizing: most ps rows are unrelated.
+    if (!row.argv.includes(sessionId)) return false;
+    const words = tokenize(row.argv);
+    const bin = words[0];
+    // ps reports the resolved path (/usr/local/bin/claude), not the bare bin.
+    if (bin === undefined || basenameOf(bin) !== h.bin) return false;
+    // The id must be the VALUE of an id-bearing flag - an id-shaped word in
+    // prompt text is not presence.
+    const bound = flags.some((flag) => {
+      const at = words.indexOf(flag);
+      return at !== -1 && words[at + 1] === sessionId;
+    });
+    if (!bound) return false;
+    return !h.presence.headlessMarkers.some((marker) => words.includes(marker));
+  });
+};

package/src/interpretation/resume-last.ts

@@ -0,0 +1,93 @@
+/**
+ * resumeLast corroboration (the codex --last race): given the candidate
+ * sessions a store scan produced, rank them by evidence and choose only
+ * when the evidence actually distinguishes them. Two candidates the
+ * ranking cannot tell apart is a refusal the caller must surface - "most
+ * recent" over a race window is a guess, and a guess resumes a stranger.
+ *
+ * cwd corroboration compares path STRINGS (trailing slashes normalized);
+ * canonicalization (symlinks, /tmp vs /private/tmp) is the caller's job at
+ * the impure boundary - harnesses record resolved paths, so pass resolved
+ * paths in.
+ */
+
+export interface ResumeCandidate {
+  readonly id: string;
+  readonly mtimeMs: number;
+  readonly cwd: string;
+}
+
+export type ResumeLastVerdict =
+  | { readonly kind: "chosen"; readonly id: string; readonly ranked: readonly string[] }
+  | { readonly kind: "ambiguous"; readonly candidates: readonly string[]; readonly reason: string }
+  | { readonly kind: "none" };
+
+/** Two same-tier candidates whose mtimes are closer than this cannot be
+ * distinguished by recency - filesystem timestamps race at this scale. */
+const RECENCY_EPSILON_MS = 2_000;
+
+const normalizePath = (p: string): string => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+
+export const rankResumeLast = (
+  candidates: readonly ResumeCandidate[],
+  context: { readonly cwd: string },
+): ResumeLastVerdict => {
+  const cwd = normalizePath(context.cwd);
+
+  // A store scan can surface one session twice (rotated file, symlinked
+  // root); duplicates are one candidate, not an ambiguity. Keep the best
+  // evidence per id: cwd match wins, then the newest mtime.
+  const byId = new Map<string, ResumeCandidate>();
+  for (const candidate of candidates) {
+    const held = byId.get(candidate.id);
+    if (held === undefined) {
+      byId.set(candidate.id, candidate);
+      continue;
+    }
+    const heldMatch = normalizePath(held.cwd) === cwd;
+    const nextMatch = normalizePath(candidate.cwd) === cwd;
+    if (
+      (nextMatch && !heldMatch) ||
+      (nextMatch === heldMatch && candidate.mtimeMs > held.mtimeMs)
+    ) {
+      byId.set(candidate.id, candidate);
+    }
+  }
+
+  const unique = [...byId.values()];
+  if (unique.length === 0) return { kind: "none" };
+
+  const tierOf = (c: ResumeCandidate): number => (normalizePath(c.cwd) === cwd ? 0 : 1);
+  const ranked = unique.sort((x, y) => {
+    const tier = tierOf(x) - tierOf(y);
+    if (tier !== 0) return tier;
+    return y.mtimeMs - x.mtimeMs;
+  });
+
+  const first = ranked[0];
+  if (first === undefined) return { kind: "none" };
+  if (!Number.isFinite(first.mtimeMs)) {
+    return {
+      kind: "ambiguous",
+      candidates: ranked.map((c) => c.id),
+      reason: "candidate timestamps are unusable (non-finite mtime) - refusing to guess",
+    };
+  }
+
+  // Every same-tier candidate within the epsilon of the winner is part of
+  // the ambiguity - reporting only two of N hides contenders.
+  const contenders = ranked.filter(
+    (c) =>
+      c !== first &&
+      tierOf(c) === tierOf(first) &&
+      (!Number.isFinite(c.mtimeMs) || Math.abs(first.mtimeMs - c.mtimeMs) < RECENCY_EPSILON_MS),
+  );
+  if (contenders.length > 0) {
+    return {
+      kind: "ambiguous",
+      candidates: [first.id, ...contenders.map((c) => c.id)],
+      reason: `${contenders.length + 1} candidates share the same corroboration tier within ${RECENCY_EPSILON_MS}ms - refusing to guess`,
+    };
+  }
+  return { kind: "chosen", id: first.id, ranked: ranked.map((c) => c.id) };
+};

package/src/interpretation/session-id.ts

@@ -0,0 +1,35 @@
+/**
+ * The shape a harness session id must have before it is believed. Ported
+ * from lucid v1 core/session-id.ts: a discovered id comes from the harness's
+ * own stdout - the least trusted input in the flow - and is later substituted
+ * into resume argv and filesystem paths. Bounding length and stripping
+ * control characters is not enough: an id of `--dangerously-skip-permissions`
+ * is printable and short, and would be handed to the CLI as a FLAG; an id of
+ * `../../etc/passwd` is a path traversal. An id is an opaque token: letters,
+ * digits, and the few separators real harnesses use, never leading with a
+ * dash or a dot.
+ */
+
+export const SESSION_ID_MAX = 128;
+
+const SESSION_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:@-]*$/;
+
+/** True when this id may be believed, placed into resume argv, or used as a
+ * path segment. */
+export const isUsableSessionId = (value: string): boolean =>
+  value.length > 0 && value.length <= SESSION_ID_MAX && SESSION_ID_SHAPE.test(value);
+
+/** Raised when a session id fails the shape rule at a boundary that cannot
+ * return null (argv building, store-path resolution). */
+export class SessionIdRefusalError extends Error {
+  constructor(value: string) {
+    super(
+      `session id ${JSON.stringify(value.slice(0, 64))} is not a usable id: must match ${String(SESSION_ID_SHAPE)} and be at most ${SESSION_ID_MAX} chars`,
+    );
+    this.name = "SessionIdRefusalError";
+  }
+}
+
+export const assertUsableSessionId = (value: string): void => {
+  if (!isUsableSessionId(value)) throw new SessionIdRefusalError(value);
+};

package/src/interpretation/session-input.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure validation and encoding for descriptor-declared persistent-session
+ * input. This module owns supported wire records, not process I/O.
+ */
+import type {
+  HarnessDescriptor,
+  SessionInputContract,
+  SessionInputKind,
+} from "../knowledge/descriptor.js";
+import { SESSION_INPUT_KINDS } from "../knowledge/descriptor.js";
+import { asRecord } from "./shape.js";
+
+export type SessionInputIssue = "missing-session-input-contract" | "unsupported-session-input-kind";
+
+export class SessionInputRefusalError extends Error {
+  constructor(readonly issue: SessionInputIssue) {
+    super(`session input refused: ${issue}`);
+    this.name = "SessionInputRefusalError";
+  }
+}
+
+const isSessionInputKind = (value: unknown): value is SessionInputKind =>
+  SESSION_INPUT_KINDS.some((kind) => kind === value);
+
+export const resolveSessionInput = (harness: HarnessDescriptor): SessionInputContract => {
+  const sessionMode = asRecord(harness.sessionMode);
+  const input = asRecord(sessionMode?.input);
+  if (input === null || !("kind" in input)) {
+    throw new SessionInputRefusalError("missing-session-input-contract");
+  }
+  if (!isSessionInputKind(input.kind)) {
+    throw new SessionInputRefusalError("unsupported-session-input-kind");
+  }
+  return { kind: input.kind };
+};
+
+export const encodeSessionInput = (input: SessionInputContract, text: string): string => {
+  switch (input.kind) {
+    case "claude-sdk-user-message":
+      return `${JSON.stringify({
+        type: "user",
+        message: { role: "user", content: [{ type: "text", text }] },
+      })}\n`;
+  }
+};

package/src/interpretation/shape.ts

@@ -0,0 +1,55 @@
+/**
+ * Tiny shared shape helpers for the interpretation layer. They exist so the
+ * unsafe cast to Record and the shell-word splitter each have exactly one
+ * owner - quoting rules live in tokenize, not at call sites.
+ */
+
+export const asRecord = (value: unknown): Record<string, unknown> | null =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+
+/**
+ * Split a command line into shell words: whitespace separates, single or
+ * double quotes group (so a flag inside quoted prompt text stays part of
+ * that one word and can never be mistaken for a real flag - the D-011
+ * resume-anchoring rule depends on this).
+ */
+export const tokenize = (command: string): string[] => {
+  const words: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let inWord = false;
+  for (const ch of command) {
+    if (quote !== null) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      inWord = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      if (inWord) {
+        words.push(current);
+        current = "";
+        inWord = false;
+      }
+      continue;
+    }
+    current += ch;
+    inWord = true;
+  }
+  if (inWord) words.push(current);
+  return words;
+};
+
+/** The final path segment of a command word, without importing node:path -
+ * argv[0] arrives as `claude`, `/usr/local/bin/claude`, or similar. */
+export const basenameOf = (word: string): string => {
+  const at = word.lastIndexOf("/");
+  return at === -1 ? word : word.slice(at + 1);
+};

package/src/interpretation/store.ts

@@ -0,0 +1,43 @@
+/**
+ * Store-path resolution: where a harness files the transcript for a session,
+ * resolved purely from descriptor template data - the tail reader in the
+ * execution layer consumes this, it is never guessed at a call site. The
+ * session id is shape-checked before it becomes a path segment (a traversal
+ * id must never reach the filesystem), and replacements are literal - no
+ * `$&` pattern semantics from String.replace.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { assertUsableSessionId } from "./session-id.js";
+
+export interface StorePathInputs {
+  readonly home: string;
+  readonly cwd: string;
+  readonly sessionId: string;
+}
+
+const slugFor = (h: HarnessDescriptor, cwd: string): string => {
+  const normalized = cwd.length > 1 ? cwd.replace(/\/+$/, "") : cwd;
+  switch (h.store.cwdSlug) {
+    case "dash-separators":
+      return normalized.replace(/[/.]/g, "-");
+    case "pi-dash-wrapped":
+      // pi 0.84.1, verified on-disk: leading slash stripped, '/' -> '-',
+      // dots preserved, wrapped in double dashes:
+      // /Users/kevin/dev/x -> --Users-kevin-dev-x--
+      return `--${normalized.replace(/^\//, "").replace(/\//g, "-")}--`;
+    case "verbatim":
+      return normalized;
+    default: {
+      const exhaustive: never = h.store.cwdSlug;
+      return exhaustive;
+    }
+  }
+};
+
+export const storePath = (h: HarnessDescriptor, inputs: StorePathInputs): string => {
+  assertUsableSessionId(inputs.sessionId);
+  return h.store.template
+    .replaceAll("{home}", () => inputs.home)
+    .replaceAll("{cwdSlug}", () => slugFor(h, inputs.cwd))
+    .replaceAll("{sessionId}", () => inputs.sessionId);
+};

package/src/interpretation/versions.ts

@@ -0,0 +1,43 @@
+/**
+ * Version comparison for the harness-update pipeline: compare a descriptor's
+ * `verifiedAgainst` against the latest published version to decide whether
+ * the descriptor's facts are stale. Pure and dotted-numeric: prerelease and
+ * build suffixes are split on and compared numerically where present, else
+ * ignored - the signal is "a newer version shipped", not full semver
+ * precedence.
+ */
+
+export type VersionStatus = "ok" | "behind" | "ahead" | "unknown";
+
+const parse = (v: string): number[] =>
+  v
+    .trim()
+    .split(/[.\-+]/)
+    .map((p) => Number.parseInt(p, 10))
+    .filter((n) => !Number.isNaN(n));
+
+/** -1 if a < b, 0 if equal, 1 if a > b, comparing dotted-numeric parts with
+ * missing trailing parts treated as 0. */
+export const compareVersions = (a: string, b: string): -1 | 0 | 1 => {
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+};
+
+/** Where `verified` stands relative to `latest`. `unknown` when either is
+ * absent or has no numeric parts (so a wrong descriptor never reads as ok). */
+export const versionStatus = (verified: string, latest: string | null): VersionStatus => {
+  if (latest === null) return "unknown";
+  if (parse(verified).length === 0 || parse(latest).length === 0) return "unknown";
+  const cmp = compareVersions(verified, latest);
+  if (cmp < 0) return "behind"; // a newer version has shipped - descriptor unverified for it
+  if (cmp > 0) return "ahead"; // verified newer than the published latest (unexpected)
+  return "ok";
+};

package/src/interpretation/vocabulary.ts

@@ -0,0 +1,74 @@
+/**
+ * Model/effort vocabulary: pure checks of a caller's selector against the
+ * descriptor's curated vocabulary, resolving aliases to the harness's own
+ * spelling. Rejections name the accepted vocabulary so the refusal is
+ * actionable without reading the descriptor. Resolution lives in ONE place
+ * (resolveModel) so validation and capability claims cannot drift.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+
+export type Validated = { readonly ok: true; readonly id: string } | ValidationRefusal;
+
+export interface ValidationRefusal {
+  readonly ok: false;
+  readonly reason: string;
+}
+
+/** The selector grammar an extensible registry still demands: pi documents
+ * models as provider/id[:thinking], so word characters plus the few real
+ * separators - never whitespace, shell metacharacters, or control/format
+ * characters, and bounded like session ids. */
+const CLEAN_SELECTOR = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,127}$/;
+
+export interface ResolvedModel {
+  readonly id: string;
+  readonly curated: boolean;
+}
+
+/** Alias-resolve a model selector. Object.hasOwn guards the alias lookup -
+ * "__proto__" must resolve to itself, not to Object.prototype. */
+export const resolveModel = (h: HarnessDescriptor, model: string): ResolvedModel => {
+  const trimmed = model.trim();
+  const aliased = Object.hasOwn(h.vocabulary.aliases, trimmed)
+    ? h.vocabulary.aliases[trimmed]
+    : undefined;
+  const id = aliased ?? trimmed;
+  return { id, curated: h.vocabulary.models.includes(id) };
+};
+
+export const validateModel = (h: HarnessDescriptor, model: string): Validated => {
+  const { id, curated } = resolveModel(h, model);
+  if (curated) return { ok: true, id };
+  if (h.vocabulary.extensible) {
+    // D-008: the registry is runtime-extensible - accept any CLEAN unknown
+    // selector; capability claims for it degrade separately.
+    if (CLEAN_SELECTOR.test(id)) return { ok: true, id };
+    return {
+      ok: false,
+      reason: `model selector ${JSON.stringify(model)} for ${h.bin} is blank, flag-shaped, over-long, or carries whitespace/control/shell characters`,
+    };
+  }
+  return {
+    ok: false,
+    reason: `unknown ${h.bin} model ${JSON.stringify(model)}; accepted: ${h.vocabulary.models.join(", ")} (aliases: ${Object.keys(h.vocabulary.aliases).join(", ")})`,
+  };
+};
+
+/** Validate an effort against the ladder that applies to the pick: the
+ * model's own ladder where the harness constrains per model (codex), else
+ * the harness-wide ladder. */
+export const validateEffort = (h: HarnessDescriptor, effort: string, model?: string): Validated => {
+  let ladder = h.vocabulary.efforts;
+  if (model !== undefined && h.vocabulary.effortsByModel !== undefined) {
+    const { id } = resolveModel(h, model);
+    const perModel = Object.hasOwn(h.vocabulary.effortsByModel, id)
+      ? h.vocabulary.effortsByModel[id]
+      : undefined;
+    if (perModel !== undefined) ladder = perModel;
+  }
+  if (ladder.includes(effort)) return { ok: true, id: effort };
+  return {
+    ok: false,
+    reason: `unknown ${h.bin} effort ${JSON.stringify(effort)}${model === undefined ? "" : ` for model ${JSON.stringify(model)}`}; ladder: ${ladder.join(" < ")}`,
+  };
+};