comisai 1.0.42 → 1.0.45

package/node_modules/@comis/core/dist/text/token-factor.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * scriptTokenFactor(text): the per-script chars-per-token multiplier in (0, 1].
+ *
+ * Every estimator call site divides by `ratio * scriptTokenFactor(text)` where
+ * `text` is the exact string whose `.length` is divided — one rule, every site.
+ *
+ * Combination across script classes is HARMONIC per-row share summation
+ * (`1/f = sum(share_i / f_i)`), NOT an arithmetic mean: tokens add per-class,
+ * so `len/(R*f)` must equal `sum(len_i/(R*f_i))`. Probe evidence: a mixed
+ * Hebrew+Latin string measured 15 real qwen tokens — harmonic estimates 15
+ * exactly, arithmetic estimates 14 (an anti-conservative under-count)
+ * [179-RESEARCH Pattern 3, qwen3-coder:30b probe 2026-06-12].
+ *
+ * Pure function, same purity rules as script-classes.ts: no I/O/clock/env
+ * (I9), no regex (V5). Imported relatively (same-package rule, never via the
+ * @comis/core barrel).
+ * @module
+ */
+import { classifyCodepointToRow } from "./script-classes.js";
+/**
+ * Harmonic share-weighted token factor in (0, 1]; returns 1.0 for
+ * empty/all-neutral/pure-ASCII text (I1 — Latin byte-identity). Shares are
+ * UTF-16 code units (matching the `.length` the estimators divide), weighted
+ * per table ROW (not per class) so combining-mark rows carry their own,
+ * lower factor than the letter rows of the same class.
+ *
+ * Why arithmetic mean is forbidden: tokens add per-class, so
+ * `len/(R*f)` must equal `sum(len_i/(R*f_i))` — i.e. `1/f = sum(share_i/f_i)`
+ * (harmonic). Probe evidence: the mixed he+latin design string measured 15
+ * qwen tokens — harmonic estimates 15 exactly, arithmetic estimates 14
+ * (under-count) [179-RESEARCH Pattern 3, 2026-06-12].
+ */
+export function scriptTokenFactor(text) {
+    // One O(n) pass accumulating per-ROW UTF-16-unit counts (rows, not classes —
+    // the marks rows carry different factors than their letter rows).
+    const rowUnits = new Map();
+    let totalUnits = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 0;
+        const row = classifyCodepointToRow(cp);
+        if (row === null)
+            continue; // neutral ASCII — excluded from shares
+        rowUnits.set(row, (rowUnits.get(row) ?? 0) + ch.length);
+        totalUnits += ch.length;
+    }
+    if (totalUnits === 0)
+        return 1;
+    // Single contributing row: return its factor exactly (avoids the FP
+    // round-trip drift of 1/(1/f) so single-class pins hold strictly).
+    if (rowUnits.size === 1) {
+        for (const row of rowUnits.keys())
+            return row.tokenFactor;
+    }
+    // HARMONIC per-class summation: 1/f = sum(share_i / f_i).
+    let inv = 0;
+    for (const [row, units] of rowUnits) {
+        inv += units / totalUnits / row.tokenFactor;
+    }
+    return Math.min(1, 1 / inv);
+}

