comisai 1.0.44 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/ctx-expand-walk.js

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * `ctxExpandWalk` — DEPTH-02 bounded in-process multi-hop walk over a compressed
- * region of THIS conversation. The single-hop `ctx_expand` recovered ONE leaf
- * summary's messages; this BFS descends the summary-parent (T2) hierarchy
+ * `ctxExpandWalk` — a bounded in-process multi-hop walk over a compressed
+ * region of THIS conversation. A single-hop expansion would recover only ONE
+ * leaf summary's messages; this BFS descends the summary-parent (T2) hierarchy
  * (condensed → child summaries → leaf summaries → messages) and, when a
  * knowledge-graph lane is injected, fuses bounded KG (T4) hops — returning a
  * RANKED CITED evidence bundle bounded by depth, token, and node-visit caps.
@@ -14,19 +14,19 @@
  *   - The walk is READ-ONLY (getSummaryChildren / getSummaryMessages / getMessages
  *     only — no append/upsert). The tool runs it INSIDE
  *     `store.runOnConversation` (the single-flight serializer) so a deferred
- *     compaction write cannot rewrite the DAG mid-walk (Pitfall 5).
- *   - R4 scope-inheritance: EVERY edge read passes the per-call `scope` the
+ *     compaction write cannot rewrite the DAG mid-walk.
+ *   - Scope-inheritance: EVERY edge read passes the per-call `scope` the
  *     caller derived from `requireCtxScope()` — an out-of-scope summary/message
- *     is unreachable by construction (WR-02). The scope is NEVER a wiring closure.
+ *     is unreachable by construction. The scope is NEVER a wiring closure.
  *
  * T2-only floor (the live default): `spreadLane` is OPTIONAL. When it is absent,
  * returns an empty lane, OR errors, the walk SUCCEEDS T2-only — the KG is NEVER a
