@dzhechkov/harness-core 0.3.107 → 0.3.108

package/src/feature-adr-routing.ts

@@ -626,3 +626,274 @@ export function mergeOpts<B extends object, E extends object>(base: B, extra: E)
   for (const k in extra) out[k] = (extra as Record<string, unknown>)[k];
   return out as B & E;
 }
+
+// ── CODEX DISPATCH BY DELIVERABLE (ADR-001) ──────────────────────────────────
+//
+// `codex:codex-rescue` is a fire-and-forget Claude WRAPPER: it dispatches to Codex and returns
+// immediately, so its return value is a stub. That is correct for a stage whose deliverable is a
+// FILE written out-of-band (Step 7 code, behind the Step-7.5 landed barrier) and catastrophic for a
+// stage whose deliverable is its RETURN VALUE — a stub reads exactly like a clean review.
+//
+// The workflow script is sandboxed (no `child_process`), so it cannot shell out to `codex exec`
+// itself. An ordinary Claude agent runs the command and returns Codex's stdout verbatim: the agent
+// is the shell.
+
+/**
+ * Stages whose deliverable is a FILE written out-of-band, and which already verify the write landed
+ * before trusting the stub. `code` polls `git status` (Step-7.5). `plan` requires its
+ * `06_implementation_plan.md` to appear and otherwise falls back to the Claude planner — it never
+ * fabricates. Both are legitimate wrapper users; everything else returns its deliverable.
+ */
+const WRAPPER_STAGES: Record<string, number> = { code: 1, plan: 1 };
+
+export type CodexDispatch = 'wrapper' | 'exec';
+
+/** Dispatch by what the stage's deliverable IS, never by which knob named it. */
+export function codexDispatchMode(stage: string): CodexDispatch {
+  return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';
+}
+
+/**
+ * A SANITY bound on prompt size, not a stall guard.
+ *
+ * The earlier 1200-char ceiling was justified by "codex exec stalls on a 55-line payload". Twin
+ * experiments refuted that (2026-07-10): 4000 chars of padding answered in 4s, and a 3156-char /
+ * 56-line adversarial code review answered in 14s. The stalls are INTERMITTENT latency — the same
+ * input hung at 60s and answered at 14s minutes apart. Size is not the variable.
+ *
+ * So the real guard is the bounded timeout plus the CODEX_UNAVAILABLE sentinel: a slow exec becomes
+ * an explicit "unavailable", never a passed review. This constant only stops us from shipping an
+ * absurdly large prompt.
+ */
+export const CODEX_EXEC_PROMPT_CEILING_CHARS = 24_000;
+
+/** The sentinel an exec agent returns when the command failed, timed out, or Codex refused. */
+export const CODEX_UNAVAILABLE = 'CODEX_UNAVAILABLE';
+
+export interface CodexExecPlanInput {
+  readonly stage: string;
+  readonly promptChars: number;
+  readonly probedId: string | null;
+}
+
+export interface CodexExecPlanResult {
+  readonly mode: 'exec' | 'wrapper' | 'claude';
+  readonly reason: string;
+}
+
+/** Decide, before spending an agent, whether Codex can honestly serve this stage. */
+export function codexExecPlan(input: CodexExecPlanInput): CodexExecPlanResult {
+  if (codexDispatchMode(input.stage) === 'wrapper') {
+    return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };
+  }
+  if (!input.probedId) {
+    return { mode: 'claude', reason: 'no codex model id answered the probe' };
+  }
+  if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {
+    return {
+      mode: 'claude',
+      reason:
+        'prompt is ' +
+        input.promptChars +
+        ' chars, over the ' +
+        CODEX_EXEC_PROMPT_CEILING_CHARS +
+        '-char codex exec ceiling (it would stall)',
+    };
+  }
+  return { mode: 'exec', reason: 'codex exec on ' + input.probedId };
+}
+
+/** A model id is user input (`args.codexModel`) and lands in a shell command. Shell-safe ids only. */
+export function isSafeCodexId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id);
+}
+
+/**
+ * A liveness probe. The allowlist says a name is spellable; only this says it answers.
+ *
+ * Found by cross-model review (codex exec, 2026-07-10): the id was interpolated into a shell command
+ * unquoted, so a malformed `args.codexModel` could corrupt or extend the command the agent runs.
+ * Reject anything that is not a plain id, and single-quote it anyway.
+ */
+export function codexProbeCommand(id: string): string | null {
+  if (!isSafeCodexId(id)) return null;
+  return "timeout 60 codex exec -m '" + id + "' 'Reply with exactly: OK'";
+}
+
+export interface CodexProbeOutput {
+  readonly stdout: string;
+  readonly exitCode: number;
+}
+
+export function interpretCodexProbe(out: CodexProbeOutput): boolean {
+  if (out.exitCode !== 0) return false;
+  return /\bOK\b/.test(out.stdout);
+}
+
+/** First id that actually answers. `null` means: route this stage to Claude. */
+export async function pickAvailableCodexId(
+  ids: readonly string[],
+  probe: (id: string) => Promise<boolean>,
+): Promise<string | null> {
+  for (const id of ids) {
+    if (await probe(id)) return id;
+  }
+  return null;
+}
+
+export interface CodexExecResult {
+  readonly ok: boolean;
+  readonly text: string;
+  readonly reason: string;
+}
+
+/**
+ * Risk R2, the most dangerous line in this change: an EMPTY reply must never read as "no findings".
+ * A genuine clean review has to say something. Empty, whitespace, or the sentinel ⇒ not ok ⇒ the
+ * caller falls back to a Claude reviewer.
+ */
+/**
+ * Extract an A–D grade. Cross-model review flagged that "Looks good" would otherwise pass as a
+ * review; a verdict must NAME its grade. No grade ⇒ no verdict ⇒ the caller falls back to Claude.
+ */
+export function parseCodexGrade(text: string): string | null {
+  const m = /\bgrade\s*[:=]?\s*([A-D])\b/i.exec(text);
+  const g = m && m[1] ? m[1] : null;
+  return g ? g.toUpperCase() : null;
+}
+
+export function parseCodexExecResult(text: string | null | undefined): CodexExecResult {
+  const t = typeof text === 'string' ? text.trim() : '';
+  if (t.length === 0) return { ok: false, text: '', reason: 'codex exec returned no text' };
+  if (t.indexOf(CODEX_UNAVAILABLE) !== -1) {
+    return { ok: false, text: t, reason: 'codex exec reported it could not run' };
+  }
+  return { ok: true, text: t, reason: 'codex answered' };
+}
+
+/** CX-3: a workflow that names an agent type the harness does not have must fall back, not die. */
+export function isAgentTypeMissingError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err ?? '');
+  return /agent type .*not found|unknown agent type|no such agent/i.test(msg);
+}
+
+/**
+ * Run a Codex-routed agent so that a missing agent type demotes to `null` (→ the caller's Claude
+ * fallback) instead of throwing and killing the whole run. Any other error still propagates: we do
+ * not want to swallow real bugs behind a fallback.
+ */
+export async function safeCodexAgent<T>(
+  agentFn: (prompt: string, opts: object) => Promise<T>,
+  prompt: string,
+  opts: object,
+  log: (msg: string) => void,
+): Promise<T | null> {
+  try {
+    return await agentFn(prompt, opts);
+  } catch (err) {
+    if (isAgentTypeMissingError(err)) {
+      log('codex: agent type unavailable — falling back to Claude (' + String(err) + ')');
+      return null;
+    }
+    throw err;
+  }
+}
+
+// ── ABSOLUTE ARTIFACT ROOT (ADR-001, absolute-artifact-paths) ────────────────
+//
+// `FDIR` (and `BRAIN`, which derives from the same value) used to be relative, because
+// `args.repo` defaults to `'.'`. A relative path means different things to different agents: once a
+// coder `cd`s elsewhere, a later agent resolves `./features/<slug>/03_adr` against another cwd, finds
+// nothing, and reports a confident FALSE BLOCKER while the artifacts sit at the workflow root.
+//
+// The workflow script is sandboxed — no filesystem, no Node API — so it cannot call `process.cwd()`.
+// The absolute root arrives either as an absolute `args.repo`, or from an agent that runs `pwd`.
+// The resolver below takes `cwd` as a PARAMETER so it is testable without ambient state.
+
+/** True for a POSIX absolute path. */
+export function isAbsolutePosix(p: string): boolean {
+  return typeof p === 'string' && p.charAt(0) === '/';
+}
+
+/**
+ * Collapse `a//b`, `a/./b` and a trailing slash. Deliberately does NOT resolve `..` — a workflow root
+ * containing `..` is a caller error we would rather surface than silently normalise away.
+ */
+export function normalizeRepoPath(p: string): string {
+  const collapsed = p.replace(/\/{2,}/g, '/').replace(/\/\.(?=\/|$)/g, '');
+  const trimmed = collapsed.replace(/\/+$/, '');
+  return trimmed === '' ? '/' : trimmed;
+}
+
+/**
+ * Resolve the artifact root to an absolute path.
+ *
+ * `raw` is `args.repo` (may be `'.'`, `'./x'`, `'x/'`, or already absolute).
+ * `cwd` is the absolute working directory, obtained ONCE from a `pwd` agent — never ambient.
+ * An already absolute `raw` ignores `cwd` entirely (zero agents on that path).
+ */
+export function absolutizeRepo(raw: string, cwd: string): string {
+  const r = typeof raw === 'string' && raw.length > 0 ? raw : '.';
+  if (isAbsolutePosix(r)) return normalizeRepoPath(r);
+  const base = normalizeRepoPath(cwd);
+  const rel = r.replace(/^\.\/+/, '').replace(/^\.$/, '');
+  return rel === '' ? base : normalizeRepoPath(base + '/' + rel);
+}
+
+/** The instruction appended to prompts that embed an artifact path (FR-3). */
+export const ABSOLUTE_PATH_NOTE =
+  ' All artifact paths in this prompt are ABSOLUTE. Read and write them exactly as given; do not cd' +
+  ' first and do not re-relativize them.';
+
+/**
+ * Pick the absolute path out of possibly chatty `pwd` output.
+ *
+ * Cross-model review (codex exec, 2026-07-10) found `.split('\n').pop()` selects the LAST line — so a
+ * `pwd` agent that appends "Done" would degrade the run despite having printed a valid path. Take the
+ * last line that actually looks like an absolute path.
+ */
+export function pickAbsolutePathLine(text: string | null | undefined): string | null {
+  if (typeof text !== 'string') return null;
+  const abs = text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => isAbsolutePosix(l));
+  return abs.length ? (abs[abs.length - 1] as string) : null;
+}
+
+/** `args.repo` may be anything the caller passed. A non-string must not throw on `.replace`. */
+export function coerceRepoArg(raw: unknown): string {
+  return typeof raw === 'string' && raw.length > 0 ? raw.replace(/\/+$/, '') : '.';
+}
+
+
+/**
+ * Round-2 cross-model review (codex exec, 2026-07-10) — three path-safety defects, all real:
+ *   1. `..` segments survived normalisation, so `args.repo='../evil'` produced an absolute-but-unstable
+ *      root. Under the fail-fast stance this is a refusal, not a normalisation.
+ *   2. A newline in `args.repo` could split an embedded path across lines in a prompt.
+ *   3. `SLUG` was concatenated raw: `'../../outside'` escapes the `features/` directory entirely.
+ */
+const UNSAFE_PATH_CHARS = /[\u0000-\u001f\u007f]/;
+const DOT_DOT_SEGMENT = /(^|\/)\.\.(\/|$)/;
+
+export function hasUnsafePathChars(p: string): boolean {
+  return UNSAFE_PATH_CHARS.test(String(p));
+}
+
+export function hasDotDotSegment(p: string): boolean {
+  return DOT_DOT_SEGMENT.test(String(p));
+}
+
+/** The slug names a directory under `features/`. Kebab-case, Latin, max 40 chars — the documented rule. */
+export function isSafeSlug(slug: string): boolean {
+  return typeof slug === 'string' && /^[a-z0-9][a-z0-9-]{0,39}$/.test(slug);
+}
+
+/** Returns an error message, or `null` when the root is safe to embed in a prompt. */
+export function checkArtifactRoot(root: string): string | null {
+  if (!isAbsolutePosix(root)) return 'artifact root is not absolute: ' + JSON.stringify(root);
+  if (hasUnsafePathChars(root)) return 'artifact root contains control characters';
+  if (hasDotDotSegment(root)) return 'artifact root contains a ".." segment: ' + root;
+  return null;
+}

