comisai 1.0.45 → 1.0.46

package/node_modules/@comis/cli/dist/support-bundle/writer.js

@@ -0,0 +1,318 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Safe writer for the support bundle — the security backbone.
+ *
+ * Every directory is created via `ensureContainedDir` (mode 0o700, real-path
+ * confined to the data dir, symlinked-dir refusal); every file is written via
+ * `writeRegularFile` (0o600, O_NOFOLLOW, unlink-before-open); every path is
+ * composed with `safePath`. The raw path-join and unchecked file-write calls
+ * are deliberately avoided. The write set is an explicit allowlist of up to
+ * nine files, never a data-dir glob.
+ *
+ * Redaction is scoped per file. `doctor.json` echoes config-derived free text
+ * (DoctorFinding messages — e.g. a configured gateway URL with `user:pass@`), so
+ * every string leaf there is value-shape masked before it reaches disk. The
+ * reducer's own outputs (`triage.json`, `issue-summary.md`, `ai-issue-draft.md`)
+ * and the content-free digests (`fleet.json`, `config-posture.json`)
+ * are content-free by construction — counts, category labels, signal codes,
+ * section names, version facts, static placeholders, and
+ * static remediation strings — so they get path-token normalization ONLY; the
+ * value-shape pass is withheld there because it treats their own
+ * field-name-like tokens ("key", "secret", "message") and token-shaped ids as
+ * payloads and would corrupt the verdict/digest (and desync triage.json's
+ * privacy block from the manifest's verbatim copy). Section-failure and upstream warning strings folded into the
+ * manifest keep the full masking pass (they can carry error text). A section that
+ * cannot be produced folds into a manifest warning and the writer continues
+ * (partial output); only a failure to create the bundle directory is a hard error.
+ *
+ * @module
+ */
+import { safePath, systemDateFrom, systemGetEnv } from "@comis/core";
+import { ok, err } from "@comis/shared";
+import { ensureContainedDir, writeRegularFile, redactString, substitutePathsInString, walkAndRedactStrings, } from "@comis/observability";
+/** Best-effort human-readable reason from a Result error or thrown value. */
+function describeError(error) {
+    if (error !== null && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+    }
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/**
+ * Build the redaction backstop options. `safePath` resolves real paths and can
+ * throw on a symlink that escapes the data dir, so the workspace token is
+ * derived defensively — falling back to state/home substitution only.
+ */
+function buildRedactionOpts(dataDir) {
+    const homeDir = systemGetEnv("HOME");
+    try {
+        return { stateDir: dataDir, homeDir, workspaceDir: safePath(dataDir, "workspace") };
+    }
+    catch {
+        return { stateDir: dataDir, homeDir };
+    }
+}
+/**
+ * Recurse through a data graph and apply path-token substitution to every string
+ * leaf, leaving numbers/booleans/null untouched. The trusted-leaf counterpart to
+ * `walkAndRedactStrings`: it deliberately omits the value-shape masking pass, so
+ * it never rewrites a field-name token. Safe for the reducer's own content-free
+ * output (counts, labels, signal codes, static remediation strings) while still
+ * normalizing any embedded `$HOME`/`$STATE_DIR`/`$WORKSPACE_DIR` path. Cycles
+ * fold to a marker so a self-referential graph cannot loop; the input is never
+ * mutated.
+ */
+function walkAndSubstitutePaths(value, opts, seen = new WeakSet()) {
+    if (typeof value === "string") {
+        return substitutePathsInString(value, opts);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        return { __cycle: true };
+    }
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+        return obj.map((v) => walkAndSubstitutePaths(v, opts, seen));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = walkAndSubstitutePaths(v, opts, seen);
+    }
+    return out;
+}
+/**
+ * Resolve and create the support-bundles parent and the per-bundle dir under
+ * the symlink-safe, real-path-confined primitive. `safePath` throws on a
+ * symlink escape and `ensureContainedDir` returns `err` on a refused/failed
+ * create; both fold into the one hard error so the writer never throws.
+ */
+function prepareBundleDir(dataDir, bundleDirName) {
+    try {
+        const supportBundlesDir = safePath(dataDir, "support-bundles");
+        const parentResult = ensureContainedDir({
+            dir: supportBundlesDir,
+            mode: 0o700,
+            confinedBaseDir: dataDir,
+        });
+        if (!parentResult.ok) {
+            return err({ kind: "bundle-dir-create-failed", reason: describeError(parentResult.error) });
+        }
+        const bundleDir = safePath(supportBundlesDir, bundleDirName);
+        const bundleDirResult = ensureContainedDir({
+            dir: bundleDir,
+            mode: 0o700,
+            confinedBaseDir: dataDir,
+        });
+        if (!bundleDirResult.ok) {
+            return err({ kind: "bundle-dir-create-failed", reason: describeError(bundleDirResult.error) });
+        }
+        return ok(bundleDir);
+    }
+    catch (thrown) {
+        return err({ kind: "bundle-dir-create-failed", reason: describeError(thrown) });
+    }
+}
+/** Derive the timestamp-only bundle dir name from the generation instant. */
+function bundleDirNameFor(generatedAtMs) {
+    const tsIso = systemDateFrom(generatedAtMs).toISOString().replace(/[:.]/g, "-");
+    return `comis-support-${tsIso}`;
+}
+/**
+ * Resolve and create the per-bundle dir under `<dataDir>/support-bundles/`,
+ * returning the same path `writeSupportBundle` writes into. Exported so the
+ * orchestrator can create the dir FIRST (and export the trace bundle into it)
+ * before handing it back to the writer via `WriteSupportBundleInput.bundleDir`.
+ *
+ * The name carries a timestamp only (no host component), derived deterministically
+ * from `generatedAtMs`. Creation goes through the symlink-safe, real-path-confined
+ * `ensureContainedDir`, so a second call with the same instant is a no-op create
+ * (idempotent). A symlink escape or a refused create folds into the one hard error.
+ *
+ * @param dataDir - the resolved data-dir root.
+ * @param generatedAtMs - the generation instant (stamps the dir name).
+ * @returns `ok(bundleDir)`, or `err({ kind: "bundle-dir-create-failed" })`.
+ */
+export function ensureSupportBundleDir(dataDir, generatedAtMs) {
+    return prepareBundleDir(dataDir, bundleDirNameFor(generatedAtMs));
+}
+/**
+ * Write the support bundle (up to nine files) under `<dataDir>/support-bundles/`.
+ *
+ * Creates `comis-support-<tsIso>/` (a timestamp-only name — no host component)
+ * and writes `issue-summary.md`, `ai-issue-draft.md`, `triage.json`,
+ * `doctor.json`, and `manifest.json`, plus `fleet.json`, `config-posture.json`,
+ * `explain.json` (on `--session`), and `audit-summary.json` when their inputs are
+ * present, each through the symlink-safe primitives with the redaction backstop
+ * applied. The manifest is written last so it records every section that failed.
+ * Returns `err` only when the directory itself cannot be created.
+ *
+ * @param input - The bundle inputs (all pre-read by the caller).
+ * @returns `ok({ bundleDir, warnings })` on a full or partial write, or
+ *   `err({ kind: "bundle-dir-create-failed" })` when the dir is unproducible.
+ */
+export function writeSupportBundle(input) {
+    const { dataDir, generatedAtMs, triage, issueSummaryMd, aiIssueDraftMd, doctorJson, fleetJson, configPostureJson, explainJson, auditSummaryJson, } = input;
+    // The dir name + ISO stamp carry a timestamp only, never a host component,
+    // and are derived deterministically from the instant (so they stay consistent
+    // whether the dir is created here or was pre-created by the orchestrator).
+    const generatedAt = systemDateFrom(generatedAtMs).toISOString();
+    const bundleDirName = bundleDirNameFor(generatedAtMs);
+    // Create the per-bundle dir, or reuse the one the orchestrator pre-created (so
+    // it could export the trace bundle into it first). A failure to create is the
+    // one hard error (the bundle cannot be produced).
+    let bundleDir;
+    if (input.bundleDir !== undefined) {
+        bundleDir = input.bundleDir;
+    }
+    else {
+        const dirResult = ensureSupportBundleDir(dataDir, generatedAtMs);
+        if (!dirResult.ok) {
+            return dirResult;
+        }
+        bundleDir = dirResult.value;
+    }
+    // The redaction backstop, built once. stateDir/homeDir/workspaceDir drive the
+    // path → placeholder substitution (longest-match-wins).
+    const redactionOpts = buildRedactionOpts(dataDir);
+    // Untrusted free-text leaf (config-derived or error text): mask value shapes,
+    // then substitute known paths. Reserved for doctor.json (which echoes
+    // DoctorFinding messages — e.g. a configured gateway URL with `user:pass@`) and
+    // the section-failure / upstream warning strings folded into the manifest.
+    const redactText = (text) => substitutePathsInString(redactString(text), redactionOpts);
+    // Trusted, content-free leaf (the reducer's own counts, category labels, signal
+    // codes, version facts, and static remediation strings): normalize known paths
+    // ONLY. The value-shape pass is withheld here — it treats field-name tokens
+    // ("key", "secret", "message", "content") as payloads and would mangle the
+    // reducer's own constants, desyncing triage.json's privacy block from the copy
+    // the manifest writes verbatim.
+    const substitutePathsOnly = (text) => substitutePathsInString(text, redactionOpts);
+    const sectionWarnings = [];
+    const recordSectionFailure = (name, reason) => {
+        sectionWarnings.push({
+            source: "writer",
+            code: "section_write_failed",
+            count: 1,
+            message: redactText(`Failed to write ${name}: ${reason}`),
+        });
+    };
+    // The content files — the explicit allowlist. Each body is lazy so a
+    // serialization failure is caught per-section rather than crashing the run.
+    // Only doctor.json echoes untrusted config-derived text, so it alone keeps the
+    // value-shape masking pass; triage.json, issue-summary.md, and ai-issue-draft.md
+    // are content-free and get path normalization only. ai-issue-draft.md rides the
+    // trusted leaf like issue-summary.md — the value-shape pass would treat its
+    // `<REQUIRED: …>` idiom and field-name-like tokens as payloads and mangle it.
+    // fleet.json and config-posture.json ride the SAME trusted leaf (content-free
+    // by construction — codes, section names, closed labels + counts); each is
+    // appended ONLY when its input is defined, so a thrown fleet read omits
+    // fleet.json and an unparseable config omits config-posture.json.
+    const FILE_PLAN = [
+        { name: "issue-summary.md", body: () => substitutePathsOnly(issueSummaryMd) },
+        { name: "ai-issue-draft.md", body: () => substitutePathsOnly(aiIssueDraftMd) },
+        {
+            name: "triage.json",
+            body: () => JSON.stringify(walkAndSubstitutePaths(triage, redactionOpts), null, 2),
+        },
+        {
+            name: "doctor.json",
+            body: () => JSON.stringify(walkAndRedactStrings(doctorJson, redactionOpts), null, 2),
+        },
+        ...(fleetJson !== undefined
+            ? [
+                {
+                    name: "fleet.json",
+                    body: () => JSON.stringify(walkAndSubstitutePaths(fleetJson, redactionOpts), null, 2),
+                },
+            ]
+            : []),
+        ...(configPostureJson !== undefined
+            ? [
+                {
+                    name: "config-posture.json",
+                    body: () => JSON.stringify(walkAndSubstitutePaths(configPostureJson, redactionOpts), null, 2),
+                },
+            ]
+            : []),
+        // explain.json rides the UNTRUSTED value-shape leaf (like doctor.json): the
+        // embedded incident report carries free-text (errorPreview/resultDigest/
+        // likelyRootCause.detail) that could surface a secret-shaped substring, so
+        // every string leaf is masked. The pass preserves content-free correlation
+        // ids and intentionally redacts PII shapes it catches. Appended only on
+        // `--session`.
+        ...(explainJson !== undefined
+            ? [
+                {
+                    name: "explain.json",
+                    body: () => JSON.stringify(walkAndRedactStrings(explainJson, redactionOpts), null, 2),
+                },
+            ]
+            : []),
+        // audit-summary.json rides the TRUSTED leaf (like fleet.json): pure counts +
+        // closed AuditKind labels — path substitution only. Appended only when the
+        // offline audit read returned a digest.
+        ...(auditSummaryJson !== undefined
+            ? [
+                {
+                    name: "audit-summary.json",
+                    body: () => JSON.stringify(walkAndSubstitutePaths(auditSummaryJson, redactionOpts), null, 2),
+                },
+            ]
+            : []),
+    ];
+    for (const { name, body } of FILE_PLAN) {
+        try {
+            const writeResult = writeRegularFile({
+                path: safePath(bundleDir, name),
+                content: body(),
+                confinedBaseDir: dataDir,
+            });
+            if (!writeResult.ok) {
+                recordSectionFailure(name, describeError(writeResult.error));
+            }
+        }
+        catch (thrown) {
+            recordSectionFailure(name, describeError(thrown));
+        }
+    }
+    // Merge upstream warnings, redacting their free-text so the manifest honors
+    // the every-leaf-redacted contract.
+    const incoming = (input.warnings ?? []).map((warning) => ({
+        ...warning,
+        message: redactText(warning.message),
+    }));
+    const manifestWarnings = [...incoming, ...sectionWarnings];
+    // The manifest is structural metadata built here (privacy sourced from the
+    // triage so the two artifacts never drift). Only its free-text leaves — the
+    // warning messages — are redacted; the enum literal and generatedAt stay
+    // pristine so the manifest round-trips through its parser.
+    const manifest = {
+        schemaVersion: 1,
+        bundle: bundleDirName,
+        generatedAt,
+        redaction: { policy: "platform-aware-v1" },
+        privacy: triage.privacy,
+        ...(manifestWarnings.length > 0 ? { warnings: manifestWarnings } : {}),
+    };
+    try {
+        const manifestResult = writeRegularFile({
+            path: safePath(bundleDir, "manifest.json"),
+            content: JSON.stringify(manifest, null, 2),
+            confinedBaseDir: dataDir,
+        });
+        if (!manifestResult.ok) {
+            recordSectionFailure("manifest.json", describeError(manifestResult.error));
+        }
+    }
+    catch (thrown) {
+        recordSectionFailure("manifest.json", describeError(thrown));
+    }
+    // The returned set includes a manifest-write failure (which the on-disk
+    // manifest cannot record about itself).
+    return ok({ bundleDir, warnings: [...incoming, ...sectionWarnings] });
+}

package/node_modules/@comis/cli/dist/sync-tooling/atomic-write.d.ts

@@ -11,7 +11,7 @@
  * the parent-dir fsync error is swallowed so dev-on-macos works while
  * Linux production gets full durability.
  *
- * NEW pattern in this codebase — there is no reference impl to mirror.
+ * This is the only atomic-write implementation in the codebase.
  * `packages/daemon/src/config/last-known-good.ts` uses `copyFileSync`
  * with no fsync; `packages/cli/src/commands/configure.ts` uses plain
  * `writeFileSync`. Neither is atomic; do not adapt either.

package/node_modules/@comis/cli/dist/sync-tooling/atomic-write.js

@@ -12,7 +12,7 @@
  * the parent-dir fsync error is swallowed so dev-on-macos works while
  * Linux production gets full durability.
  *
- * NEW pattern in this codebase — there is no reference impl to mirror.
+ * This is the only atomic-write implementation in the codebase.
  * `packages/daemon/src/config/last-known-good.ts` uses `copyFileSync`
  * with no fsync; `packages/cli/src/commands/configure.ts` uses plain
  * `writeFileSync`. Neither is atomic; do not adapt either.

package/node_modules/@comis/cli/dist/sync-tooling/daemon-guard.js

@@ -51,8 +51,8 @@ export async function isDaemonRunning(timeoutMs = 1000) {
         return true;
     }
     catch (e) {
-        // W13: a gateway token-rejection (WS close 4001) is PROOF the daemon is up
-        // — it answered the upgrade. Returning false here made the CLI print
+        // A gateway token-rejection (WS close 4001) is PROOF the daemon is up
+        // — it answered the upgrade. Returning false here would make the CLI print
         // "daemon ... is not running" against a live daemon, hiding the real
         // (auth) problem. The follow-up RPC then fails with the token-naming error.
         if (isGatewayAuthRejection(e)) {

package/node_modules/@comis/cli/dist/sync-tooling/diff.d.ts

@@ -5,9 +5,9 @@
  * callback), return a string. NO console.log calls, NO fs I/O, NO Commander.
  * The caller emits via the existing `format.ts` helpers.
  *
- * "stdout contains `tooling:`" is satisfied because `payload.wouldWrite` (the
- * post-mutation `doc.toString()` output) is appended verbatim into the
- * "Would write:" preview section.
+ * The rendered output always contains the literal `tooling:` block because
+ * `payload.wouldWrite` (the post-mutation `doc.toString()` output) is
+ * appended verbatim into the "Would write:" preview section.
  *
  * @module
  */

package/node_modules/@comis/cli/dist/sync-tooling/diff.js

@@ -6,9 +6,9 @@
  * callback), return a string. NO console.log calls, NO fs I/O, NO Commander.
  * The caller emits via the existing `format.ts` helpers.
  *
- * "stdout contains `tooling:`" is satisfied because `payload.wouldWrite` (the
- * post-mutation `doc.toString()` output) is appended verbatim into the
- * "Would write:" preview section.
+ * The rendered output always contains the literal `tooling:` block because
+ * `payload.wouldWrite` (the post-mutation `doc.toString()` output) is
+ * appended verbatim into the "Would write:" preview section.
  *
  * @module
  */

package/node_modules/@comis/cli/dist/tooling-fill/agent-call.d.ts

@@ -4,11 +4,11 @@
  * POSTs to http://127.0.0.1:<port>/api/chat with bearer auth, parses the
  * `{response: string}` field of the gateway's chat response, and returns a
  * typed `Result<{response}, AgentCallError>`. No SDK deps — `node:http`
- * only ("no axios, no node-fetch" per SPEC §Constraints).
+ * only (no axios, no node-fetch).
  *
  * Failure modes (`AgentCallErrorKind`):
  * - `network`     — ECONNREFUSED / ENOTFOUND / EHOSTUNREACH; emits the
- *                   literal SPEC string "Cannot reach Comis daemon —
+ *                   exact operator-facing string "Cannot reach Comis daemon —
  *                   gateway unreachable. Start the daemon and retry."
  * - `auth`        — HTTP 401; "Unauthorized — check COMIS_GATEWAY_TOKEN".
  * - `timeout`     — request exceeded `timeoutMs` (default 30s).
@@ -45,7 +45,7 @@ export interface AgentCallArgs {
     readonly agentId?: string;
     /** Default 30_000 (30s). */
     readonly timeoutMs?: number;
-    /** Default "127.0.0.1". The gateway is localhost-only by SPEC §Constraints. */
+    /** Default "127.0.0.1". The gateway is localhost-only by design. */
     readonly host?: string;
 }
 export interface AgentCallResponse {

package/node_modules/@comis/cli/dist/tooling-fill/agent-call.js

@@ -5,11 +5,11 @@
  * POSTs to http://127.0.0.1:<port>/api/chat with bearer auth, parses the
  * `{response: string}` field of the gateway's chat response, and returns a
  * typed `Result<{response}, AgentCallError>`. No SDK deps — `node:http`
- * only ("no axios, no node-fetch" per SPEC §Constraints).
+ * only (no axios, no node-fetch).
  *
  * Failure modes (`AgentCallErrorKind`):
  * - `network`     — ECONNREFUSED / ENOTFOUND / EHOSTUNREACH; emits the
- *                   literal SPEC string "Cannot reach Comis daemon —
+ *                   exact operator-facing string "Cannot reach Comis daemon —
  *                   gateway unreachable. Start the daemon and retry."
  * - `auth`        — HTTP 401; "Unauthorized — check COMIS_GATEWAY_TOKEN".
  * - `timeout`     — request exceeded `timeoutMs` (default 30s).
@@ -27,7 +27,7 @@
 import * as http from "node:http";
 import { ok, err } from "@comis/shared";
 const DEFAULT_TIMEOUT_MS = 30_000;
-/** Literal SPEC string. Anti-regression grep counts this exact string. */
+/** Exact operator-facing message — tests assert this literal string. */
 const GATEWAY_UNREACHABLE_MSG = "Cannot reach Comis daemon — gateway unreachable. Start the daemon and retry.";
 /**
  * POST `/api/chat` to the local daemon and parse the `{response}` field.
@@ -147,5 +147,5 @@ export async function callAgent(args) {
     // The token never appears in error.message; only the bearer header
     // carries it, and that is constructed inline above.
 }
-// Internal export for testability of the literal SPEC string.
+// Internal export so tests can assert the exact gateway-unreachable message.
 export const __TOOLFILL_GATEWAY_UNREACHABLE_MSG = GATEWAY_UNREACHABLE_MSG;

package/node_modules/@comis/cli/dist/tooling-fill/apply-hint.d.ts

@@ -63,6 +63,6 @@ export interface HintFields {
  *          "mcp"/"skills" after a runtime cast-around;
  *          err({kind:"doc-corrupt"}) if doc.contents is null/undefined.
  *
- * Failure paths leave the doc unmutated (verified in tests 8-9).
+ * Failure paths leave the doc unmutated.
  */
 export declare function setHintFields(doc: Document, kind: FillKind, name: string, fields: HintFields): Result<void, ApplyHintError>;

package/node_modules/@comis/cli/dist/tooling-fill/apply-hint.js

@@ -59,7 +59,7 @@ const STUB_TODO_COMMENT = " TODO: list npm/pip packages this MCP replaces";
  *          "mcp"/"skills" after a runtime cast-around;
  *          err({kind:"doc-corrupt"}) if doc.contents is null/undefined.
  *
- * Failure paths leave the doc unmutated (verified in tests 8-9).
+ * Failure paths leave the doc unmutated.
  */
 export function setHintFields(doc, kind, name, fields) {
     // Runtime guard for callers that cast around the FillKind type.
@@ -84,7 +84,7 @@ export function setHintFields(doc, kind, name, fields) {
     const hintPath = ["tooling", kind, "capabilityHints", name];
     // hasIn returns false if any segment of the path is missing — covers both
     // "the hint name doesn't exist under capabilityHints" and "capabilityHints
-    // (or the parent map) doesn't exist at all" (test cases 8 + 9).
+    // (or the parent map) doesn't exist at all".
     if (!doc.hasIn(hintPath)) {
         return err({
             kind: "hint-not-found",

package/node_modules/@comis/cli/dist/tooling-fill/orchestrator/orchestrator-verify.js

@@ -55,7 +55,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
         willRestart = true;
     }
     // ---- Protected mutation window --------------------------------------
-    // 9a. stopDaemon
+    // Stop the daemon so no live process reads the config mid-mutation.
     if (willRestart) {
         const stopRes = await stopDaemon(supervisor);
         if (!stopRes.ok) {
@@ -65,7 +65,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             };
         }
     }
-    // 9b. writeBackup
+    // Back up the config before any mutation (backup-fail-fast).
     const backupRes = writeBackup(opts.configPath, opts.homeDir, "tooling-fill");
     if (!backupRes.ok) {
         // Best-effort restart, then exit 2.
@@ -78,7 +78,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
         };
     }
     const backupPath = backupRes.value.backupPath;
-    // 9c. setHintFields per entry — accumulate into doc.
+    // setHintFields per entry — accumulate into doc.
     for (const entry of filled) {
         const applyRes = setHintFields(doc, entry.kind, entry.name, {
             description: entry.description,
@@ -93,7 +93,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             };
         }
     }
-    // 9d. atomicWriteFile
+    // Atomically write the mutated doc over the config.
     const writeRes = atomicWriteFile(opts.configPath, doc.toString());
     if (!writeRes.ok) {
         const rb = await rollback(opts.configPath, rawYaml, willRestart, supervisor);
@@ -102,7 +102,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             summary: `Atomic write failed (${writeRes.error.code}): ${writeRes.error.cause}. ${rolledBackSuffix(backupPath, opts.configPath, rb)}`,
         };
     }
-    // 9e. validateConfig — re-load + validate the freshly written file.
+    // validateConfig — re-load + validate the freshly written file.
     // Env-substitute `${VAR}` references before validation, mirroring
     // `comis config validate` (commands/config.ts:131-133). Without this, any
     // config using the documented `${COMIS_GATEWAY_TOKEN}` pattern would fail
@@ -125,7 +125,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             summary: rolledBackSummary(backupPath, opts.configPath, rb, undefined),
         };
     }
-    // ---- 10. startDaemon + verify-alive ---------------------------------
+    // ---- startDaemon + verify-alive --------------------------------------
     // `systemctl start` exits 0 once the unit is queued, not once the daemon
     // has finished booting. If the daemon then crashes during boot (e.g.
     // misowned config, invalid YAML), the orchestrator was previously a
@@ -158,7 +158,7 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             };
         }
     }