package/node_modules/@comis/core/dist/text/trigram-query.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Script-routed FTS5 trigram query construction (FTS-01).
+ *
+ * Routes a query to one of three lanes and, for the trigram lane, builds the
+ * FTS5 MATCH string from untrusted user/model query text:
+ *   - "word": NO non-Latin token → the caller uses the ORIGINAL string against
+ *     the existing porter word lane (I1: byte-identical SQL for all-Latin).
+ *   - "tri":  at least one non-Latin token → a quoted, normalized, bounded
+ *     MATCH expression over the trigram twins.
+ *   - "scan": every non-operator token folds below the 3-codepoint trigram
+ *     floor → the caller runs its bounded normalized scan floor over `scanTokens`.
+ *
+ * DECISION RECORD — Open Question 1 resolved as **Option B**: OR-of-trigram
+ * decomposition ONLY for suffixing-morphology scripts (cyrillic + greek);
+ * whole-quoted tokens for hebrew/arabic/cjk/everything else. A quoted whole
+ * token is FTS5 substring semantics, which fails the pinned Russian criterion
+ * (`книга` is not a substring of stored `книги`); an OR-of-trigrams group
+ * matches it (RESEARCH probe 2, 2026-06-13). he/ar/CJK are prefix/substring
+ * cases the whole-token shape already satisfies (the Hermes production
+ * precedent). Adding a suffixing script later is a data edit to SUFFIXING_SCRIPTS.
+ *
+ * SECURITY (T-180-01-01 / T-180-01-02): every non-operator term is double-quoted
+ * AFTER normalization, operators come only from the exact-uppercase allowlist,
+ * any residual ASCII `"` is stripped from a term before quoting, and the only
+ * parens are builder-emitted (never sourced from user text). MAX_QUERY_TOKENS +
+ * MAX_TRIGRAMS_PER_TOKEN bound the MATCH size; the dangling-operator sweep
+ * eliminates the probe-pinned FTS5 syntax-error shapes. Pure (I9): no I/O.
+ * @module
+ */
+/** The lane a query is routed to. */
+export type SearchLane = "word" | "tri" | "scan";
+export interface TrigramRoute {
+    lane: SearchLane;
+    /** Defined iff lane === "tri" — the complete FTS5 MATCH string. */
+    match?: string;
+    /** Defined iff lane === "scan" — normalized non-operator tokens for the
+     *  bounded floor (includes the <3-codepoint tokens that forced the scan). */
+    scanTokens?: string[];
+}
+/**
+ * Route a query to the word / trigram / scan lane and, for the trigram lane,
+ * build the FTS5 MATCH string.
+ *
+ * join: "and" = space-joined terms (LCD implicit-AND semantics);
+ * join: "or"  = OR-joined terms (LTM buildFtsQuery parity).
+ */
+export declare function routeSearchQuery(query: string, opts: {
+    join: "and" | "or";
+}): TrigramRoute;