- * precondition (the design's §15 degradation; `spreadLane` is a skeleton
+ * precondition (graceful degradation; `spreadLane` is a skeleton
  * returning [] in production today, and no TripleStorePort is threaded into the
  * tool deps). A failing lane is non-fatal — logged content-free, the walk
  * continues T2-only (mirrors recall-graph-spread-lane.ts:72-85).
  *
- * NO sub-agent, NO grant lifecycle — EXPF-01 (frontier sub-agent escalation) is
+ * NO sub-agent, NO grant lifecycle — frontier sub-agent escalation is
  * explicitly DEFERRED. This walk is in-process and deterministic.
  *
  * @module
@@ -55,7 +55,7 @@ export function depthForTier(capabilityClass) {
  * lane), seeded by `seedSummaryId`. Read-only; every edge read passes `scope`.
  *
  * @param store           The injected core `ContextStorePort` TYPE (read-only here).
- * @param scope           The per-call R4 read scope (from `requireCtxScope()`).
+ * @param scope           The per-call read scope (from `requireCtxScope()`).
  * @param seedSummaryId   The summaryId to zoom into (from ctx_search / ctx_inspect).
  * @param caps            depth / token / node-visit caps (depth is tier-gated).
  * @param opts            Optional T4 spreadLane + logger (T2-only when absent).
@@ -70,8 +70,8 @@ export async function ctxExpandWalk(store, scope, seedSummaryId, caps, opts) {
     let nodesVisited = 0;
     let unrecoverable = 0;
     let capped = false;
-    // Lazy id→message map — built once on the first leaf encountered (the
-    // single-summary tool's id-keyed re-join, kept O(referenced) by deferring it).
+    // Lazy id→message map — built once on the first leaf encountered (an
+    // id-keyed re-join, kept O(referenced) by deferring it).
     let messageById;
     const getMessageMap = () => {
         if (messageById === undefined) {
@@ -95,7 +95,7 @@ export async function ctxExpandWalk(store, scope, seedSummaryId, caps, opts) {
         if (node.depth > depthReached)
             depthReached = node.depth;
         // A condensed summary has children; a leaf summary covers messages. Read both
-        // edges R4-scoped — a drifted id simply yields [] (never throws).
+        // edges scoped — a drifted id simply yields [] (never throws).
         const children = store.getSummaryChildren(scope, node.summaryId);
         const messageIds = store.getSummaryMessages(scope, node.summaryId);
         // Leaf detail: re-join covered ids → render text → add as cited message items,

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/ctx-inspect-tool.d.ts

@@ -4,7 +4,7 @@
  * child summaryIds and covered-message count, via the injected
  * `ContextStorePort`.
  *
- * Composition (RESEARCH Q2 — no dedicated single-summary getter): filters
+ * Composition (no dedicated single-summary getter): filters
  * `getSummaries(conversationId)` by `summaryId`, then composes
  * `getSummaryChildren` + `getSummaryMessages`. Returns METADATA ONLY — the
  * summary `content` is NOT surfaced and NOT logged, so the output is not
@@ -13,7 +13,7 @@
  *
  * Owner-scoped: the conversation is derived per-call from
  * `tryGetContext().sessionKey` (fail-closed `permission_denied` with no live
- * session), never a caller-supplied id (E2 isolation).
+ * session), never a caller-supplied id (conversation isolation).
  *
  * @module
  */

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/ctx-inspect-tool.js

@@ -5,7 +5,7 @@
  * child summaryIds and covered-message count, via the injected
  * `ContextStorePort`.
  *
- * Composition (RESEARCH Q2 — no dedicated single-summary getter): filters
+ * Composition (no dedicated single-summary getter): filters
  * `getSummaries(conversationId)` by `summaryId`, then composes
  * `getSummaryChildren` + `getSummaryMessages`. Returns METADATA ONLY — the
  * summary `content` is NOT surfaced and NOT logged, so the output is not
@@ -14,7 +14,7 @@
  *
  * Owner-scoped: the conversation is derived per-call from
  * `tryGetContext().sessionKey` (fail-closed `permission_denied` with no live
- * session), never a caller-supplied id (E2 isolation).
+ * session), never a caller-supplied id (conversation isolation).
  *
  * @module
  */
@@ -38,12 +38,12 @@ export function createCtxInspectTool(deps) {
         parameters: CtxInspectParams,
         async execute(_toolCallId, params) {
             // SCOPE — build the (conversation, agent, tenant) read scope from the LIVE
-            // context per-call (R4 / WR-02); fail closed without a fully-scoped session.
+            // context per-call; fail closed without a fully-scoped session.
             const ctxScope = requireCtxScope();
             const conversationId = ctxScope.conversationId;
             const summaryId = readStringParam(params, "summaryId", true);
             const t0 = deps.nowMs();
-            // Filter this agent's summaries (R4 agent-scoped) — no single-summary getter (YAGNI, Q2).
+            // Filter this agent's summaries (agent-scoped) — there is no single-summary getter.
             const summary = deps.store
                 .getSummaries(ctxScope)
                 .find((s) => s.summaryId === summaryId);
@@ -66,12 +66,12 @@ export function createCtxInspectTool(deps) {
                 coveredMessageCount: coveredMessageIds.length,
                 step: "ctx_inspect",
             }, "ctx_inspect complete");
-            // O1: content-free expansion-hit metric (ids/counts/durationMs only —
+            // Content-free expansion-hit metric (ids/counts/durationMs only —
             // NEVER the summary content; the lossless store, AGENTS.md §2.2/§2.7).
             // recoveredCount = the covered-message count the inspection surfaced.
-            // WR-02: GUARDED — a throwing subscriber must never fail this completed
+            // GUARDED — a throwing subscriber must never fail this completed
             // metadata read (see emitExpansionMetric).
-            // WR-03: read the end-instant ONCE so durationMs and timestamp are a single
+            // Read the end-instant ONCE so durationMs and timestamp are a single
             // consistent snapshot (the afterTurn triggers' one-read pattern).
             const endMs = deps.nowMs();
             emitExpansionMetric(deps, "ctx_inspect", {

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/ctx-search-tool.d.ts

@@ -5,15 +5,15 @@
  * Direct-injection (NOT the RPC `session_search`/`memory_search` recall path):
  *   1. SCOPE: the conversation is derived per-call from `tryGetContext().sessionKey`
  *      and rejected (`permission_denied`) when there is no live session. NEVER
- *      cached in the factory closure; NEVER a caller-supplied id (E2 isolation).
+ *      cached in the factory closure; NEVER a caller-supplied id (conversation isolation).
  *   2. SANITIZE: the raw query is run through `sanitizeFts5Query` (the skills-side
- *      sanitizer) BEFORE it reaches `store.searchLcd` (PATTERNS gap #2 — the store
+ *      sanitizer) BEFORE it reaches `store.searchLcd` (the store
  *      trusts a pre-sanitized query).
  *   3. TAINT: every returned hit snippet is recovered/untrusted content, so it is
  *      wrapped via `wrapExternalContent({ source: "unknown" })` before it leaves
  *      the tool (the prompt-injection surface).
  *   4. OBSERVABILITY: logs ids/counts/durationMs/step ONLY — never the query text
- *      or a snippet body (Pitfall 2 / log-payload-checker gate).
+ *      or a snippet body (the log-payload-checker gate).
  *
  * @module
  */

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/ctx-search-tool.js

@@ -6,15 +6,15 @@
  * Direct-injection (NOT the RPC `session_search`/`memory_search` recall path):
  *   1. SCOPE: the conversation is derived per-call from `tryGetContext().sessionKey`
  *      and rejected (`permission_denied`) when there is no live session. NEVER
- *      cached in the factory closure; NEVER a caller-supplied id (E2 isolation).
+ *      cached in the factory closure; NEVER a caller-supplied id (conversation isolation).
  *   2. SANITIZE: the raw query is run through `sanitizeFts5Query` (the skills-side
- *      sanitizer) BEFORE it reaches `store.searchLcd` (PATTERNS gap #2 — the store
+ *      sanitizer) BEFORE it reaches `store.searchLcd` (the store
  *      trusts a pre-sanitized query).
  *   3. TAINT: every returned hit snippet is recovered/untrusted content, so it is
  *      wrapped via `wrapExternalContent({ source: "unknown" })` before it leaves
  *      the tool (the prompt-injection surface).
  *   4. OBSERVABILITY: logs ids/counts/durationMs/step ONLY — never the query text
- *      or a snippet body (Pitfall 2 / log-payload-checker gate).
+ *      or a snippet body (the log-payload-checker gate).
  *
  * @module
  */
@@ -24,7 +24,7 @@ import { jsonResult, throwToolError, readStringParam, readNumberParam } from "..
 import { sanitizeFts5Query } from "../../../platform-tools/tools/fts5-sanitizer.js";
 import { emitExpansionMetric, emitScriptZeroHit, requireCtxScope } from "./context-tools-shared.js";
 /**
- * OBS-01 scan-floor cap note surfaced to the model when the bounded normalized
+ * Scan-floor cap note surfaced to the model when the bounded normalized
  * scan reached its row cap (`lane === "scan" && scanCapped`). Content-free
  * (no query text) — names the SCAN_ROW_CAP (`@comis/memory` `SCAN_ROW_CAP = 2000`)
  * so the model knows older messages were not scanned. Pinned by the tool test.
@@ -73,8 +73,8 @@ export function createCtxSearchTool(deps) {
         parameters: CtxSearchParams,
         async execute(_toolCallId, params) {
             // (1) SCOPE — build the (conversation, agent, tenant) read scope from the
-            //     LIVE context per-call (R4 / WR-02); fail closed without a fully-scoped
-            //     session. NEVER a wiring closure (multi-agent-safe, Pitfall 4).
+            //     LIVE context per-call; fail closed without a fully-scoped
+            //     session. NEVER a wiring closure (multi-agent-safe).
             const ctxScope = requireCtxScope();
             const conversationId = ctxScope.conversationId;
             // (2) SANITIZE — strip FTS5 special chars in the tool, before the store sees it.
@@ -83,7 +83,7 @@ export function createCtxSearchTool(deps) {
             const requested = readNumberParam(params, "limit", false) ?? 10;
             const limit = Math.min(Math.max(1, requested), 30);
             const t0 = deps.nowMs();
-            // OBS-01: searchLcd returns the 180-05-widened LcdSearchResult
+            // searchLcd returns the widened LcdSearchResult
             // { hits, scriptZeroHit?, lane, matchErrored, scanCapped? } — preserve the
             // hits array for downstream processing and surface the script-health signals
             // at THIS logging/emit boundary (infra-free seam: @comis/memory has no logger).
@@ -91,7 +91,7 @@ export function createCtxSearchTool(deps) {
             const hits = result.hits;
             // (3) SCRUB + TAINT — scrub secrets out of every recovered snippet, THEN wrap
             //     it as untrusted before it leaves the tool. A snippet can legitimately
-            //     contain a credential (the F1 lossless store keeps the raw conversation);
+            //     contain a credential (the lossless store keeps the raw conversation);
             //     the egress copy must never carry it to the model context (mirrors the
             //     ctx_expand egress scrub). The base store is untouched.
             const safeHits = hits.map((h) => ({
@@ -101,11 +101,11 @@ export function createCtxSearchTool(deps) {
                 snippet: wrapExternalContent(scrubSecretsFromText(h.snippet).text, { source: "unknown" }),
             }));
             // (4) OBSERVABILITY — ids/counts/durationMs/step ONLY; never the query or a snippet.
-            // WR-03: read the end-instant ONCE and reuse it for the DEBUG durationMs, the
+            // Read the end-instant ONCE and reuse it for the DEBUG durationMs, the
             // emit durationMs, AND the emit timestamp, so the three are a single
             // consistent clock snapshot (the afterTurn triggers' one-read pattern).
             const endMs = deps.nowMs();
-            // OBS-01 signal purity (RESEARCH Pitfall 9): the 180-05 store sets
+            // Signal purity: the store sets
             // `scriptZeroHit` ONLY on a CLEAN zero-hit (`!matchErrored`); a swallowed
             // FTS5 MATCH error surfaces as `matchErrored` instead and must NEVER count
             // as a lane gap.
@@ -123,14 +123,11 @@ export function createCtxSearchTool(deps) {
                 }, "lcd search MATCH errored (degraded)");
             }
             else if (result.scriptZeroHit) {
-                // OBS-01: a clean non-Latin zero-hit. Promote the §14.4 instrumented
-                // trigger (the old DEBUG-only CJK-zero-hit line, now replaced) to a
-                // content-free event-bus signal — onto the `comis explain` timeline AND
-                // `comis fleet`
-                // health_signal (plan 180-03's dual-path plumbing). Guarded: a throwing
-                // subscriber can NEVER fail the already-completed search. Payload carries
-                // the closed `scriptClass`/`lane` enums + ids + timestamp ONLY (I8) —
-                // the query string is intentionally ABSENT.
+                // A clean non-Latin zero-hit → emit a content-free event-bus signal onto
+                // the `comis explain` timeline AND the `comis fleet` health_signal.
+                // Guarded: a throwing subscriber can NEVER fail the already-completed
+                // search. Payload carries the closed `scriptClass`/`lane` enums + ids +
+                // timestamp ONLY — the query string is intentionally ABSENT.
                 emitScriptZeroHit(deps, {
                     conversationId: ctxScope.conversationId,
                     agentId: ctxScope.agentId,
@@ -148,9 +145,9 @@ export function createCtxSearchTool(deps) {
                 durationMs: endMs - t0,
                 step: "ctx_search",
             }, "ctx_search complete");
-            // O1: content-free expansion-hit metric (ids/counts/durationMs only —
+            // Content-free expansion-hit metric (ids/counts/durationMs only —
             // NEVER the query or a snippet; the lossless store, AGENTS.md §2.2/§2.7).
-            // WR-02: GUARD the emit. TypedEventBus.emit delegates to Node's
+            // GUARD the emit. TypedEventBus.emit delegates to Node's
             // EventEmitter.emit, which propagates the first subscriber exception
             // synchronously to the emitter — so a throwing subscriber (a trajectory
             // writer, a metrics sink) would unwind out of execute() and convert this
@@ -166,7 +163,7 @@ export function createCtxSearchTool(deps) {
                 durationMs: endMs - t0,
                 timestamp: endMs,
             });
-            // OBS-01: surface the lane to the model (which path served the query) and,
+            // Surface the lane to the model (which path served the query) and,
             // when the bounded normalized scan floor hit its row cap, the cap note (the
             // "cap noted in result" criterion) — so the model knows older messages were
             // not searched and can narrow/retry. Content-free (no query text). The cap

package/node_modules/@comis/skills/dist/tools/builtin/context-tools/index.js

@@ -16,6 +16,6 @@
 export { createCtxSearchTool } from "./ctx-search-tool.js";
 export { createCtxInspectTool } from "./ctx-inspect-tool.js";
 export { createCtxExpandTool } from "./ctx-expand-tool.js";
-// DEPTH-02: the tier→multi-hop-depth map, consumed by the daemon wiring site to
+// The tier→multi-hop-depth map, consumed by the daemon wiring site to
 // resolve `maxExpandDepth` from the agent's ModelProfile capabilityClass.
 export { depthForTier } from "./ctx-expand-walk.js";

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/exec-shared.js

@@ -452,7 +452,7 @@ export function buildExecEnv(deps) {
         ...(resolvedSecretEnv ?? {}),
     };
     const finalEnv = sandboxConfig?.sandbox.wrapEnv?.(env, workspacePath) ?? env;
-    // Broker + cap-lease env LAST; proxy vars filtered to the defined ones (a Phase 211 cap-lease-only spawn has none).
+    // Broker + cap-lease env LAST; proxy vars filtered to the defined ones (a cap-lease-only spawn has none).
     if (deps.brokerSpawnEnv) {
         const { HTTPS_PROXY, HTTP_PROXY, NODE_EXTRA_CA_CERTS, placeholders } = deps.brokerSpawnEnv;
         Object.assign(finalEnv, placeholders, Object.fromEntries(Object.entries({ HTTPS_PROXY, NODE_EXTRA_CA_CERTS, HTTP_PROXY }).filter(([, v]) => v != null)));

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/index.js

@@ -23,12 +23,12 @@ import { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, ExecParams } from "./exec-types.js"
 import { resolveCwd, commandUsesRawInterpreter, resolveSecretRefs, evaluateInstallDetourGate, buildExecEnv, } from "./exec-shared.js";
 import { executeForeground } from "./exec-foreground.js";
 import { executeBackground } from "./exec-background.js";
-// Activity label spec (SPEC §6.3). Descriptor name == emitted name
+// Activity label spec. Descriptor name == emitted name
 // (exec-tool/index.ts:75 → `name: "exec"`). The transform hook wires
 // parseShellCommand for runtime completion; the fallback `label` literal
 // renders when the transform returns "" (empty command).
 //
-// Security (Pitfall 4 — defense-in-depth):
+// Security (defense-in-depth):
 //   1) parseShellCommand self-redacts via redactValue at
 //      shell-label-parser.ts:53 — `grep sk-… /tmp/log` renders as
 //      `search for \`<redacted>\` in /tmp/log`.

package/node_modules/@comis/skills/dist/tools/builtin/file/apply-patch-parser.js

@@ -195,7 +195,7 @@ export function parsePatch(input) {
                     // We'll move them back to be context between change regions.
                     // For correctness of context matching in the tool, we keep them as
                     // contextAfter and the matcher must handle it.
-                    // Actually, re-examining: the plan says hunks are separated by @@.
+                    // Re-examining: in this patch format, hunks are separated by @@.
                     // Context after changes is trailing context. If more changes appear
                     // WITHOUT an @@ separator, they're part of the same hunk.
                     // We'll just keep accumulating in the same hunk.

package/node_modules/@comis/skills/dist/tools/builtin/file/safe-path-wrapper.d.ts

@@ -1,9 +1,6 @@
 /**
  * Shared types and constants for Comis file tools.
  *
- * Previously contained SafePath/PathSuggestion/FileStateGuards wrappers;
- * those were deleted when all file tools became Comis-native.
- *
  * @module
  */
 /**

package/node_modules/@comis/skills/dist/tools/builtin/file/safe-path-wrapper.js

@@ -2,9 +2,6 @@
 /**
  * Shared types and constants for Comis file tools.
  *
- * Previously contained SafePath/PathSuggestion/FileStateGuards wrappers;
- * those were deleted when all file tools became Comis-native.
- *
  * @module
  */
 /**

package/node_modules/@comis/skills/dist/tools/builtin/file-tools/shared/edit-diff.js

@@ -148,6 +148,55 @@ function countOccurrences(content, oldText) {
     const fuzzyOldText = normalizeForFuzzyMatch(oldText);
     return fuzzyContent.split(fuzzyOldText).length - 1;
 }
+/** Bounds for the not-found "closest actual text" hint (content-hygiene: a
+ *  few lines, each truncated — never a whole-file dump). */
+const NEAREST_HINT_MAX_LINES = 8;
+const NEAREST_HINT_MAX_LINE_CHARS = 200;
+/**
+ * Best-effort "closest actual text" hint for a not-found edit.
+ *
+ * When an `oldText` misses (exact + desanitized + fuzzy all fail), the raw
+ * "must match exactly" error tells the model WHAT rule it broke but not WHICH
+ * bytes differ — so it blindly re-reads and re-guesses (a live onboarding
+ * burned 8 edit calls on a single dropped "?"). This anchors on the FIRST
+ * `oldText` line whose trimmed form matches a file line and returns the REAL
+ * file block at that anchor, spanning `oldText`'s line count — surfacing the
+ * exact drift (e.g. a trailing "?") so the model fixes it in one retry.
+ *
+ * Returns `""` when no `oldText` line anchors (no misleading guess). Pure;
+ * bounded to {@link NEAREST_HINT_MAX_LINES} lines each truncated to
+ * {@link NEAREST_HINT_MAX_LINE_CHARS} chars.
+ */
+function describeNearestText(content, oldText) {
+    const oldLines = oldText.split("\n");
+    const contentLines = content.split("\n");
+    // Anchor: the first non-trivial oldText line whose TRIMMED form matches a
+    // file line (indentation drift tolerated). The label line usually matches;
+    // it is the placeholder VALUE below it that drifted.
+    let anchorFileIdx = -1;
+    let anchorOldIdx = -1;
+    for (let oi = 0; oi < oldLines.length; oi++) {
+        const needle = oldLines[oi].trim();
+        if (needle.length < 3)
+            continue; // skip blank / trivial lines
+        const found = contentLines.findIndex((l) => l.trim() === needle);
+        if (found !== -1) {
+            anchorFileIdx = found;
+            anchorOldIdx = oi;
+            break;
+        }
+    }
+    if (anchorFileIdx === -1)
+        return "";
+    // Place the block where oldText's first line would sit relative to the anchor.
+    const blockStart = Math.max(0, anchorFileIdx - anchorOldIdx);
+    const blockLen = Math.min(oldLines.length, NEAREST_HINT_MAX_LINES);
+    const block = contentLines
+        .slice(blockStart, blockStart + blockLen)
+        .map((l) => (l.length > NEAREST_HINT_MAX_LINE_CHARS ? l.slice(0, NEAREST_HINT_MAX_LINE_CHARS) + "…" : l))
+        .join("\n");
+    return ` Closest actual text at line ${blockStart + 1}:\n${block}`;
+}
 /**
  * Apply one or more exact-text replacements to LF-normalized content.
  *
@@ -195,7 +244,8 @@ export function applyEdits(content, edits, filePath) {
                 const fuzzyResult = findMatch(baseContent, edit.oldText);
                 if (!fuzzyResult) {
                     throw new Error(`[text_not_found] The old_text in edits[${i}] was not found in ${filePath}. ` +
-                        `Make sure it matches exactly (including whitespace and indentation).`);
+                        `Make sure it matches exactly (including whitespace and indentation).` +
+                        describeNearestText(baseContent, edit.oldText));
                 }
                 // Fuzzy found a single match -- use it, but note encoding diff
                 matchedEdits.push({
@@ -227,10 +277,11 @@ export function applyEdits(content, edits, filePath) {
             // Single-match logic (existing behavior)
             const matchResult = findMatch(baseContent, edit.oldText);
             if (!matchResult) {
+                const hint = describeNearestText(baseContent, edit.oldText);
                 if (normalizedEdits.length === 1) {
-                    throw new Error(`Could not find the exact text in ${filePath}. The old text must match exactly including all whitespace and newlines.`);
+                    throw new Error(`Could not find the exact text in ${filePath}. The old text must match exactly including all whitespace and newlines.${hint}`);
                 }
-                throw new Error(`Could not find edits[${i}] in ${filePath}. The oldText must match exactly including all whitespace and newlines.`);
+                throw new Error(`Could not find edits[${i}] in ${filePath}. The oldText must match exactly including all whitespace and newlines.${hint}`);
             }
             const occurrences = countOccurrences(baseContent, edit.oldText);
             if (occurrences > 1) {

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/comis-agent-cli.js

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * `comis-agent-cli` — the in-jail `comis-agent` CLI body (Surface 3, v8 §7).
+ * `comis-agent-cli` — the in-jail `comis-agent` CLI body (Surface 3).
  * {@link runComisAgent} parses an attacker-controlled argv (the agent's own
  * script) into EXACTLY ONE cap-socket call and dispatches it via the injected
- * {@link callCapSocket} (CLI-04 — the lease cap socket, never a WebSocket /
+ * {@link callCapSocket} (the lease cap socket, never a WebSocket /
  * gateway client). A `{kind:"tool"}` subcommand rides `tool.invoke`
  * (`callCapSocket("tool.invoke", { tool, args })`); a `{kind:"method"}`
  * subcommand sends the DIRECT method (`callCapSocket(method, params)`).
@@ -14,9 +14,9 @@
  * `requireCapability` decide (a denial surfaces as the endpoint's content-free
  * message, never re-implemented here). An unknown subcommand — including the
  * deliberately-absent `skill` (denylisted orch:skill closed door) and the admin
- * verbs `secrets`/`config`/`tokens` (CLI-03) — exits non-zero WITHOUT touching
+ * verbs `secrets`/`config`/`tokens` — exits non-zero WITHOUT touching
  * the socket. A missing lease loud-fails (the {@link callCapSocket} reject
- * surfaces as a non-zero exit + a loud stderr naming the env + "jail", CLI-06).
+ * surfaces as a non-zero exit + a loud stderr naming the env + "jail").
  *
  * Containment (AGENTS.md §2.3): this runs INSIDE the orchestrate jail, so the
  * parser is deliberately DEPENDENCY-FREE — a tiny hand-rolled flag/positional

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/comis-agent-entry.js

@@ -2,14 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * `comis-agent` entrypoint — the `#!/usr/bin/env node` binary bound read-only
- * into the orchestrate jail (Plan 06 sha256-pins + binds this dist file beside
+ * into the orchestrate jail (sha256-pins + binds this dist file beside
  * the daemon `node` binary). It wires the REAL {@link callCapSocket} (the lease
  * cap socket wire) into {@link runComisAgent} and exits with the returned code.
  *
  * This file holds NO logic beyond the wiring — the parse/dispatch lives in
  * `comis-agent-cli.ts` (so it is unit-testable over a fake callCapSocket). The
  * only egress is {@link callCapSocket}; there is deliberately no WebSocket /
- * gateway client (CLI-04) and no argv-parsing dependency (§2.3).
+ * gateway client and no argv-parsing dependency (AGENTS.md §2.3).
  *
  * @module
  */

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/comis-agent-manifest.json

@@ -1,4 +1,4 @@
 {
   "file": "comis-agent-entry.js",
-  "sha256": "c0f61d11f508c51cc2fcbaf846cb04dcdd6462b6cd15ffa6eea1d7082d66de48"
+  "sha256": "40d89834ff675f96cceafe42f94df6773640770c33c12e64e80e7585ee9405ba"
 }

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/comis_tools.d.ts

@@ -44,6 +44,8 @@ export interface ToolDescriptor {
   readonly capability: string;
   /** A one-line human summary of what the tool does. */
   readonly summary: string;
+  /** A worked calling-pattern example for the tool's capability group. */
+  readonly example: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -59,38 +61,52 @@ export interface ComisTools {
    * a specific tool's full types.
    */
   describe(): ToolDescriptor[];
-  /** Extract readable text from a document (pdf/docx/…). (capability: orch:read) */
+  /** Persist this run's state so it survives a restart: comis_tools.checkpoint(state). Durable (longer TTL), capped like any result; requires the resume surface. (capability: orch:write) Example: await comis_tools.write({ path: 'summary.md', content: '# Findings' }); */
+  checkpoint(args?: Record<string, unknown>): Promise<unknown>;
+  /** Extract readable text from a document (pdf/docx/…). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   extract_document(args?: Record<string, unknown>): Promise<ResultRef>;
-  /** Find files in the jailed workspace by name/glob. (capability: orch:read) */
+  /** Find files in the jailed workspace by name/glob. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   find(args?: Record<string, unknown>): Promise<unknown>;
-  /** Search the jailed workspace for a pattern (recursive). (capability: orch:read) */
+  /** Search the jailed workspace for a pattern (recursive). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   grep(args?: Record<string, unknown>): Promise<ResultRef>;
-  /** Run a jq expression over JSON (a value or a ResultRef). (capability: orch:read) */
+  /** Run a jq expression over JSON (a value or a ResultRef). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   jq(args?: Record<string, unknown>): Promise<unknown>;
-  /** Extract a precise value from a JSON ResultRef via JSONPath (no eval). (capability: orch:read) */
+  /** Extract a precise value from a JSON ResultRef via JSONPath (no eval). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   jsonpath(args?: Record<string, unknown>): Promise<unknown>;
-  /** List a directory in the jailed workspace. (capability: orch:read) */
+  /** List a directory in the jailed workspace. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   ls(args?: Record<string, unknown>): Promise<unknown>;
-  /** Fetch a specific memory file by id (self-tenant). (capability: orch:read) */
+  /** Call an allowlisted connected MCP server's tool: comis_tools.mcp.<server>.<tool>(args). The server/tool set is operator-configured. (capability: orch:mcp) Example: const result = await comis_tools.mcp.myserver.mytool({ query: 'hello' }); */
+  mcp: Record<string, Record<string, (args?: Record<string, unknown>) => Promise<unknown>>>;
+  /** Fetch a specific memory file by id (self-tenant). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   memory_get(args?: Record<string, unknown>): Promise<unknown>;
-  /** Search the agent's long-term memory (self-tenant). (capability: orch:read) */
+  /** Search the agent's long-term memory (self-tenant). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   memory_search(args?: Record<string, unknown>): Promise<unknown>;
-  /** Read a file from the jailed workspace (offset/limit). (capability: orch:read) */
+  /** Read a file from the jailed workspace (offset/limit). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   read(args?: Record<string, unknown>): Promise<ResultRef>;
-  /** Search across the agent's own session history. (capability: orch:read) */
+  /** Return this run's last checkpoint state (wrapped as data, never executed) or null if none: comis_tools.resume(). Requires the resume surface. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
+  resume(args?: Record<string, unknown>): Promise<unknown>;
+  /** Search across the agent's own session history. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   session_search(args?: Record<string, unknown>): Promise<unknown>;
-  /** Read the status of one of the agent's sessions. (capability: orch:read) */
+  /** Read the status of one of the agent's sessions. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   session_status(args?: Record<string, unknown>): Promise<unknown>;
-  /** Read the message history of the agent's own session. (capability: orch:read) */
+  /** Read the message history of the agent's own session. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   sessions_history(args?: Record<string, unknown>): Promise<unknown>;
-  /** List the agent's own sessions. (capability: orch:read) */
+  /** List the agent's own sessions. (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   sessions_list(args?: Record<string, unknown>): Promise<unknown>;
-  /** Run DuckDB SQL over a CSV/JSONL/JSON ResultRef (daemon-side, read-only). (capability: orch:read) */
+  /** Run DuckDB SQL over a CSV/JSONL/JSON ResultRef (daemon-side, read-only). (capability: orch:read) Example: const ref = await comis_tools.grep({ path: 'logs/app.jsonl', pattern: 'ERROR' }); const rows = await ref.jq('.[0:20]'); const head = await ref.read(0, 40); */
   sql(args?: Record<string, unknown>): Promise<unknown>;
-  /** Fetch a URL's readable content (daemon-side, DNS-pinned). (capability: orch:web) */
+  /** Fetch a URL's readable content (daemon-side, DNS-pinned). (capability: orch:web) Example: const hits = await comis_tools.web_search({ query: 'site reliability' }); const top3 = await hits.jq('.[0:3]'); const page = await comis_tools.web_fetch({ url: top3[0].url }); const text = await page.read(0, 200); */
   web_fetch(args?: Record<string, unknown>): Promise<ResultRef>;
-  /** Search the web (daemon-side, DNS-pinned). (capability: orch:web) */
+  /** Search the web (daemon-side, DNS-pinned). (capability: orch:web) Example: const hits = await comis_tools.web_search({ query: 'site reliability' }); const top3 = await hits.jq('.[0:3]'); const page = await comis_tools.web_fetch({ url: top3[0].url }); const text = await page.read(0, 200); */
   web_search(args?: Record<string, unknown>): Promise<ResultRef>;
+  /** Write a file into the jailed run workspace (path-confined, run-ephemeral). (capability: orch:write) Example: await comis_tools.write({ path: 'summary.md', content: '# Findings' }); */
+  write(args?: Record<string, unknown>): Promise<unknown>;
+  /** Send a message to a channel (outward). (capability: orch:message) */
+  message_send(args?: Record<string, unknown>): Promise<unknown>;
+  /** Reply to a message in a channel (outward). (capability: orch:message) */
+  message_reply(args?: Record<string, unknown>): Promise<unknown>;
+  /** React to a message with an emoji (outward). (capability: orch:message) */
+  message_react(args?: Record<string, unknown>): Promise<unknown>;
 }
 
 /** The singleton typed SDK the jailed script imports. */