-    // ---- 11. Partial success on --all -----------------------------------
+    // ---- Partial success on --all -----------------------------------------
     if (skipped.length > 0) {
         const filledNames = filled.map((f) => f.name).join(", ");
         const skippedReport = skipped
@@ -170,12 +170,12 @@ export async function verifyFill(opts, rawYaml, doc, supervisor, filled, skipped
             summary: `Filled: ${filledNames}.${droppedReport} Skipped: ${skippedReport}. Backup: ${backupPath}.`,
         };
     }
-    // ---- 12. Backup retention -------------------------------------------
+    // ---- Backup retention --------------------------------------------------
     // Keep the 5 most recent tooling-fill backups, drop older. Best-effort —
     // never failing the success path on a housekeeping miss.
     const pruneRes = pruneOldBackups(opts.homeDir, "tooling-fill", 5);
     const pruneSuffix = pruneRes.deleted > 0 ? ` (pruned ${pruneRes.deleted} older backup(s))` : "";
-    // ---- 13. Success exit ------------------------------------------------
+    // ---- Success exit ------------------------------------------------------
     const filledNames = filled.map((f) => f.name).join(", ");
     const droppedReport = renderDroppedReport(filled);
     return {

package/node_modules/@comis/cli/dist/tooling-fill/prompt-template.js

@@ -63,8 +63,8 @@ export function buildFillPrompt(args) {
             args.skillDescription.length > 0) {
             sections.push(`Existing manifest description: "${args.skillDescription}"`);
             sections.push(
-            // REFINE / CONDENSE: do not invent. "REFINE" must appear in
-            // uppercase per acceptance test.
+            // REFINE / CONDENSE: do not invent. "REFINE" must stay uppercase —
+            // tests assert the literal token.
             "Task: REFINE OR CONDENSE the existing description (do not invent " +
                 "a new one). Then list any npm/pip packages this skill replaces — " +
                 "usually [] for skills, but supported (e.g. a markdown-formatter " +

package/node_modules/@comis/cli/dist/util/cli-version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared reader for this CLI's own version, from `packages/cli/package.json`.
+ *
+ * `import.meta.url` is per-module, so the relative specifier below resolves
+ * from THIS module's own location. Compiled to `dist/util/cli-version.js`, the
+ * `../../package.json` specifier (two hops up) points at `packages/cli/package.json`.
+ * Every caller imports this one reader and inherits the correct resolution
+ * regardless of its own directory depth.
+ *
+ * @module
+ */
+/**
+ * Read this CLI's version from `packages/cli/package.json`.
+ *
+ * Returns `undefined` — never throws — when the package cannot be resolved, so
+ * callers treat an absent version as "unknown" rather than a hard failure.
+ */
+export declare function readCliVersion(): string | undefined;

package/node_modules/@comis/cli/dist/util/cli-version.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared reader for this CLI's own version, from `packages/cli/package.json`.
+ *
+ * `import.meta.url` is per-module, so the relative specifier below resolves
+ * from THIS module's own location. Compiled to `dist/util/cli-version.js`, the
+ * `../../package.json` specifier (two hops up) points at `packages/cli/package.json`.
+ * Every caller imports this one reader and inherits the correct resolution
+ * regardless of its own directory depth.
+ *
+ * @module
+ */
+import { createRequire } from "node:module";
+/**
+ * Read this CLI's version from `packages/cli/package.json`.
+ *
+ * Returns `undefined` — never throws — when the package cannot be resolved, so
+ * callers treat an absent version as "unknown" rather than a hard failure.
+ */
+export function readCliVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req("../../package.json");
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}

package/node_modules/@comis/cli/dist/util/csv.d.ts

@@ -1,8 +1,7 @@
 /**
- * A pure RFC4180 CSV serializer (COST-03, Phase 179 WS6).
+ * A pure RFC4180 CSV serializer.
  *
- * Greenfield — the repo had no CSV module (the `join(",")` hits elsewhere are
- * list-formatting, not CSV). Zero-dependency by design: the only escaping rule is
+ * Zero-dependency by design: the only escaping rule is
  * RFC4180 §2.6/§2.7 — a field containing a comma, a double-quote, or a line break
  * (CR or LF) is enclosed in double-quotes, and each embedded double-quote is
  * doubled. Records are joined with CRLF (§2.1).
@@ -10,7 +9,8 @@
  * CONTENT-FREE BY CONSTRUCTION: `toCsv` projects ONLY the explicit `columns`
  * allowlist — it NEVER reflects arbitrary object keys (`Object.keys(row)`). A
  * source row may carry a body/secret/query field, but unless that key is named in
- * `columns` it can never reach the CSV (the export threat T-179-07). The caller
+ * `columns` it can never reach the CSV — the export cannot exfiltrate message
+ * bodies or secrets. The caller
  * passes the cost-bucket + pricing-coverage column set; nothing else is emitted.
  *
  * @module

package/node_modules/@comis/cli/dist/util/csv.js

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * A pure RFC4180 CSV serializer (COST-03, Phase 179 WS6).
+ * A pure RFC4180 CSV serializer.
  *
- * Greenfield — the repo had no CSV module (the `join(",")` hits elsewhere are
- * list-formatting, not CSV). Zero-dependency by design: the only escaping rule is
+ * Zero-dependency by design: the only escaping rule is
  * RFC4180 §2.6/§2.7 — a field containing a comma, a double-quote, or a line break
  * (CR or LF) is enclosed in double-quotes, and each embedded double-quote is
  * doubled. Records are joined with CRLF (§2.1).
@@ -11,7 +10,8 @@
  * CONTENT-FREE BY CONSTRUCTION: `toCsv` projects ONLY the explicit `columns`
  * allowlist — it NEVER reflects arbitrary object keys (`Object.keys(row)`). A
  * source row may carry a body/secret/query field, but unless that key is named in
- * `columns` it can never reach the CSV (the export threat T-179-07). The caller
+ * `columns` it can never reach the CSV — the export cannot exfiltrate message
+ * bodies or secrets. The caller
  * passes the cost-bucket + pricing-coverage column set; nothing else is emitted.
  *
  * @module