package/node_modules/@comis/core/dist/text/trigram-query.js

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Script-routed FTS5 trigram query construction (FTS-01).
+ *
+ * Routes a query to one of three lanes and, for the trigram lane, builds the
+ * FTS5 MATCH string from untrusted user/model query text:
+ *   - "word": NO non-Latin token → the caller uses the ORIGINAL string against
+ *     the existing porter word lane (I1: byte-identical SQL for all-Latin).
+ *   - "tri":  at least one non-Latin token → a quoted, normalized, bounded
+ *     MATCH expression over the trigram twins.
+ *   - "scan": every non-operator token folds below the 3-codepoint trigram
+ *     floor → the caller runs its bounded normalized scan floor over `scanTokens`.
+ *
+ * DECISION RECORD — Open Question 1 resolved as **Option B**: OR-of-trigram
+ * decomposition ONLY for suffixing-morphology scripts (cyrillic + greek);
+ * whole-quoted tokens for hebrew/arabic/cjk/everything else. A quoted whole
+ * token is FTS5 substring semantics, which fails the pinned Russian criterion
+ * (`книга` is not a substring of stored `книги`); an OR-of-trigrams group
+ * matches it (RESEARCH probe 2, 2026-06-13). he/ar/CJK are prefix/substring
+ * cases the whole-token shape already satisfies (the Hermes production
+ * precedent). Adding a suffixing script later is a data edit to SUFFIXING_SCRIPTS.
+ *
+ * SECURITY (T-180-01-01 / T-180-01-02): every non-operator term is double-quoted
+ * AFTER normalization, operators come only from the exact-uppercase allowlist,
+ * any residual ASCII `"` is stripped from a term before quoting, and the only
+ * parens are builder-emitted (never sourced from user text). MAX_QUERY_TOKENS +
+ * MAX_TRIGRAMS_PER_TOKEN bound the MATCH size; the dangling-operator sweep
+ * eliminates the probe-pinned FTS5 syntax-error shapes. Pure (I9): no I/O.
+ * @module
+ */
+import { classifyCodepoint } from "./script-classes.js";
+import { normalizeForSearch } from "./normalize-search.js";
+/**
+ * DoS bound on the token count fed into the MATCH builder. The upstream FTS5
+ * sanitizer does NOT cap token count, so the builder must (RESEARCH Security
+ * Domain — "DoS via pathological queries"). 16 is generous for real queries.
+ */
+const MAX_QUERY_TOKENS = 16;
+/**
+ * DoS bound on the OR-of-trigrams group size for one suffixing-script token.
+ * Covers a ≤14-codepoint word fully; recall is preserved beyond it because any
+ * 3 matching trigrams already rank the document (BM25).
+ */
+const MAX_TRIGRAMS_PER_TOKEN = 12;
+/**
+ * Scripts whose morphology is SUFFIXING — a stem keeps its prefix but changes
+ * its tail across inflections, so substring (quoted whole-token) matching fails
+ * (`книга`/`книги`). These get OR-of-trigram decomposition (OQ-1 Option B).
+ * Everything else (hebrew/arabic/cjk/...) is prefix/substring morphology and
+ * stays whole-quoted. Adding a script here is a one-line data edit.
+ */
+const SUFFIXING_SCRIPTS = new Set(["cyrillic", "greek"]);
+/** The exact-uppercase FTS5 operator allowlist — the ONLY tokens passed
+ *  through bare (a lowercase `and` is a literal search term, not an operator). */
+const OPERATORS = new Set(["AND", "OR", "NOT"]);
+/** ASCII double-quote (built from a codepoint to avoid the string-terminator
+ *  hazard and to keep the quoting site explicit). */
+const DQUOTE = String.fromCodePoint(0x22);
+/** Codepoint count (NOT .length — astral safety for the <3 trigram floor). */
+function codepointLength(s) {
+    let n = 0;
+    for (const _ of s)
+        n += 1;
+    return n;
+}
+/** True if the token contains any codepoint classified as a non-Latin script
+ *  (neutral ASCII — digits/punct — classifies null and never forces routing). */
+function hasNonLatin(token) {
+    for (const ch of token) {
+        const cls = classifyCodepoint(ch.codePointAt(0) ?? 0);
+        if (cls !== null && cls !== "latin")
+            return true;
+    }
+    return false;
+}
+/** True if the token contains any codepoint in a suffixing-morphology script. */
+function hasSuffixingScript(token) {
+    for (const ch of token) {
+        const cls = classifyCodepoint(ch.codePointAt(0) ?? 0);
+        if (cls !== null && SUFFIXING_SCRIPTS.has(cls))
+            return true;
+    }
+    return false;
+}
+/** Sliding window of 3 codepoints, each trigram double-quoted, capped at
+ *  MAX_TRIGRAMS_PER_TOKEN. Astral-safe (operates on the codepoint array). */
+function orOfTrigrams(normalized) {
+    const cps = [...normalized];
+    const trigrams = [];
+    for (let i = 0; i + 3 <= cps.length && trigrams.length < MAX_TRIGRAMS_PER_TOKEN; i += 1) {
+        trigrams.push(quote(cps.slice(i, i + 3).join("")));
+    }
+    return `(${trigrams.join(" OR ")})`;
+}
+/** Double-quote a term for FTS5. The caller has already stripped any interior
+ *  ASCII `"` (so the quotes can never be unbalanced — T-180-01-01). */
+function quote(term) {
+    return DQUOTE + term + DQUOTE;
+}
+/** Strip any residual ASCII double-quote from a term (buildFtsQuery parity —
+ *  hybrid-search.ts:82,90; FTS5 injection prevention). */
+function stripQuotes(s) {
+    let out = "";
+    for (const ch of s) {
+        if (ch !== DQUOTE)
+            out += ch;
+    }
+    return out;
+}
+/**
+ * Re-apply the dangling-operator sweep AFTER token drops can leave an operator
+ * stranded (`ספרים NOT גם` → drop `גם` → trailing `NOT`). The three regexes are
+ * COPIED VERBATIM out of the upstream sanitizer source file
+ * `packages/skills/.../tools/fts5-sanitizer.ts` (step 4, lines 53-59) — a
+ * cross-package import between core and skills is forbidden in both directions,
+ * so the source is duplicated with this citation rather than imported. These are
+ * fixed alternations over a 3-word operator set: no nested quantifiers, no
+ * backtracking surface (T-180-01-02).
+ */
+function sweepDanglingOperators(match) {
+    let working = match;
+    // Remove operators at the start.
+    working = working.replace(/^\s*\b(AND|OR|NOT)\b\s*/i, "");
+    // Remove operators at the end.
+    working = working.replace(/\s*\b(AND|OR|NOT)\b\s*$/i, "");
+    // Collapse adjacent operators (e.g. "query AND OR other" → "query other").
+    working = working.replace(/\b(AND|OR|NOT)\s+(AND|OR|NOT)\b/gi, "");
+    // Trim and collapse whitespace.
+    return working.replace(/\s+/g, " ").trim();
+}
+/**
+ * Tokenize: extract sanitizer-preserved balanced `"…"` phrases as single phrase
+ * tokens (mirror fts5-sanitizer.ts step 1 mechanics, reimplemented locally),
+ * then whitespace-split the remainder into plain tokens. Order is preserved.
+ */
+function tokenize(query) {
+    const tokens = [];
+    let cursor = 0;
+    const text = query;
+    while (cursor < text.length) {
+        const open = text.indexOf(DQUOTE, cursor);
+        if (open === -1) {
+            pushPlain(text.slice(cursor), tokens);
+            break;
+        }
+        const close = text.indexOf(DQUOTE, open + 1);
+        if (close === -1) {
+            // Unbalanced trailing quote — treat the remainder as plain (the upstream
+            // sanitizer strips unbalanced quotes for the LCD lane; be defensive here).
+            pushPlain(text.slice(cursor), tokens);
+            break;
+        }
+        pushPlain(text.slice(cursor, open), tokens);
+        const phrase = text.slice(open + 1, close);
+        if (phrase.trim().length > 0)
+            tokens.push({ kind: "phrase", text: phrase });
+        cursor = close + 1;
+    }
+    return tokens;
+}
+function pushPlain(chunk, tokens) {
+    for (const part of chunk.split(/\s+/)) {
+        if (part.length > 0)
+            tokens.push({ kind: "plain", text: part });
+    }
+}
+/**
+ * Route a query to the word / trigram / scan lane and, for the trigram lane,
+ * build the FTS5 MATCH string.
+ *
+ * join: "and" = space-joined terms (LCD implicit-AND semantics);
+ * join: "or"  = OR-joined terms (LTM buildFtsQuery parity).
+ */
+export function routeSearchQuery(query, opts) {
+    const raw = (query ?? "").trim();
+    if (raw.length === 0)
+        return { lane: "word" };
+    // Step 1: tokenize (phrases kept whole). Step 2: cap at MAX_QUERY_TOKENS.
+    const tokens = tokenize(raw).slice(0, MAX_QUERY_TOKENS);
+    if (tokens.length === 0)
+        return { lane: "word" };
+    // Step 3: all-Latin → word lane (caller uses the ORIGINAL string — I1).
+    const anyNonLatin = tokens.some((t) => hasNonLatin(t.text));
+    if (!anyNonLatin)
+        return { lane: "word" };
+    // Step 4: build the trigram MATCH term-wise. `prevWasNot` carries the
+    // preceding-operator context as a local (no variable array indexing) so a
+    // suffixing-script token directly governed by NOT stays whole-quoted.
+    const terms = [];
+    const scanTokens = [];
+    let positiveTermCount = 0;
+    let prevWasNot = false;
+    for (const token of tokens) {
+        // Operators (exact-uppercase) pass through bare.
+        if (token.kind === "plain" && OPERATORS.has(token.text)) {
+            terms.push(token.text);
+            prevWasNot = token.text === "NOT";
+            continue;
+        }
+        // Normalize the token (or phrase interior) and strip any residual ASCII `"`.
+        const normalized = stripQuotes(normalizeForSearch(token.text));
+        const governedByNot = prevWasNot;
+        prevWasNot = false; // only the token immediately after NOT is governed
+        // A balanced phrase stays ONE whole-quoted phrase (interior normalized,
+        // never re-split even if it now contains spaces — the U+FDFA edge).
+        if (token.kind === "phrase") {
+            scanTokens.push(normalized);
+            if (normalized.length > 0) {
+                terms.push(quote(normalized));
+                positiveTermCount += 1;
+            }
+            continue;
+        }
+        scanTokens.push(normalized);
+        // Drop tokens below the 3-codepoint trigram floor — correctness-critical:
+        // a <3-cp token in an AND context returns ZERO ROWS (RESEARCH probe 3).
+        if (codepointLength(normalized) < 3)
+            continue;
+        // OQ-1 Option B: suffixing-script token (≥4 cp) NOT directly governed by a
+        // preceding NOT → OR-of-trigrams group; else whole-quoted.
+        if (hasSuffixingScript(normalized) && codepointLength(normalized) >= 4 && !governedByNot) {
+            terms.push(orOfTrigrams(normalized));
+        }
+        else {
+            terms.push(quote(normalized));
+        }
+        positiveTermCount += 1;
+    }
+    // Step 5: join. Step 6: sweep dangling operators left by drops.
+    const joiner = opts.join === "and" ? " " : " OR ";
+    const match = sweepDanglingOperators(terms.join(joiner));
+    // Step 7: zero positive terms survived → scan floor (ALL normalized
+    // non-operator tokens, including the short ones that forced the floor).
+    if (positiveTermCount === 0 || match.length === 0) {
+        return { lane: "scan", scanTokens };
+    }
+    return { lane: "tri", match };
+}