package/src/index.ts

@@ -17,6 +17,8 @@ export type { BundleOptions, BundleResult, BundledSkill } from './bundle.js';
 export * from './targets.js';
 export * from './operations.js';
 export * from './workflows.js';
+export * from './sign.js';
+export * from './skill-schema.js';
 export { createSkill } from './create-skill.js';
 export type { CreateSkillOptions, CreateSkillResult } from './create-skill.js';
 export { checkUpstream, checkAllUpstream, discoverSourcePackages, loadSourcesManifest } from './sync-upstream.js';
@@ -119,8 +121,8 @@ export type { PluginManifest } from './plugin.js';
 export type { SetupOptions, SetupResult, SetupStep } from './setup.js';
 export type { PretrainResult, DetectedTech } from './pretrain.js';
 export type { RecommendationReport, SkillRecommendation } from './recommend.js';
-export { claimCheck, summarize } from './claim-check.js';
-export type { ClaimFinding, ClaimCheckResult } from './claim-check.js';
+export { claimCheck, summarize, decideClaimCheckText, severityCounts, isGated } from './claim-check.js';
+export type { ClaimFinding, ClaimCheckResult, ClaimTextDecision, FailOn } from './claim-check.js';
 export { hookDecision, isFenced, isNewLine, ESCAPE_TEACHING } from './claim-check-hook-policy.js';
 export type { HookDecision, HookDecisionOpts } from './claim-check-hook-policy.js';
 export { step8ClaimGate } from './feature-adr-claim-gate.js';
