@gamaze/hicortex 0.22.3 → 0.23.1

package/dist/distiller.js

@@ -10,10 +10,12 @@ exports.extractConversationText = extractConversationText;
 exports.distillSession = distillSession;
 exports.isNoExtractResponse = isNoExtractResponse;
 exports.hasMinimalSubstance = hasMinimalSubstance;
+exports.isVolatileStatusEntry = isVolatileStatusEntry;
 exports.typeFromTag = typeFromTag;
 exports.parseDistilledEntries = parseDistilledEntries;
 const prompts_js_1 = require("./prompts.js");
 const redact_js_1 = require("./redact.js");
+const calibration_js_1 = require("./calibration.js");
 const MAX_TRANSCRIPT_CHARS = 80_000;
 const MIN_CONVERSATION_CHARS = 200;
 // #339 (2026-08-24 postmortem): NO_EXTRACT over-firing visibility threshold.
@@ -403,21 +405,36 @@ async function distillChunk(llm, transcript, projectName, date, onUsage) {
         console.log(`[hicortex]     topic-first check: ${offTopic}/${parsed.length} entries look actor/bracket-led (prompt may be ignored)`);
     }
     const entries = [];
-    const dropped = [];
+    const substanceDropped = [];
+    const volatileDropped = [];
     for (const entry of parsed) {
-        if (hasMinimalSubstance(entry.content)) {
-            entries.push(entry);
+        if (!hasMinimalSubstance(entry.content)) {
+            substanceDropped.push(entry.content);
+            continue;
         }
-        else {
-            dropped.push(entry.content);
+        // #489 volatility gate (owner decision 2: entry-level, deterministic,
+        // beside the substance gate — cleanMessageContent untouched): GH-ticket /
+        // version-bump / commit-state status shapes drop into the SAME #156
+        // trail (owner decision 1: mark-and-skip, never silent). Kill-switch =
+        // the release-managed calibration constant (owner decision 5).
+        if (calibration_js_1.VOLATILE_STATUS_FILTER && isVolatileStatusEntry(entry.content)) {
+            volatileDropped.push(entry.content);
+            continue;
         }
+        entries.push(entry);
     }
-    if (dropped.length > 0) {
-        for (const d of dropped) {
+    const dropped = [...substanceDropped, ...volatileDropped];
+    for (const [label, list] of [
+        ["Substance gate", substanceDropped],
+        ["Volatility gate", volatileDropped],
+    ]) {
+        if (list.length === 0)
+            continue;
+        for (const d of list) {
             const preview = d.length > 120 ? `${d.slice(0, 120)}…` : d;
-            console.log(`[hicortex]     Substance gate: dropped "${preview}"`);
+            console.log(`[hicortex]     ${label}: dropped "${preview}"`);
         }
-        console.log(`[hicortex]     Substance gate: dropped ${dropped.length}/${parsed.length} content-free fragment(s)`);
+        console.log(`[hicortex]     ${label}: dropped ${list.length}/${parsed.length} entr(ies)`);
     }
     // Parsed-zero bypass (#339 CR finding 2): a non-empty response with no
     // NO_EXTRACT token that still parses to zero bullets is the silent twin of
@@ -508,6 +525,74 @@ function hasMinimalSubstance(entry) {
         return false;
     return true;
 }
+// ---------------------------------------------------------------------------
+// Volatility gate (#489) — deterministic, entry-level, beside the substance
+// gate. Owner directive (gold-set A adjudication): GitHub ticket/workflow
+// states and version numbers churn faster than nightly consolidation retires
+// them — they arrive as supersession noise and inflate the store with
+// same-subject rows. The ephemera PROMPT already names these categories and
+// demonstrably under-fires (a month of it running, gold A still full of
+// GH-status/version rows) — so the filter is deterministic, catching entries
+// synthesized from ANY source prose.
+// ---------------------------------------------------------------------------
+/**
+ * Durability escapes — decision/policy predicates that OVERRIDE every
+ * volatility trigger (#489 spec): "switched from X to Y" is a durable model
+ * choice even though it names two versions; a version boundary is a policy
+ * even though it cites one. Whole-word, case-insensitive. Version numbers
+ * never trigger alone — version + STATUS-verb triggers; version +
+ * DECISION-verb escapes.
+ */
+const VOLATILE_ESCAPES = /\b(?:switch(?:ed)?\s+from|adopt(?:ed)?|standardi[sz]ed|deprecated|polic(?:y|ies)|rule|boundary|convention|must|never|always|only\s+when)\b/i;
+/** T1 — GH ticket/workflow status: a #number ticket + a status predicate, or
+ *  a workflow-run shape (checks/CI outcome, test-count status). */
+const TICKET_REF = /(?:^|[\s(#])(?:pr|issue|epic)?\s*#\d+/i;
+const TICKET_STATUS = /\b(?:merged?|closed?|reopened?|opened?|approved?|blocked?|failing|pass(?:ed|ing)?|green|red|ready|draft)\b/i;
+const WORKFLOW_STATUS = /\b(?:checks?\s+(?:passed|failed|green|red)|ci\s+(?:green|red)|\d+\s+tests?\s+(?:pass(?:ed|ing)?|fail(?:ed|ing)?))\b/i;
+/** T2 — version-bump status: a semver-ish number + a release verb, or a
+ *  version→version transition. The `\b` boundary keeps "Qwen3.6" (no
+ *  boundary between n and 3) from matching — model names are not versions. */
+const SEMVERISH = /\bv?\d+\.\d+(?:\.\d+)?\b/;
+const RELEASE_VERB = /\b(?:released?|deployed?|promoted?|published?|tagged?|bumped?|cut|shipped?|rolled?\s+out|dist-tags?)\b/i;
+const VERSION_TRANSITION = /\bv?\d+\.\d+(?:\.\d+)?\b[^.\d]{0,20}(?:→|->|to)\s*v?\d+\.\d+(?:\.\d+)?\b/i;
+/** T3 — branch/commit state: a short sha (7-40 hex, word-bounded) + a
+ *  vcs-motion verb. The SHA is the discriminator, so the verb list is bare
+ *  ("rebased feature branch onto 4f9c1ab" must fire); a durable narrative
+ *  carrying a sha + verb rides the escape list or the length cap. */
+const SHORT_SHA = /\b[0-9a-f]{7,40}\b/;
+const VCS_STATE = /\b(?:pushed?|merged?|rebased?|force-?pushed?|updated?)\b/i;
+/**
+ * True when the entry is a VOLATILE STATUS SHAPE — GH-ticket/workflow status,
+ * version-bump status, or branch/commit state — and carries no durability
+ * escape (#489, owner decisions 1+2). Runs in distillChunk's gate zone beside
+ * hasMinimalSubstance; drops ride the SAME #156 dropped[] trail. Also reused
+ * verbatim by `hicortex sweep-volatile` over the stored corpus — ONE gate,
+ * one meaning.
+ *
+ * PRECISION OVER RECALL (the substance gate's law, inherited): escapes are
+ * checked FIRST and override every trigger; entries longer than
+ * VOLATILE_GATE_MAX_CHARS are treated as mixed prose whose status clause is
+ * not the DOMINANT content (kept). Accepted false-positive mode, stated
+ * plainly: an entry pairing a status clause with a distinct durable clause
+ * and no escape word drops, losing the durable half — unless the distiller
+ * emitted that half as its own entry, which is exactly what the ephemera
+ * prompt tells it to do. Every drop is auditable via the trail.
+ */
+function isVolatileStatusEntry(entry) {
+    const raw = entry.trim();
+    if (!raw || raw.length > calibration_js_1.VOLATILE_GATE_MAX_CHARS)
+        return false;
+    if (VOLATILE_ESCAPES.test(raw))
+        return false;
+    const ticketStatus = TICKET_REF.test(raw) && TICKET_STATUS.test(raw);
+    const workflowStatus = WORKFLOW_STATUS.test(raw);
+    // A version number + release verb, OR a bare version→version transition
+    // (the transition fires without a verb — "0.22.2 → 0.22.3 on rc" is a
+    // version-bump status; the escape list carries the durable flips).
+    const versionBump = (SEMVERISH.test(raw) && RELEASE_VERB.test(raw)) || VERSION_TRANSITION.test(raw);
+    const commitState = SHORT_SHA.test(raw) && VCS_STATE.test(raw);
+    return ticketStatus || workflowStatus || versionBump || commitState;
+}
 /**
  * Map a single-letter type tag to the stored memory_type. Unknown/absent →
  * experience (the pre-#216 default). `[L]` is explicitly rejected →

package/dist/eval/planted-harness.js

@@ -644,7 +644,7 @@ function renderPlantedReport(args) {
         `- conflicts (guard-C): flagged ${s.conflict_flagged}, skipped ${s.conflict_skipped} ` +
         `(zone clusters + judged merges refused on a conflicts link)\n` +
         `- zone: clusters_found ${s.merges.clusters_found}, merged ${s.merges.merged_clusters}, ` +
-        `losers_merged ${s.merges.losers_merged}, metadata_skipped ${s.merges.skipped_metadata_mismatch}, ` +
+        `losers_merged ${s.merges.losers_merged}, project_skipped ${s.merges.skipped_project_mismatch}, ` +
         `conflict_skipped ${s.merges.skipped_conflict}\n` +
         `- skipped: infra ${s.skipped_infra}, idempotent ${s.skipped_idempotent}, above_ceiling ${s.skipped_above_ceiling}\n`);
     return L.join("\n");

package/dist/eval/run-eval.js

@@ -66,11 +66,9 @@ function renderDups(d) {
         `${d.pairAttribution.recoveryReingest} recovery/re-ingest-suspect (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.recoveryReingest / d.pairAttribution.totalPairs : 0)}), ${d.pairAttribution.organic} organic (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.organic / d.pairAttribution.totalPairs : 0)}).\n`);
     lines.push(`### Top ${d.topClusters.length} clusters (0.90 threshold, largest first)\n`);
     d.topClusters.forEach((cluster, i) => {
+        // #206 decision 2: project is the only merge-safety rail (agent rail removed).
         const mismatch = cluster.metadataMismatch;
-        const mismatchFlags = [
-            mismatch.projectMismatch ? "project" : null,
-            mismatch.sourceAgentMismatch ? "source_agent" : null,
-        ].filter(Boolean);
+        const mismatchFlags = [mismatch.projectMismatch ? "project" : null].filter(Boolean);
         lines.push(`**Cluster ${i + 1}** — size ${cluster.size}, attribution: ${cluster.attribution.recoveryReingest} recovery-pair(s) / ${cluster.attribution.organic} organic-pair(s)` +
             (mismatchFlags.length > 0 ? `, metadata mismatch: ${mismatchFlags.join(", ")}` : ", metadata consistent"));
         for (const m of cluster.members) {

package/dist/llm.d.ts

@@ -237,9 +237,20 @@ export declare class LlmClient {
     private acquireFlightGuard;
     private dispatchOnce;
     /**
-     * Claude CLI: shell out to `claude -p` for subscription users.
+     * Claude CLI: invoke `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
      *
+     * Invocation contract (#512): the binary is called with a plain argument
+     * array and NO shell; the prompt travels on the child's stdin (execFileSync
+     * pipes stdin when `input` is set — the `< /dev/null` of the old shell
+     * command line is gone with the shell). The prompt is transcript-derived
+     * data, so it must reach the binary as bytes, never as command-line text
+     * an intermediary could interpret; argv stays exactly the fixed flag set.
+     * Side effects: stdin delivery lifts the per-argument exec limit on long
+     * transcripts, and a claudePath containing spaces works (one argv element,
+     * never re-parsed). cwd is left unset on purpose — the child inherits
+     * process.cwd() like every other phase of the daemon.
+     *
      * Token usage (#246): the claude CLI JSON output does not carry a token
      * usage field, so this path returns `usage: undefined`. The CLI is billed
      * by Claude subscription, not per-token — there is nothing to meter. The

package/dist/llm.js

@@ -570,9 +570,20 @@ class LlmClient {
         return this.completeOpenAiCompat(model, prompt, maxTokens, timeoutMs);
     }
     /**
-     * Claude CLI: shell out to `claude -p` for subscription users.
+     * Claude CLI: invoke `claude -p` for subscription users.
      * No API key needed — uses CC's authenticated session.
      *
+     * Invocation contract (#512): the binary is called with a plain argument
+     * array and NO shell; the prompt travels on the child's stdin (execFileSync
+     * pipes stdin when `input` is set — the `< /dev/null` of the old shell
+     * command line is gone with the shell). The prompt is transcript-derived
+     * data, so it must reach the binary as bytes, never as command-line text
+     * an intermediary could interpret; argv stays exactly the fixed flag set.
+     * Side effects: stdin delivery lifts the per-argument exec limit on long
+     * transcripts, and a claudePath containing spaces works (one argv element,
+     * never re-parsed). cwd is left unset on purpose — the child inherits
+     * process.cwd() like every other phase of the daemon.
+     *
      * Token usage (#246): the claude CLI JSON output does not carry a token
      * usage field, so this path returns `usage: undefined`. The CLI is billed
      * by Claude subscription, not per-token — there is nothing to meter. The
@@ -580,10 +591,10 @@ class LlmClient {
      * correct outcome (no meterable cost to defend against).
      */
     async completeClaude(model, prompt, timeoutMs) {
-        const { execSync } = require("node:child_process");
+        const { execFileSync } = require("node:child_process");
         const claudePath = this.config.baseUrl; // baseUrl stores the claude binary path
         try {
-            const raw = execSync(`${claudePath} -p ${JSON.stringify(prompt)} --model ${model} --max-turns 1 --output-format json --no-session-persistence < /dev/null`, { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 });
+            const raw = execFileSync(claudePath, ["-p", "--model", model, "--max-turns", "1", "--output-format", "json", "--no-session-persistence"], { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, input: prompt });
             const data = JSON.parse(raw);
             if (data.is_error) {
                 throw new Error(`Claude CLI error: ${data.result}`);

package/dist/mcp-stdio.d.ts

@@ -42,6 +42,27 @@
  * port: explicit error, never a spawn. A remote target that is down is
  * likewise an explicit error — we never spawn for remote URLs.
  *
+ * Startup retry (#501): a REMOTE target that is unreachable at launch is
+ * TRANSIENT, not fatal — the product case is a client (e.g. Claude Desktop
+ * auto-launched at login) starting before the VPN/DNS that carries the
+ * server URL is up (ENOTFOUND/EAI_AGAIN/ECONNREFUSED/timeouts). The bridge
+ * then keeps the stdio side ALIVE and answers `initialize` IMMEDIATELY
+ * (design B), retrying the upstream connect with backoff (1s→2s→4s… capped
+ * 10s) for a 60s window. Why answer immediately: MCP clients cancel a
+ * pending `initialize` at ~60s (TS SDK DEFAULT_REQUEST_TIMEOUT_MSEC;
+ * Claude Desktop observed cancelling at ~60s in the wild) — a delayed
+ * initialize would lose the session the retry window is meant to save, and
+ * the first tools/list request carries the same ~60s client budget, so the
+ * window deliberately stays at the BOTTOM of the 60–90s range the issue
+ * proposed (evidence + decision: issue #501 design-note comment). The
+ * daemon's initialize-result `instructions` are unknowable while it is down
+ * and are therefore omitted on this path (the pre-#383 shape); tools
+ * handlers await upstream readiness. NEVER retried: 401/403 (auth is not
+ * transient — existing HICORTEX_AUTH_TOKEN hint) and a reachable-but-not-
+ * healthy endpoint (foreign service). Local targets keep the autostart poll
+ * (which already waits 30s). Mid-session SSE reconnect after an established
+ * connection drops is OUT OF SCOPE (#501 follow-up).
+ *
  * STDIO DISCIPLINE: stdout carries ONLY the MCP protocol. Every diagnostic
  * goes to stderr; fatal errors are a one-liner on stderr + non-zero exit
  * (thrown to cli.ts's catch). Cancellation downstream→upstream rides the
@@ -51,6 +72,7 @@
  * upstream request id (a verbatim forward would carry the downstream id,
  * which means nothing to the daemon) — and reject the in-flight bridge call.
  */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 /** Where the bridge target came from — surfaces in the startup diagnostic. */
 export type BridgeTargetSource = "option" | "env" | "config" | "default";
@@ -122,6 +144,16 @@ export interface EnsureDaemonOptions {
  * every fail-path (explicit error, never silent degradation).
  */
 export declare function ensureDaemonReady(target: BridgeTarget, options?: EnsureDaemonOptions): Promise<void>;
+export type StartupFailureKind = "auth" | "foreign" | "transient" | "fatal";
+/**
+ * Classify a startup failure of the upstream connect sequence. Only a REMOTE
+ * target's network-level failure is transient (#501); auth rejections and a
+ * reachable-but-unhealthy endpoint are fatal immediately, and local targets
+ * keep their own autostart-poll semantics.
+ */
+export declare function classifyStartupFailure(err: unknown, target: BridgeTarget): StartupFailureKind;
+/** Backoff step N (0-based): base·2^N, capped — 1s, 2s, 4s, 8s, then the cap. */
+export declare function nextRetryDelayMs(attempt: number, baseMs: number, maxMs: number): number;
 export interface McpStdioOptions extends EnsureDaemonOptions {
     /** Explicit target URL (test seam; normally resolved from env/config). */
     serverUrl?: string;
@@ -129,10 +161,36 @@ export interface McpStdioOptions extends EnsureDaemonOptions {
     authToken?: string;
     /** Injectable downstream transport (test seam; default: real stdio). */
     downstream?: Transport;
+    /** Injectable upstream connect (test seam; default: real SSE transport). */
+    connectUpstream?: (target: BridgeTarget, token: string | undefined) => Promise<Client>;
+    /** Retry pacing for the #501 transient-unreachable window (test seams). */
+    retryWindowMs?: number;
+    retryBaseDelayMs?: number;
+    retryMaxDelayMs?: number;
 }
 /**
- * Run the stdio MCP bridge. Resolves only after the downstream transport
- * closes (the lifecycle handlers then exit the process); every setup failure
- * throws for cli.ts to report on stderr and exit 1.
+ * Connect the upstream Client to the daemon's SSE MCP endpoint. requestInit
+ * headers ride BOTH the GET /sse and the POST /messages (SDK 1.28
+ * _commonHeaders/send). Raw errors propagate — classification happens at the
+ * call site. Exported for the ghost-reconnect unit test.
+ *
+ * On failure the transport is closed EXPLICITLY: the SDK's Client.connect
+ * closes only when the initialize REQUEST fails after a successful start —
+ * a failed transport.start() (refused/DNS) propagates out of Protocol.connect
+ * with no cleanup, and the still-open EventSource keeps eventsource's ~3s
+ * reconnect loop alive. Every retry attempt would leak one ghost that, once
+ * the server appears, opens a REAL authed SSE session on the daemon and is
+ * never closed (proven empirically on SDK 1.28.0 / eventsource 3.0.7, PR
+ * review round 1 — pinned by the ghost-reconnect unit test).
+ */
+export declare function defaultConnectUpstream(target: BridgeTarget, token: string | undefined): Promise<Client>;
+/**
+ * Run the stdio MCP bridge. Fast path (daemon reachable now): connect
+ * upstream first, then serve stdio with the daemon's forwarded instructions
+ * — exactly the pre-#501 sequence. Slow path (REMOTE target, transient
+ * network failure — the boot race): serve stdio IMMEDIATELY (design B,
+ * initialize answered at once) and retry the upstream connect with backoff
+ * for the retry window. Resolves once bridging is established; every setup
+ * failure throws for cli.ts to report on stderr and exit 1.
  */
 export declare function runMcpStdio(options?: McpStdioOptions): Promise<void>;