package/node_modules/@comis/core/dist/tool-metadata.d.ts

@@ -8,8 +8,9 @@
  * Registry supports incremental registration via spread-merge semantics:
  * different sources can register different fields for the same tool.
  */
+import type { ErrorKind } from "./logging/log-fields.js";
 /**
- * Capability metadata for a builtin/platform tool -- used by the v1.1 capability
+ * Capability metadata for a builtin/platform tool -- used by the capability
  * layer to route tools into clusters and detect install-detour overlap.
  *
  * All fields optional. Operators may override `cluster` per-tool via
@@ -62,8 +63,54 @@ export interface ComisToolMetadata {
     requiredByAction?: Readonly<Record<string, readonly string[]>>;
     /** Pre-flight input validator. Returns error string on failure, undefined on success. */
     validateInput?: (params: Record<string, unknown>) => string | undefined | Promise<string | undefined>;
-    /** Capability metadata for tool-first routing (v1.1). */
+    /** Capability metadata for tool-first routing. */
     capability?: ToolCapabilityMetadata;
+    /** Per-tool MCP-export policy for the /mcp/v1 server endpoint.
+     *  - `"safe"`: exposed to any MCP client with scope `mcp-client` (no allowlist needed).
+     *  - `"permission-gated"`: exposed only when the per-client
+     *    `mcpClient.allowlist` includes this tool name.
+     *  - `"never-export"`: NEVER exposed via the MCP server endpoint.
+     *  - `undefined` ⇒ treated as `"never-export"` (default-deny safety net;
+     *    CI gate enforces that `undefined` is impossible in committed code).
+     *  Spread-merge in `registerToolMetadata` preserves this field across multiple
+     *  registrations for the same tool name. */
+    mcpExportPolicy?: "safe" | "permission-gated" | "never-export";
+    /** When true, this tool's lifecycle produces no activity messages (the
+     *  activity pipeline skips it). Lifecycle reactions + final delivery are
+     *  unaffected. Read by the activity layer (§16.11). */
+    suppressActivity?: boolean;
+    /** When true, a non-zero `details.exitCode` in this tool's RESULT is the DRIVEN
+     *  subject's exit code (informational), NOT the tool's own outcome — so the bridge's
+     *  exit-code failure heuristic (§D1) must NOT flag the call as failed. Set on the
+     *  terminal-driver perception tools (status/read/wait), whose result reports the driven
+     *  session's `exitCode`. Without it a driven program exiting non-zero (e.g. bash `exit 1`)
+     *  misclassifies a perfectly-successful `terminal_session_status` as a tool failure
+     *  (real-VPS 2026-06-16). Default (absent) ⇒ the heuristic applies (exec/process, where
+     *  the exit code IS the tool's outcome). */
+    exitCodeIsDrivenSession?: boolean;
+    /** Tool-specific failure classifier consulted *before* the `tool:executed`
+     *  emit (§16.10), so observability never sees the raw result. Receives the
+     *  tool result and the SDK `isError` flag; returns `true`/`false` (failed or
+     *  not) or `{ errorKind, … }` (failed, with a closed-union classification plus
+     *  optional verdict provenance). Lets a tool flag a logically-failed result
+     *  that the SDK reported as success (e.g. a non-zero exit code). (§16.11).
+     *
+     *  Verdict provenance (P2/D2) — all optional, additive on the contract:
+     *  - `classifiedField`: which STRUCTURED field drove the verdict (never the body).
+     *  - `matchedRule`: the literal regex/rule description that matched (a fixed
+     *    string, not a serialized RegExp and not tool-output data).
+     *  - `matchedToken`: the concrete token that matched (e.g. a status code). This
+     *    is the only provenance field that may carry tool output, so downstream
+     *    sinks (Plan 04) bound it via `sanitizeLogString(...).slice(0, 1500)`. */
+    failureDetector?: (result: unknown, isError: boolean) => boolean | {
+        errorKind: ErrorKind;
+        /** Which structured field drove the verdict (P2/D2). */
+        classifiedField?: "error" | "status" | "message" | "failures";
+        /** The regex/rule literal that matched (P2/D2). */
+        matchedRule?: string;
+        /** The concrete token that matched, e.g. a status code (P2/D2). */
+        matchedToken?: string;
+    };
 }
 /**
  * Register metadata for a tool. Merges with any existing metadata via spread,

package/node_modules/@comis/core/dist/workspace/index.d.ts

@@ -12,7 +12,7 @@
 export { ensureWorkspace, getWorkspaceStatus, registerWorkspaceFilesInTracker, WORKSPACE_SUBDIRS, } from "./workspace-manager.js";
 export type { WorkspaceFiles, EnsureWorkspaceOptions, WorkspaceStatus, WorkspaceSeedTracker, RegisterWorkspaceResult, } from "./workspace-manager.js";
 export { resolveWorkspaceDir } from "./workspace-resolver.js";
-export { WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, TEMPLATE_MARKER, } from "./templates.js";
+export { WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, PLATFORM_OWNED_FILES, USER_OWNED_FILES, TEMPLATE_MARKER, } from "./templates.js";
 export type { WorkspaceFileName } from "./templates.js";
 export { readWorkspaceState, writeWorkspaceState, incrementOnboardingCount, isIdentityFilled, STATE_FILENAME, WorkspaceStateSchema, } from "./workspace-state.js";
 export type { WorkspaceState } from "./workspace-state.js";

package/node_modules/@comis/core/dist/workspace/index.js

@@ -12,5 +12,5 @@
  */
 export { ensureWorkspace, getWorkspaceStatus, registerWorkspaceFilesInTracker, WORKSPACE_SUBDIRS, } from "./workspace-manager.js";
 export { resolveWorkspaceDir } from "./workspace-resolver.js";