@@ -159,12 +161,12 @@ export type {
   RecallUsagePatternRow,
   RecallUsageReport,
 } from './recall-usage.js';
-export { discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, orderByDependencies, syncReadmeVersion } from './publish.js';
+export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, orderByDependencies, syncReadmeVersion } from './publish.js';
 export { fetchAllDownloads } from './downloads.js';
 export type { PackageDownloads, DownloadsReport } from './downloads.js';
 export { discoverInstalled, checkUpgrades } from './upgrade.js';
 export type { InstalledSkill, UpgradeCheck, UpgradeReport } from './upgrade.js';
-export type { PublishResult, PublishReport } from './publish.js';
+export type { PublishResult, PublishReport, ProvenanceMode, ProvenanceDecision } from './publish.js';
 export { computeRiskScore } from './risk-scoring.js';
 export type { RiskScore, RiskThresholds } from './risk-scoring.js';
 export {

package/src/publish.ts

@@ -80,6 +80,72 @@ function maxPublished(name: string, localVersion: string): string {
   return pub !== undefined && compareVersions(pub, localVersion) > 0 ? pub : localVersion;
 }
 
+
+// ── npm provenance (ADR-001, publish-provenance) ────────────────────────────
+//
+// Provenance is minted from a GitHub OIDC token during the publish job. There is no private key for us
+// to hold, leak, or rotate — which is why it supersedes the Ed25519 signing key we never generated.
+// It can only be produced where a token can be minted, so the DECISION belongs to the environment, and
+// the decision is a pure function whose output is the exact argv a test can assert.
+
+export type ProvenanceMode = 'auto' | 'on' | 'off';
+
+/**
+ * The facts that mean an OIDC token can actually be minted.
+ *
+ * Cross-model review (codex exec, 2026-07-10): GitHub sets BOTH `ACTIONS_ID_TOKEN_REQUEST_URL` and
+ * `ACTIONS_ID_TOKEN_REQUEST_TOKEN` when `permissions: id-token: write` is granted. Checking only the
+ * URL would pass `--provenance` in a job where minting then fails.
+ *
+ * Honest limit: presence is not proof that a token can be minted (a stale or unreachable URL still
+ * looks capable). npm fails loudly in that case; this guard only prevents the failure we can foresee.
+ */
+export function environmentCanMintProvenance(env: NodeJS.ProcessEnv): boolean {
+  const nonEmpty = (v: string | undefined): boolean => typeof v === 'string' && v.length > 0;
+  return (
+    env.GITHUB_ACTIONS === 'true' &&
+    nonEmpty(env.ACTIONS_ID_TOKEN_REQUEST_URL) &&
+    nonEmpty(env.ACTIONS_ID_TOKEN_REQUEST_TOKEN)
+  );
+}
+
+export interface ProvenanceDecision {
+  readonly useProvenance: boolean;
+  readonly reason: string;
+}
+
+/**
+ * `on` in an environment that cannot mint a token is an ERROR, not a downgrade: failing before the batch
+ * starts beats failing halfway through 45 packages.
+ *
+ * `off` is an escape hatch for a registry outage, and it says so out loud — a safety check the caller can
+ * quietly narrow is not a safety check.
+ */
+export function decideProvenance(mode: ProvenanceMode, env: NodeJS.ProcessEnv): ProvenanceDecision {
+  const capable = environmentCanMintProvenance(env);
+  if (mode === 'off') {
+    return { useProvenance: false, reason: 'provenance disabled explicitly (--no-provenance)' };
+  }
+  if (mode === 'on') {
+    if (!capable) {
+      throw new Error(
+        'dz publish: --provenance requires GITHUB_ACTIONS=true and ACTIONS_ID_TOKEN_REQUEST_URL ' +
+          '(an OIDC token cannot be minted here) — refusing to start the batch',
+      );
+    }
+    return { useProvenance: true, reason: 'provenance forced on (--provenance)' };
+  }
+  return capable
+    ? { useProvenance: true, reason: 'provenance auto-enabled: GitHub Actions with an OIDC token' }
+    : { useProvenance: false, reason: 'provenance auto-disabled: no OIDC token in this environment' };
+}
+
+/** The exact command. A test asserts this string; nothing is assembled inline at the call site. */
+export function publishArgv(mode: ProvenanceMode, env: NodeJS.ProcessEnv): string {
+  const base = 'pnpm publish --access public --no-git-checks';
+  return decideProvenance(mode, env).useProvenance ? base + ' --provenance' : base;
+}
+
 /** Discover all publishable @dzhechkov packages. */
 export function discoverPackages(monorepoRoot: string): { name: string; dir: string; version: string }[] {
   const baseDir = join(monorepoRoot, 'packages', '@dzhechkov');
@@ -219,8 +285,14 @@ export function publishPackages(
      * disables the gate entirely (no `claimCheck` field is emitted).
      */
     claimGate?: 'off' | 'warn' | 'error' | undefined;
+    /** ADR-001: `auto` (default) decides from the environment; `on` fails where it cannot work. */
+    provenance?: ProvenanceMode | undefined;
   } = {},
 ): PublishReport {
+  // Decide ONCE, before the batch: `--provenance` in an incapable environment must fail here, not on
+  // package 7 of 45 (recalled lesson: a failed publish that retries with a bump orphans version numbers).
+  const publishCmd = publishArgv(opts.provenance ?? 'auto', process.env);
+
   const packages = discoverPackages(monorepoRoot);
   const results: PublishResult[] = [];
   const filtered = opts.filter && opts.filter.length > 0
@@ -314,7 +386,7 @@ export function publishPackages(
       }
 
       // Publish
-      execSync('pnpm publish --access public --no-git-checks', {
+      execSync(publishCmd, {
         cwd: pkg.dir,
         stdio: 'pipe',
         encoding: 'utf-8',

package/src/registry.ts

@@ -7,7 +7,7 @@
  * @packageDocumentation
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -82,7 +82,14 @@ export function discoverSkillPackDirs(cwd: string): { pack: string; dir: string
   const out: { pack: string; dir: string }[] = [];
   for (const base of skillPackBaseDirs(cwd)) {
     for (const e of readdirSync(base, { withFileTypes: true })) {
-      if (e.isDirectory() && e.name.startsWith('skills-') && !seen.has(e.name)) {
+      // pnpm links workspace/`node_modules` packages as SYMLINKS, so `isDirectory()` is false for
+      // them and every pack would be skipped — a verifier that checks nothing (cross-model review,
+      // 2026-07-10). Follow a symlink at the PACK-ROOT level only; file hashing below still refuses
+      // to follow symlinks (O_NOFOLLOW).
+      const isPackDir =
+        e.isDirectory() ||
+        (e.isSymbolicLink() && (() => { try { return statSync(join(base, e.name)).isDirectory(); } catch { return false; } })());
+      if (isPackDir && e.name.startsWith('skills-') && !seen.has(e.name)) {
         seen.add(e.name);
         out.push({ pack: e.name, dir: join(base, e.name) });
       }