-export { WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, TEMPLATE_MARKER, } from "./templates.js";
+export { WORKSPACE_FILE_NAMES, DEFAULT_TEMPLATES, PLATFORM_OWNED_FILES, USER_OWNED_FILES, TEMPLATE_MARKER, } from "./templates.js";
 export { readWorkspaceState, writeWorkspaceState, incrementOnboardingCount, isIdentityFilled, STATE_FILENAME, WorkspaceStateSchema, } from "./workspace-state.js";

package/node_modules/@comis/core/dist/workspace/templates.d.ts

@@ -6,6 +6,23 @@
  */
 export declare const WORKSPACE_FILE_NAMES: readonly ["SOUL.md", "IDENTITY.md", "USER.md", "AGENTS.md", "ROLE.md", "TOOLS.md", "HEARTBEAT.md", "BOOTSTRAP.md", "BOOT.md"];
 export type WorkspaceFileName = (typeof WORKSPACE_FILE_NAMES)[number];
+/**
+ * Platform-owned workspace files — content-hash-refreshed by `ensureWorkspace`
+ * on every invocation when the on-disk sha256 differs from `DEFAULT_TEMPLATES`.
+ *
+ * 2026-05-20 lineage: the prior `wx`-only seed flow let stale pre-fix templates
+ * persist forever, so a sub-agent's inherited workspace kept promising a
+ * pre-warmed venv that no code provisioned. These three files declare themselves
+ * read-only platform contract in their own prose — this partition makes that
+ * contract real.
+ */
+export declare const PLATFORM_OWNED_FILES: readonly ["SOUL.md", "AGENTS.md", "BOOTSTRAP.md"];
+/**
+ * User-owned workspace files — first-write-wins via `writeIfMissing`'s `wx`
+ * flag; never overwritten by `ensureWorkspace` once present on disk. The agent
+ * fills these in during onboarding and continues editing them across sessions.
+ */
+export declare const USER_OWNED_FILES: readonly ["IDENTITY.md", "USER.md", "ROLE.md", "TOOLS.md", "HEARTBEAT.md", "BOOT.md"];
 /** Marker for template-only workspace files (used by isTemplateOnly detection). */
 export declare const TEMPLATE_MARKER = "<!-- COMIS-TEMPLATE -->";
 export declare const DEFAULT_TEMPLATES: Record<WorkspaceFileName, string>;

package/node_modules/@comis/core/dist/workspace/templates.js

@@ -16,6 +16,23 @@ export const WORKSPACE_FILE_NAMES = [
     "BOOTSTRAP.md",
     "BOOT.md",
 ];
+/**
+ * Platform-owned workspace files — content-hash-refreshed by `ensureWorkspace`
+ * on every invocation when the on-disk sha256 differs from `DEFAULT_TEMPLATES`.
+ *
+ * 2026-05-20 lineage: the prior `wx`-only seed flow let stale pre-fix templates
+ * persist forever, so a sub-agent's inherited workspace kept promising a
+ * pre-warmed venv that no code provisioned. These three files declare themselves
+ * read-only platform contract in their own prose — this partition makes that
+ * contract real.
+ */
+export const PLATFORM_OWNED_FILES = ["SOUL.md", "AGENTS.md", "BOOTSTRAP.md"];
+/**
+ * User-owned workspace files — first-write-wins via `writeIfMissing`'s `wx`
+ * flag; never overwritten by `ensureWorkspace` once present on disk. The agent
+ * fills these in during onboarding and continues editing them across sessions.
+ */
+export const USER_OWNED_FILES = ["IDENTITY.md", "USER.md", "ROLE.md", "TOOLS.md", "HEARTBEAT.md", "BOOT.md"];
 /** Marker for template-only workspace files (used by isTemplateOnly detection). */
 export const TEMPLATE_MARKER = "<!-- COMIS-TEMPLATE -->";
 export const DEFAULT_TEMPLATES = {
@@ -126,13 +143,11 @@ This folder is home. Treat it that way.
 
 ## Every Session
 
-Before doing anything else:
-
-1. Read \`SOUL.md\` -- this is who you are
-2. Read \`USER.md\` -- this is who you're helping
-3. Read \`IDENTITY.md\` -- your name, creature, vibe, emoji
-
-Don't ask permission. Just do it.
+\`SOUL.md\` (who you are), \`USER.md\` (who you're helping), and \`IDENTITY.md\`
+(your name, creature, vibe, emoji) are already in your context -- they're
+inlined into this system prompt at session start. Reference them directly.
+Do NOT call the \`read\` tool on them: it wastes a turn and they won't have
+changed since they were loaded.
 
 Your system prompt already includes relevant memories via RAG (Retrieval-
 Augmented Generation). You don't need to manually search for context --
@@ -204,10 +219,9 @@ Capture what matters. The system persists it automatically.
 
 \`\`\`
 projects/    -- Code repos (each in its own subfolder, .venv per repo)
-venv/        -- Pre-warmed Python env (matplotlib, numpy, pandas on PATH).
-                Use venv/bin/python for chart/data work; venv/bin/pip
-                install <pkg> for extras. Per-project venvs go inside
-                projects/<name>/.venv (separate lifecycle).
+venv/        -- Python virtualenv (create on demand with \`python3 -m venv venv\`,
+                then call venv/bin/python3 and venv/bin/pip install <pkgs>).
+                Per-project venvs go inside projects/<name>/.venv.
 scripts/     -- Standalone reusable scripts
 documents/   -- Text docs, PDFs, spreadsheets, markdown
 media/       -- User-provided images, audio, video
@@ -439,7 +453,7 @@ Over the next few messages, figure out together:
 2. **Your nature** -- What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)
 3. **Your vibe** -- Formal? Casual? Snarky? Warm? What feels right?
 4. **Your emoji** -- Everyone needs a signature.
-5. **Your values** -- Read SOUL.md's "Core Truths" for your foundation. What does being comis look like for you?
+5. **Your values** -- SOUL.md's "Core Truths" are already in your context; reference them directly (don't \`read\` the file) for your foundation. What does being comis look like for you?
 
 Take these one at a time. Let each answer shape the next question.
 Offer suggestions if they're stuck. Have fun with it.
@@ -454,7 +468,7 @@ Update these files with what you learned:
 Auto-fill timezone and preferred language from the system context date header
 and the user's message language. Write them to USER.md without asking.
 
-Then open \`SOUL.md\` together and talk about:
+Then talk through SOUL.md's values together (it's already in your context):
 
 - What matters to them
 - How they want you to behave

package/node_modules/@comis/core/dist/workspace/workspace-manager.js

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
-// @allow-throw: ENOENT re-raise inside writeIfMissing 'wx' flag fallback (line 103); EEXIST is the silent-skip path, all other errors propagate. Consumed at workspace-init boundary (CLI wizard + daemon bootstrap, both @allow-throw entry points).
+// @allow-throw: ENOENT re-raise inside writeIfMissing 'wx' flag fallback (line 103); EEXIST is the silent-skip path, all other errors propagate. refreshPlatformFiles propagates fs.rename errors (atomic-write boundary). Consumed at workspace-init boundary (CLI wizard + daemon bootstrap, both @allow-throw entry points).
 import { safePath } from "../security/safe-path.js";
 import { execFile as execFileCb } from "node:child_process";
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import { promisify } from "node:util";
-import { DEFAULT_TEMPLATES, WORKSPACE_FILE_NAMES } from "./templates.js";
+import { DEFAULT_TEMPLATES, PLATFORM_OWNED_FILES, WORKSPACE_FILE_NAMES, } from "./templates.js";
 import { readWorkspaceState, writeWorkspaceState, isIdentityFilled } from "./workspace-state.js";
 import { systemNowMs } from "../runtime/system-time.js";
 const execFile = promisify(execFileCb);
@@ -36,6 +37,87 @@ async function writeIfMissing(filePath, content) {
         throw err;
     }
 }
+/** Compute the lowercase hex sha256 of a string (Node builtin -- no new deps). */
+function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf-8").digest("hex");
+}
+/**
+ * Content-hash-refresh every platform-owned workspace file (SOUL.md, AGENTS.md,
+ * BOOTSTRAP.md) whose on-disk sha256 differs from the canonical template.
+ *
+ * SILENT BY DESIGN: this helper does NOT take a logger parameter. The existing
+ * `ensureWorkspace` signature is called from CLI wizard + daemon bootstrap and
+ * does not thread a logger; adding one is invasive. When a `tracker` is
+ * supplied, the post-rename `tracker.recordRead` call is sufficient observability
+ * for the session-aware path (the tracker is consumed by `write` tools).
+ *
+ * 2026-05-20 lineage: prior to this helper, `ensureWorkspace` only wrote files
+ * with the `wx` (exclusive-create) flag. Every existing install kept its
+ * pre-fix template forever, including the false-promise venv prose in AGENTS.md
+ * that triggered the 06:18-06:25 sub-agent exec cascade. The codebase's own
+ * AGENTS.md prose declares "This file is read-only" -- this helper makes that
+ * contract real for the three platform-owned files.
+ *
+ * Per-file logic:
+ * - Skip silently on ENOENT (first-write path is handled by `writeIfMissing`).
+ * - BOOTSTRAP.md empty-guard: skip when the file is empty (.length === 0).
+ *   This preserves the post-onboarding cleared state -- the agent clears
+ *   BOOTSTRAP.md via the `write` tool once onboarding completes, and we must
+ *   not resurrect it. Strict `.length === 0` (not `.trim().length === 0`)
+ *   because a single trailing newline is meaningful agent intent.
+ * - sha256 match -> skip (idempotent fast path; no write, no tracker call).
+ * - Otherwise: atomic write via `.tmp` sibling + fs.rename (crash-safe).
+ *   On successful rename, re-register in the tracker if provided.
+ *
+ * Atomic write: write canonical to `<name>.tmp`, then `fs.rename` to `<name>`.
+ * Rename on POSIX is atomic; a crash mid-write cannot corrupt the target. On
+ * rename failure, the error propagates (same `@allow-throw` boundary as
+ * `writeIfMissing`).
+ */
+async function refreshPlatformFiles(dir, tracker) {
+    for (const name of PLATFORM_OWNED_FILES) {
+        const filePath = safePath(dir, name);
+        let onDiskContent;
+        try {
+            onDiskContent = await fs.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // First-write path: writeIfMissing handles seeding. Refresh is a no-op.
+                continue;
+            }
+            throw err;
+        }
+        // BOOTSTRAP.md empty-guard: preserve the post-onboarding cleared state.
+        // 2026-05-20 lineage: the agent clears BOOTSTRAP.md via `write` once
+        // onboarding completes; resurrecting it would re-run onboarding on the
+        // next ensureWorkspace call.
+        if (name === "BOOTSTRAP.md" && onDiskContent.length === 0) {
+            continue;
+        }
+        const canonical = DEFAULT_TEMPLATES[name];
+        if (sha256Hex(onDiskContent) === sha256Hex(canonical)) {
+            // Idempotent fast path: file already canonical. No write, no tracker.
+            continue;
+        }
+        // Atomic write: write to .tmp sibling, then rename onto the target.
+        // POSIX rename is atomic; a crash mid-write cannot corrupt the target.
+        const tmpPath = safePath(dir, `${name}.tmp`);
+        await fs.writeFile(tmpPath, canonical, { encoding: "utf-8", flag: "w" });
+        await fs.rename(tmpPath, filePath);
+        if (tracker) {
+            try {
+                const stat = await fs.stat(filePath);
+                tracker.recordRead(filePath, stat.mtimeMs, 0, undefined, Buffer.from(canonical, "utf-8"));
+            }
+            catch {
+                // stat failure is non-fatal -- same pattern as writeIfMissing's
+                // tracker-registration block (caller will need to read before
+                // overwriting, but the file itself is healthy on disk).
+            }
+        }
+    }
+}
 /**
  * Ensure a git repository exists in the given directory.
  * Best-effort: silently skips if git is unavailable.
@@ -104,6 +186,12 @@ export async function ensureWorkspace(options) {
         if (bootstrapNewlyWritten) {
             await writeWorkspaceState(dir, { bootstrapSeededAt: systemNowMs() });
         }
+        // Heal stale platform-owned files (SOUL.md, AGENTS.md, non-empty stale
+        // BOOTSTRAP.md) whose on-disk sha256 differs from the canonical template.
+        // No-op on first-run (writeIfMissing just seeded them at canonical hash).
+        // 2026-05-20: closes the architectural gap where wx-only seeding let stale
+        // pre-fix templates persist forever.
+        await refreshPlatformFiles(dir, tracker);
     }
     if (initGit) {
         await ensureGitRepo(dir);