@descryy/mcp 0.6.0 → 0.7.1

package/dist/tools/observe-runtime.js

@@ -1,137 +1,22 @@
 /**
- * `observe_runtime` — boot or attach to a real application, watch it, and write
- * what was witnessed into the graph as R4 facts.
- *
- * **The second tool that writes, and the first that writes something no
- * re-index can reproduce.** `analyze` re-derives the graph from source already
- * on disk, so nothing it writes is a new claim about the world. This one runs
- * a real process and records what it saw happen, which is the one accuracy
- * source architecture §11B.3 calls *"the core technical moat"* and the one a
- * purely static tool is structurally unable to reach: *"a purely static
- * code-graph tool is capped at R3 permanently. It has no runtime."*
- *
- * ## What this composes, and what it invents
- *
- * It invents no mechanism. Every stage already existed, gate-verified, in
- * `descry-runtime`, and every one of them was dormant — the whole point of
- * `DEC-NEXT-mcp-runtime-dependency-boundary-for-r4-evidence`, which measured
- * that `applyRuntimeObservations` had **zero production callers anywhere**,
- * not in `descry-desktop` and not in `descry-runtime`'s own pipeline. Four
- * shipped components in a row, and this tool is the wire between them:
- *
- * 1. `runInstrumentedExecution` (`@descryy/runtime-orchestrator`) spawns or
- *    attaches the declared services, starts the adapter's collectors, drains
- *    them for a stated window, and writes every item through `EvidenceStore`.
- * 2. `correlateExecution` (`@descryy/runtime-evidence-correlation`) resolves
- *    each evidence item to the graph node it is *about* — the resolve-then-
- *    attribute pass. This answers identity, not edges.
- * 3. `confirmObservedFrontendCaller` (`@descryy/runtime-graph-correlator`)
- *    turns a captured call-site stack plus a resolved endpoint into a
- *    `RuntimeEdgeObservation`, and
- * 4. calls `applyRuntimeObservations` (`@descryy/core`) with it, which
- *    promotes, mints or contradicts the edge and writes the EARNED ledger.
- *
- * ## Why stage 3 exists rather than deriving edges from stage 2 directly
- *
- * `uat-phase-1-bug-fixes.md` Phase 2 describes step 2 as producing
- * `RuntimeEdgeObservation[]`. It does not, and the difference is load-bearing
- * rather than pedantic: `correlateExecution` returns
- * `CorrelationAttribution`s — *(evidenceId, graphNodeId)* pairs saying which
- * single node an observation is about. An edge needs **two** endpoints and a
- * witnessed relationship between them, and manufacturing one by pairing up
- * attributions that happen to co-occur in the same run would mint edges from
- * temporal coincidence. That is precisely the wrong-direction failure rule 2
- * exists to prevent, arriving through the one mechanism built to make the
- * graph *more* trustworthy.
- *
- * So the observation comes from the one shipped producer that can honestly
- * make one: a captured stack naming the caller, against an endpoint the same
- * observation named. Both endpoints come from the observation itself. Every
- * other correlated item is reported in the counts and produces no edge, which
- * is a disclosed gap rather than a silent one.
- *
- * ## What this closure can actually witness today — measured, not assumed
- *
- * The wire is complete, and what it can carry changed when the runtime packages
- * were published at 0.1.0 and pinned here — so this paragraph is the record of
- * a limit that was real and is now lifted, kept rather than deleted because the
- * shape of it recurs.
- *
- * **It used to be that no producer of the required pair — HTTP evidence
- * carrying a call-site stack — was in this server's closure.** The browser
- * network collector never has been. The outbound-fetch instrumentation in
- * `@descryy/runtime-external-service-observation` existed, was proven in
- * `descry-runtime`, and was not installed here at all. So a run resolved both
- * kinds of node and wrote no edge, and `STANDING_NOTES` said so on every call
- * because "no edge was written" and "nothing here could have written one" are
- * different statements.
- *
- * **That second producer is now in the closure**, transitively through
- * `@descryy/runtime-orchestrator`, which applies the adapter's
- * `outboundHttpLaunch()` between the interpreter and the script so the client
- * is patched before any application code can capture an unpatched one. Measured
- * end to end in `observe-runtime-outbound.conformance.test.ts`: two real
- * processes, 17 `EXTERNAL_REQUEST` items alongside 18 `BACKEND_LOG`, one
- * `USES_API` edge minted at R4, and the first `strongly supported` reply this
- * server has produced.
- *
- * **Two limits remain, and they are stated rather than inferred from a zero.**
- * An *attached* service is not launched by Descry, so the instrumentation
- * cannot be installed into it and its outbound calls carry no stack. And
- * browser-side traffic still needs `@descryy/runtime-browser`, which is not
- * here. Both are in `STANDING_NOTES`.
- *
- * The rule that outlives all of it: a disclosure about the closure is a fact
- * about *this build*, not about what `descry-runtime` can do. The two came
- * apart once already, when the cross-boundary lane landed and this file still
- * claimed the capability was absent. Re-check it against the installed tree
- * when the pins move, not against the source repository.
- * Descry.
- *
- * ## Why no denial is ever emitted
- *
- * `applyRuntimeObservations` accepts `held: false`. Nothing here ever sends
- * one, and `confirmObservedFrontendCaller`'s own header explains why: a run
- * establishes that a call *happened*; it cannot establish that one did not,
- * because a run exercises the paths it happens to take. Demoting a correct
- * edge on the strength of a route this run did not visit would be worse than
- * never running.
- *
- * ## Class and tier
- *
- * `action` — DEC-278's own test is *"can this call's effect change a later
- * finding without the developer having said so"*, and this one spawns
- * processes and writes R4 edges that cap every later reliability class
- * differently. It is gated by the same two-call `confirmToken` handshake
- * `questions` uses, and additionally by the environment profile's declared
- * `safetyLevel` (DEC-270): booting a service is a **write** against the
- * target, so a `readOnly` profile refuses. An all-attach run is genuinely
- * read-only — `ServiceConfiguration.attach`'s own contract is that Descry
- * never executes code in, or applies limits to, a process it did not spawn —
- * so it is allowed under `readOnly`, and that distinction is stated in the
- * disclosures rather than inferred silently.
- *
- * `evidence` — it reports what was witnessed and what was written. It draws no
- * conclusion about the user's code; nothing here reads or writes a finding, a
- * hypothesis or a category (RT-027).
- *
- * ## No new query tools
- *
- * None are needed and none are added. `impact`, `propagation` and the rest
- * already read the `resolution` field, so an edge this tool promotes to R4
- * becomes visible through every one of them on the next call, with no change
- * to any of them.
- */
+ * `observe_runtime` — boot or attach to a real application, write what was witnessed into the
+ * graph as R4 facts. Composes existing descry-runtime stages, no new mechanism (DEC-NEXT-mcp-
+ * runtime-dependency-boundary-for-r4-evidence). `action`/`evidence` (DEC-278), gated by
+ * confirmToken + profile safetyLevel (DEC-270). Never emits a denial. */
 import { mkdir } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import { independentSignalTypes } from "@descryy/ir";
+import { checkNotSensitivePath, checkPathConfinement } from "../path-confinement.js";
+/** A-F6 escape hatches — see path-confinement.ts. */
+const ALLOW_EVIDENCE_PATH_OUTSIDE_REPO_ENV_VAR = "DESCRY_ALLOW_EVIDENCE_PATH_OUTSIDE_REPO";
+const ALLOW_SENSITIVE_LOG_PATH_ENV_VAR = "DESCRY_ALLOW_SENSITIVE_LOG_PATH";
 import { buildGraph, counts, createConfirmedIncidentSource, persistGraph, } from "@descryy/core";
 import { evaluateAction, validateProfile } from "@descryy/runtime-environment-profile";
 import { correlateExecution } from "@descryy/runtime-evidence-correlation";
 import { EvidenceStore } from "@descryy/runtime-evidence-store";
 import { confirmObservedFrontendCaller } from "@descryy/runtime-graph-correlator";
 import { runInstrumentedExecution } from "@descryy/runtime-orchestrator";
-import { answer, optionalInteger, optionalString, ToolInputError, } from "./kit.js";
+import { answer, optionalEnum, optionalInteger, optionalString, ToolInputError, } from "./kit.js";
 import { cancellationHeadline, cancellationNotes, whenAborted } from "../cancellation.js";
 import { loadRuntimeAdapter, RuntimeAdapterLoadError } from "../runtime-registry.js";
 import { writeConfirmedIncident } from "../session.js";
@@ -186,10 +71,8 @@ const SCHEMA = {
                             "an \"http\" or \"tcp-port\" check it is not needed at all, because nothing is " +
                             "started and Descry never executes code in a process it did not spawn.",
                     },
-                    // The description below is the fix for the single most expensive
-                    // ergonomic gap this tool has: three failed runs in one real
-                    // investigation, all the same root cause wearing different clothes,
-                    // and the explanation both times living in a source comment.
+                    // Fixes the tool's costliest ergonomic gap: 3 failed runs in one real investigation,
+                    // same root cause, explanation previously living only in a source comment.
                     port: {
                         type: "integer",
                         description: "The port readiness checks against, and the two modes need opposite things from you. " +
@@ -306,6 +189,51 @@ const SCHEMA = {
             type: "string",
             description: `Where the evidence database lives. Defaults to ${DEFAULT_EVIDENCE_RELATIVE_PATH} under the repository root.`,
         },
+        resourceLimits: {
+            type: "object",
+            description: "A-F5: caps on a spawned service, enforced by the OS (prlimit) — never applied to an attached " +
+                "service, since Descry did not start it. Absent means unconstrained, which every reply discloses.",
+            properties: {
+                maxMemoryBytes: { type: "integer", description: "Virtual address space cap (prlimit --as)." },
+                maxCpuSeconds: { type: "integer", description: "CPU time cap, in seconds (prlimit --cpu)." },
+                maxProcesses: { type: "integer", description: "Process count cap, per real uid (prlimit --nproc)." },
+            },
+            additionalProperties: false,
+        },
+        filesystemPolicy: {
+            type: "object",
+            description: "A-F5: confines a spawned service's filesystem view to its own cwd plus these roots — real on " +
+                "Linux (a bwrap mount namespace; everything else is not merely unreadable, it is not mounted at " +
+                "all), refused rather than silently unenforced elsewhere. Absent means unconstrained.",
+            properties: {
+                allowedRoots: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Absolute paths visible read-write in addition to the service's own cwd.",
+                },
+            },
+            required: ["allowedRoots"],
+            additionalProperties: false,
+        },
+        networkPolicy: {
+            type: "object",
+            description: 'A-F5: only { mode: "allow", hosts: [] } (full denial) is actually enforced today — a network ' +
+                "namespace holding nothing but an unreachable loopback. Any other shape refuses the run rather " +
+                "than starting unconstrained under a policy nobody enforced. Absent means unconstrained.",
+            properties: {
+                mode: { type: "string", enum: ["allow", "deny"] },
+                hosts: { type: "array", items: { type: "string" } },
+            },
+            required: ["mode", "hosts"],
+            additionalProperties: false,
+        },
+        sandboxBackend: {
+            type: "string",
+            enum: ["bwrap", "container"],
+            description: 'Which mechanism enforces filesystemPolicy/networkPolicy. Defaults to "bwrap" (Linux-native). ' +
+                '"container" routes through a real Docker container instead — the only option on macOS/Windows, ' +
+                "and it does not compose with resourceLimits (disclosed on the reply when both are declared).",
+        },
         confirmToken: {
             type: "string",
             description: "The token returned by an unconfirmed call. This tool performs nothing without it: the first " +
@@ -317,9 +245,6 @@ const SCHEMA = {
     required: ["profile", "services", "adapter"],
     additionalProperties: false,
 };
-// ---------------------------------------------------------------------------
-// Argument reading. Hand-written, same reasoning as `kit.ts`'s own readers.
-// ---------------------------------------------------------------------------
 function asRecord(value, what) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new ToolInputError(`"${what}" must be an object`);
@@ -343,8 +268,7 @@ function readProfile(args) {
     };
     const errors = validateProfile(candidate);
     if (errors.length > 0) {
-        // The profile package's own error codes, verbatim — this tool adds no
-        // interpretation to a validation it did not perform.
+        // The profile package's own error codes, verbatim — no interpretation added here.
         throw new ToolInputError(`"profile" is not valid: ${errors.join(", ")}`);
     }
     return candidate;
@@ -385,25 +309,13 @@ function readServices(args, repoPath) {
         if (command !== undefined && typeof command !== "string") {
             throw new ToolInputError(`"services.${name}.command" must be a string`);
         }
-        // Read once, here, because two separate rules below need it: whether a
-        // `cwd` is required at all, and whether an attached service must state its
-        // port.
+        // Read once: two rules below need it (whether cwd is required, whether attach needs a port).
         const readinessRaw = entry["readiness"];
         const readinessKind = typeof readinessRaw === "object" && readinessRaw !== null && !Array.isArray(readinessRaw)
             ? readinessRaw["kind"]
             : undefined;
-        // `cwd` is required exactly where something will be executed in it, and
-        // nowhere else. Descry spawns nothing for an attached service and never
-        // executes code in a process it did not spawn, so for an attached service
-        // with an `http` or `tcp-port` check the value is inert — demanding it
-        // makes the caller invent a path that changes nothing. A `command` check
-        // *is* executed, in this directory, so it still needs one.
-        //
-        // The runtime contract's `ServiceConfiguration.cwd` is non-optional, so
-        // something must be supplied downstream either way; the repository root is
-        // the inert choice, and it is inert precisely because nothing runs there
-        // on this path.
-        // (`DEC-388`.)
+        // cwd required only where something executes in it: attach never runs code Descry didn't
+        // spawn, so http/tcp-port checks leave it inert; a "command" check does execute (DEC-388).
         const cwdRaw = entry["cwd"];
         if (cwdRaw !== undefined && (typeof cwdRaw !== "string" || cwdRaw === "")) {
             throw new ToolInputError(`"services.${name}.cwd" must be a non-empty string`);
@@ -447,20 +359,17 @@ function readServices(args, repoPath) {
             if (typeof logFilePath !== "string" || logFilePath === "") {
                 throw new ToolInputError(`"services.${name}.attach.logFilePath" is required`);
             }
+            // A-F6: logFilePath is read in full on every poll and can't be root-confined (a real
+            // log lives anywhere) — narrower, disclosed name-based check instead (path-confinement.ts).
+            const sensitivity = checkNotSensitivePath(logFilePath, ALLOW_SENSITIVE_LOG_PATH_ENV_VAR);
+            if (sensitivity.sensitive) {
+                throw new ToolInputError(`"services.${name}.attach.logFilePath": ${sensitivity.reason}`);
+            }
             attach = { pid, logFilePath };
-            // A spawned service gets an ephemeral port allocated for it; an attached
-            // one cannot, because the target chose its own port before Descry
-            // existed and nothing in a pid or a log path reveals which. The
-            // controller's refusal to guess is deliberate and right — but expressed
-            // as `port ?? 0`, it surfaces to a caller as a readiness check timing
-            // out against port 0 some seconds later, with the actual explanation
-            // living in a source comment they cannot see. Twice in one real
-            // investigation that cost a full failed run to rediscover. So it is
-            // refused here, by name, before anything starts.
-            //
-            // Only for the two checks that resolve a port. A "command" check runs an
-            // executable and never asks where the service listens, so demanding a
-            // port for it would be a second wrong answer in the other direction.
+            // An attached service's port can't be allocated or inferred — nothing in a pid or log
+            // path reveals it. Left as `port ?? 0` it silently times out against port 0; refused
+            // here by name instead (cost a full failed run to rediscover, twice). Not for "command"
+            // checks, which never ask where the service listens.
             if ((readinessKind === "http" || readinessKind === "tcp-port") && port === undefined) {
                 throw new ToolInputError(`"services.${name}.port" is required when "${name}" uses "attach" with a ` +
                     `"${readinessKind}" readiness check: the check needs a port and an attached target's ` +
@@ -484,16 +393,9 @@ function readServices(args, repoPath) {
         };
     });
 }
-/**
- * The JSON→`ReadinessCheck` mapping, and the two mechanisms it cannot express.
- *
- * `log-pattern` needs a `read()` closing over the `ManagedProcess` the
- * controller owns, and `custom-hook` is a function outright. Neither survives a
- * JSON boundary, and inventing a string-shaped stand-in for either would offer
- * a mechanism that silently is not the one named. They are absent from the
- * schema's enum and stated in the disclosures instead — rule 7, honest
- * degradation, applied to a capability rather than to a result.
- */
+/** JSON→ReadinessCheck mapping. `log-pattern`/`custom-hook` can't survive a JSON boundary
+ *  (one closes over a live process, the other is a function) — absent from the enum and
+ *  stated in disclosures instead (rule 7, applied to a capability, not just a result). */
 function readReadiness(raw, service, cwd) {
     const entry = asRecord(raw, `services.${service}.readiness`);
     const kind = entry["kind"];
@@ -505,12 +407,8 @@ function readReadiness(raw, service, cwd) {
         (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < 1)) {
         throw new ToolInputError(`"services.${service}.readiness.timeoutMs" must be a positive integer`);
     }
-    // Every field is validated **here**, not inside `checks`. The controller does
-    // not call `checks()` until the service has already spawned, so a bad
-    // argument validated lazily would surface as a failed run with a live process
-    // to clean up rather than as a rejected call that started nothing — and
-    // `ToolInputError`'s whole contract is that it is something the caller can
-    // fix before anything happens.
+    // Validated here, not lazily inside checks() — the controller only calls checks() after
+    // spawning, so a bad argument caught late means a live process to clean up.
     const path = typeof entry["path"] === "string" ? entry["path"] : "/";
     const expectedStatus = entry["expectedStatus"];
     if (expectedStatus !== undefined && typeof expectedStatus !== "number") {
@@ -584,9 +482,6 @@ function readScopes(args, declared, fallback) {
     }
     return scopes;
 }
-// ---------------------------------------------------------------------------
-// The run
-// ---------------------------------------------------------------------------
 const EMPTY_WRITE = {
     promoted: [],
     created: [],
@@ -595,14 +490,9 @@ const EMPTY_WRITE = {
     contradictions: [],
     staleR4: [],
 };
-/**
- * The disclosure every call carries, whatever it did.
- *
- * Stated unconditionally rather than only when it bites: a caller who does not
- * know that `log-pattern` readiness is unreachable here will write a
- * `tcp-port` check that passes the instant the socket binds and read the
- * resulting empty evidence as "the service produced nothing".
- */
+/** Stated unconditionally on every call, not only when it bites: a caller unaware
+ *  log-pattern readiness is unreachable will misread a tcp-port check's empty evidence
+ *  as "the service produced nothing". */
 const STANDING_NOTES = [
     "Readiness here offers only the three mechanisms JSON can state — http, tcp-port and command. " +
         "log-pattern and custom-hook need a function and are unreachable through this tool; a run that " +
@@ -625,30 +515,40 @@ const STANDING_NOTES = [
     "No denial is ever recorded. A run establishes that a call happened; it cannot establish that one " +
         "did not, because it exercises only the paths it took. Nothing here demotes an edge.",
 ];
-/**
- * Said on every run that attaches, because it explains an absence that
- * otherwise reads as a Descry defect — and did, in a real investigation, until
- * it was measured.
- *
- * A request fired partway through an observation window did not appear in the
- * evidence, and appeared in the log file afterwards. The obvious reading is
- * that observation stopped early. It did not: reproduced end to end against a
- * real attached service, a request fired at t≈5s of a 12s window landed in the
- * evidence store, timestamped correctly. What actually happens is one layer
- * out — a process whose stdout is redirected to a file is block-buffered, not
- * line-buffered, because the descriptor is not a terminal. Measured directly:
- * three lines written over 0.6s were still entirely absent from the file three
- * seconds later, and arrived only when the process flushed.
- *
- * Nothing in Descry can see those bytes; they are in the target's own
- * userspace buffer. So this is not a gap to close, it is a boundary to state —
- * and stating it is what separates "we did not see it" from "it was not
- * there", which is the whole difference this tool exists to preserve.
- *
- * Written for any redirected process, naming no language or framework: the
- * behaviour is the C standard library's, and a note scoped to one ecosystem
- * would invite one more such note per ecosystem.
- */
+/** A-F5: honest degradation about real isolation, said on every reply rather than left for
+ *  the caller to discover. applySandbox enforces resourceLimits/filesystemPolicy/networkPolicy
+ *  for real on Linux when declared; never applied to an attached service (Descry didn't spawn it). */
+function sandboxDisclosure(options) {
+    const { resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend } = options;
+    // True regardless of policy: spawnProcess merges the full ambient env into every spawned
+    // process and bwrap doesn't clear it — out of this repo's reach (DEC-NEXT-runtime-sandbox-residual-gaps).
+    const envCaveat = "This is unaffected by any policy above: the spawned process still receives this operator's full " +
+        "environment, secrets included — the merge happens in @descryy/runtime-controller's spawnProcess and " +
+        "cannot be narrowed from this server.";
+    if (resourceLimits === undefined && filesystemPolicy === undefined && networkPolicy === undefined) {
+        return ("No resourceLimits, filesystemPolicy or networkPolicy was declared for this run. Every spawned " +
+            "service therefore ran with no OS-enforced isolation: it can read and write anything this operator's " +
+            "account can, use as much memory/CPU/process count as the host allows, and reach any network this " +
+            "operator's account can reach, and it received this operator's full environment. Attached services " +
+            "are never sandboxed regardless — Descry did not spawn them. Declare resourceLimits/filesystemPolicy/" +
+            "networkPolicy to change the filesystem/network/resource part of this for a spawned service.");
+    }
+    const applied = [];
+    if (resourceLimits !== undefined)
+        applied.push("resourceLimits");
+    if (filesystemPolicy !== undefined)
+        applied.push(`filesystemPolicy (allowedRoots: ${filesystemPolicy.allowedRoots.join(", ") || "none beyond cwd"})`);
+    if (networkPolicy !== undefined)
+        applied.push(`networkPolicy (${networkPolicy.mode}: ${networkPolicy.hosts.join(", ") || "none"})`);
+    const backend = sandboxBackend ?? "bwrap";
+    return (`Declared for this run, applied to every spawned (never attached) service via the "${backend}" ` +
+        `backend: ${applied.join(", ")}. If any of these could not actually be enforced (wrong platform, an ` +
+        "unsupported networkPolicy shape, bwrap/Docker unavailable), the run refused to start rather than " +
+        `running unconstrained under a policy nobody enforced — see the headline if this reply is a refusal. ${envCaveat}`);
+}
+/** Said on every attaching run. Measured: a redirected process's stdout is block-buffered,
+ *  not line-buffered — 3 lines written over 0.6s were still absent from the file 3s later.
+ *  Nothing in Descry can see those bytes; a boundary to state, not a gap to close. */
 const ATTACH_BUFFERING_NOTE = "Attaching reads a file the target writes; it can only see what the target has already flushed " +
     "there. A process whose output is redirected to a file is usually block-buffered rather than " +
     "line-buffered — its own runtime holds whole lines in a userspace buffer, invisible from outside, " +
@@ -657,25 +557,73 @@ const ATTACH_BUFFERING_NOTE = "Attaching reads a file the target writes; it can
     "target's buffering and not evidence that it did nothing. Run the target with its output " +
     "unbuffered or line-buffered if the timing matters.";
 /**
- * Every argument this tool takes, read and validated in one place.
- *
- * Extracted from `run` so that `describeAction` can call it too. That is the
- * whole point of the extraction: an `action` tool's first call is the one a
- * caller makes *before* it has a token, and therefore the only cheap place to
- * learn its arguments are wrong. Minting a token, and a paragraph describing
- * an action, for a declaration that cannot possibly run asks a developer to
- * confirm something that was never going to happen — and delivers the real
- * refusal on the second call, after the confirmation.
- *
- * Nothing here touches the filesystem, spawns anything or reads the graph: it
- * is argument reading and nothing else, which is what makes it safe to run at
- * mint time, outside the call budget.
+ * RT-024, restated where a caller can actually see it.
  *
- * Ruled in `documents/decisions-inbox/DEC-387.md`.
- *
- * Exported for its own test: several of the argument rules are conditional and
- * cheaper to assert directly than through a full run.
+ * `attachToRunningProcess` (descry-runtime) already discloses this in its own
+ * source comment — `isProcessAlive` confirms *a* process with this pid
+ * exists, not that it is the one that wrote `logFilePath`, because pids are
+ * reused by the OS and nothing in a bare pid or path proves provenance. That
+ * comment reaches nobody calling this tool. A real run hit exactly the gap it
+ * describes: an unrelated orphaned process from an earlier failed boot wrote
+ * a crash trace into the same log path a live attach target used, and it was
+ * attributed to the live run with no indication anything could be wrong.
  */
+const ATTACH_IDENTITY_NOTE = "Attaching verifies the declared pid is alive and reads the declared log file; it does not verify " +
+    "the lines in that file actually came from that pid. A pid can be reused by the OS, and nothing in " +
+    "a bare pid or file path proves which process is writing to it — an unrelated process writing to " +
+    "the same path would be attributed to this run with no way to tell the two apart from here.";
+/** Every argument this tool takes (readArguments, below), extracted so describeAction can
+ *  call it too — catches a bad argument before minting a token for a run that could never
+ *  happen (DEC-387). Touches nothing; exported for its own test. */
+/** A-F5: ResourceLimits, straight through to ExecutionConfiguration. applyResourceLimits
+ *  already refuses rather than silently running unconstrained; this only reads the shape. */
+function readResourceLimits(args) {
+    const raw = args["resourceLimits"];
+    if (raw === undefined || raw === null)
+        return undefined;
+    const record = asRecord(raw, "resourceLimits");
+    const maxMemoryBytes = optionalInteger(record, "maxMemoryBytes", 1);
+    const maxCpuSeconds = optionalInteger(record, "maxCpuSeconds", 1);
+    const maxProcesses = optionalInteger(record, "maxProcesses", 1);
+    return {
+        ...(maxMemoryBytes === undefined ? {} : { maxMemoryBytes }),
+        ...(maxCpuSeconds === undefined ? {} : { maxCpuSeconds }),
+        ...(maxProcesses === undefined ? {} : { maxProcesses }),
+    };
+}
+/** A-F5: FilesystemPolicy. allowedRoots is required whenever filesystemPolicy is present —
+ *  an empty-roots policy silently means "cwd only", and that must be stated, not defaulted into. */
+function readFilesystemPolicy(args) {
+    const raw = args["filesystemPolicy"];
+    if (raw === undefined || raw === null)
+        return undefined;
+    const record = asRecord(raw, "filesystemPolicy");
+    const allowedRoots = record["allowedRoots"];
+    if (!Array.isArray(allowedRoots) || allowedRoots.some((r) => typeof r !== "string")) {
+        throw new ToolInputError('"filesystemPolicy.allowedRoots" must be an array of strings');
+    }
+    return { allowedRoots: allowedRoots };
+}
+/** A-F5: NetworkPolicy. Only `{mode:"allow", hosts:[]}` (full denial) is actually enforced
+ *  by applySandbox today; any other shape is accepted here and refused downstream by the
+ *  mechanism itself (execution.validationError), never pre-judged here (rule 1). */
+function readNetworkPolicy(args) {
+    const raw = args["networkPolicy"];
+    if (raw === undefined || raw === null)
+        return undefined;
+    const record = asRecord(raw, "networkPolicy");
+    const mode = optionalEnum(record, "mode", ["allow", "deny"]);
+    if (mode === undefined)
+        throw new ToolInputError('"networkPolicy.mode" is required');
+    const hosts = record["hosts"];
+    if (!Array.isArray(hosts) || hosts.some((h) => typeof h !== "string")) {
+        throw new ToolInputError('"networkPolicy.hosts" must be an array of strings');
+    }
+    return { mode, hosts: hosts };
+}
+function readSandboxBackend(args) {
+    return optionalEnum(args, "sandboxBackend", ["bwrap", "container"]);
+}
 export function readArguments(args, repoPath) {
     const profile = readProfile(args);
     const adapterSpec = readAdapterSpec(args);
@@ -687,31 +635,55 @@ export function readArguments(args, repoPath) {
         throw new ToolInputError('"fidelityLevel" must be 1, 2, 3 or 4');
     const environmentTier = optionalString(args, "environmentTier") ?? "tier-2-container";
     const evidenceArg = optionalString(args, "evidencePath");
-    const evidencePath = evidenceArg === undefined
+    const evidenceCandidate = evidenceArg === undefined
         ? join(repoPath, DEFAULT_EVIDENCE_RELATIVE_PATH)
         : isAbsolute(evidenceArg)
             ? evidenceArg
             : join(repoPath, evidenceArg);
-    return { profile, adapterSpec, declared, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath };
+    // A-F6: join() doesn't stop ".." escaping repoPath — confined by default (path-confinement.ts).
+    const confinement = checkPathConfinement({
+        candidate: evidenceCandidate,
+        allowedRoots: [repoPath],
+        envVar: ALLOW_EVIDENCE_PATH_OUTSIDE_REPO_ENV_VAR,
+        what: "evidencePath",
+    });
+    if (!confinement.allowed)
+        throw new ToolInputError(confinement.reason);
+    const evidencePath = confinement.resolved;
+    const resourceLimits = readResourceLimits(args);
+    const filesystemPolicy = readFilesystemPolicy(args);
+    const networkPolicy = readNetworkPolicy(args);
+    const sandboxBackend = readSandboxBackend(args);
+    return {
+        profile,
+        adapterSpec,
+        declared,
+        observeForMs,
+        timeoutMs,
+        fidelityRaw,
+        environmentTier,
+        evidencePath,
+        resourceLimits,
+        filesystemPolicy,
+        networkPolicy,
+        sandboxBackend,
+    };
 }
 async function run(args, ctx) {
     const session = ctx.session;
-    const { profile, adapterSpec, declared, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath } = readArguments(args, session.repoPath);
-    const notes = [...STANDING_NOTES];
-    // Added on the refusal paths too, deliberately. A caller who attaches and is
-    // then refused for some unrelated reason will fix that reason and attach
-    // again; telling them about the buffering only on the success path means
-    // telling them after the run whose result it would have explained.
-    if (declared.some((service) => service.attached))
-        notes.push(ATTACH_BUFFERING_NOTE);
+    const { profile, adapterSpec, declared, observeForMs, timeoutMs, fidelityRaw, environmentTier, evidencePath, resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend, } = readArguments(args, session.repoPath);
+    const notes = [...STANDING_NOTES, sandboxDisclosure({ resourceLimits, filesystemPolicy, networkPolicy, sandboxBackend })];
+    // Added on refusal paths too — telling the caller only on success means telling them
+    // after the run whose result it would have explained.
+    if (declared.some((service) => service.attached)) {
+        notes.push(ATTACH_BUFFERING_NOTE, ATTACH_IDENTITY_NOTE);
+    }
     const base = session.provider().baseStamp();
     const refuse = (headline, data = {}, extraNotes = []) => answer({
         headline,
         state: "refused",
         nameLevel: true,
-        // Nothing ran, so nothing was resolved. A refusal reporting the tier its
-        // successful path would have reached is the leaked-default this repo's
-        // own UAT already caught once elsewhere.
+        // Nothing ran, so nothing was resolved — never leak the tier a successful path would reach.
         resolutionFloor: 0,
         commitSha: base.commitSha,
         graphBuiltAt: base.graphBuiltAt,
@@ -730,11 +702,8 @@ async function run(args, ctx) {
             ...data,
         },
     });
-    // --- the safety gate ------------------------------------------------------
-    // Spawning is a write against the target; attaching is not (Descry never
-    // executes code in, signals, or applies limits to a process it did not
-    // spawn). So the action's shape depends on what was declared, and the
-    // profile's declared level decides — never the profile's name.
+    // Spawning is a write against the target; attaching is not (Descry never executes code in,
+    // signals, or limits a process it didn't spawn). The profile's declared level decides, never its name.
     const spawns = declared.some((service) => !service.attached);
     const action = { write: spawns, destructive: false };
     const decision = evaluateAction(profile, action);
@@ -750,10 +719,8 @@ async function run(args, ctx) {
             "applied no resource, filesystem or network policy to any process — Descry does not constrain " +
             "a process it did not spawn.");
     }
-    // --- the graph must exist -------------------------------------------------
-    // Correlation resolves evidence against this graph. Against an empty one it
-    // resolves nothing, and reporting that as a clean run with no findings would
-    // be the exact "empty means broken" collapse the five states exist to stop.
+    // Correlation resolves evidence against this graph; an empty graph resolving nothing must
+    // not be reported as a clean run with no findings — the "empty means broken" collapse.
     const driver = session.store().driver;
     const stored = counts(driver);
     if (stored.nodes === 0) {
@@ -791,25 +758,23 @@ async function run(args, ctx) {
         fidelityLevel: fidelityRaw,
         timeoutMs,
         services,
+        // A-F5: wired through to the controller's real bwrap/container isolation
+        // — see sandboxDisclosure() above for what this reply says about it.
+        ...(resourceLimits === undefined ? {} : { resourceLimits }),
+        ...(filesystemPolicy === undefined ? {} : { filesystemPolicy }),
+        ...(networkPolicy === undefined ? {} : { networkPolicy }),
+        ...(sandboxBackend === undefined ? {} : { sandboxBackend }),
     };
-    // Before anything is spawned. This tool boots somebody's application; doing
-    // that for a caller who has already gone leaves a real process running with
-    // nothing left that would ever stop it.
+    // Before anything is spawned — a caller who's already gone would leave a real process
+    // running with nothing left to ever stop it.
     if (ctx.signal.aborted) {
         return refuse(cancellationHeadline("no service was started") + " " + cancellationNotes("Nothing was spawned.")[0]);
     }
     await mkdir(dirname(evidencePath), { recursive: true });
     const evidenceStore = new EvidenceStore({ path: evidencePath });
-    /**
-     * The processes **this run started**, and only those.
-     *
-     * An `attach`-mode service was already running before this tool was called —
-     * it is the developer's own process, borrowed for the length of an
-     * observation. Killing it on a cancellation would destroy something this
-     * call never created, which is a worse failure than the leak being fixed.
-     * The spawn path is the one that is cleaned up, because it is the one this
-     * call is responsible for.
-     */
+    /** Processes **this run started**, and only those — an attach-mode service is the
+     *  developer's own process; killing it on cancellation would destroy something this
+     *  call never created. Only the spawn path is cleaned up. */
     const attached = new Set(declared.filter((service) => service.attached).map((service) => service.name));
     const spawnedPids = new Set();
     const abort = whenAborted(ctx.signal);
@@ -828,10 +793,8 @@ async function run(args, ctx) {
             },
             runOptions: {
                 readiness,
-                // The only channel that names a process while it is still alive.
-                // `Execution.processes` is complete when `runInstrumentedExecution`
-                // resolves, and by then the whole observation window has already been
-                // slept — which is exactly the stretch a cancellation lands in.
+                // The only channel naming a process while still alive — Execution.processes is
+                // complete only once the whole window has already slept, past where a cancel lands.
                 onProcessLifecycleEvent: (event) => {
                     if (event.kind !== "process-started" || attached.has(event.serviceName))
                         return;
@@ -843,12 +806,9 @@ async function run(args, ctx) {
             store: evidenceStore,
             observeForMs,
         });
-        // The window is not shortened by the kill above — the orchestrator sleeps
-        // it out and returns as it always does — so this is where a cancelled run
-        // stops. Nothing is correlated and nothing is written: an R4 edge is the
-        // one claim in this system that cannot be re-derived from source and
-        // checked later, and minting one from a run nobody watched to the end
-        // would put a fact into the graph that no later pass could question.
+        // The kill above doesn't shorten the window — this is where a cancelled run actually
+        // stops. Nothing is correlated or written: an R4 edge can't be re-derived and checked
+        // later, so minting one from a run nobody watched to the end would be unquestionable.
         if (ctx.signal.aborted) {
             return refuse(cancellationHeadline("the observed application was stopped"), {
                 executionId: execution.execution.executionId,
@@ -863,9 +823,8 @@ async function run(args, ctx) {
         const observed = describeServices(execution.execution.processes, declared);
         const evidenceByType = tally(execution.evidence);
         if (execution.validationError !== null) {
-            // The controller refused before spawning anything. That is a fact about
-            // the declaration, not about the application — no evidence, no
-            // correlation, and emphatically not "the service is clean".
+            // Refused before spawning — a fact about the declaration, not the application;
+            // emphatically not "the service is clean".
             return refuse(`The execution refused to start: ${execution.validationError}. Nothing was spawned, no ` +
                 "evidence was collected, and no graph edge was written.", {
                 executionState: execution.execution.state,
@@ -874,24 +833,9 @@ async function run(args, ctx) {
                 evidenceByType,
             });
         }
-        // **The declared budget expired before the observation window closed.**
-        // `timeoutMs` is published in this tool's schema as the whole-execution
-        // budget, and it reaches `ExecutionConfiguration` where the controller
-        // arms a timer for it — that timer kills the services and nothing else.
-        // Measured: an 8s budget on a live attach returned after ~90s, and a
-        // 1.5s budget over a 12s window returned after 12.3s with zero evidence,
-        // because the processes had been dead for the last 10.8s of a window
-        // nothing shortened (`DEC-NEXT-observe-runtime-timeout-budget-is-not-
-        // enforced.md`). The window is now clamped in the orchestrator; this is
-        // the other half — saying so.
-        //
-        // Reported as `timed_out` rather than `ok`. §6 calls that state "not a
-        // silent truncation and never a `failed`", which is exactly this run: the
-        // evidence below is real and the R4 writes below it are honest, there is
-        // simply less of both than was asked for. `ok` would make "we watched the
-        // whole window and it was quiet" indistinguishable from "we stopped
-        // watching a tenth of the way in", and a caller acting on the first
-        // concludes the application is fine.
+        // Budget expired before the window closed. Measured pre-clamp: a 1.5s budget over a 12s
+        // window returned at 12.3s with zero evidence (DEC-NEXT-observe-runtime-timeout-budget-
+        // is-not-enforced.md). Reported `timed_out`, not `ok` (§6) — real evidence, just less of it.
         const timedOut = execution.execution.state === "TIMED_OUT";
         if (timedOut) {
             notes.push(`This run hit its ${String(timeoutMs)}ms whole-execution budget before the ` +
@@ -916,16 +860,8 @@ async function run(args, ctx) {
             harnessErrors: pass.harnessErrors.map((e) => `${e.detail} (${String(e.occurrences)}×)`),
         };
         if (pass.unscopedServices.length > 0) {
-            // Two different sentences, because they call for two different actions
-            // and the first one used to be printed for both. A named service with no
-            // scope is something the caller can fix by supplying one. The `(no
-            // service)` sentinel is not: `correlateExecution` looks a scope up by
-            // `evidence.service`, and no collector in this dependency closure stamps
-            // one — measured by the conformance run, which prints a real V8 stack
-            // resolving to a real graph node and watches it go unasked. Telling a
-            // caller to name a scope they have no key for would send them after a
-            // fix that does not exist, which is the honest-degradation rule failing
-            // in the one place it acts.
+            // Two sentences, not one: a named service with no scope is fixable by the caller; the
+            // "(no service)" sentinel is not — no collector stamps one, so there's no key to supply.
             const named = pass.unscopedServices.filter((s) => s !== "(no service)");
             const anonymous = pass.unscopedServices.length - named.length;
             if (named.length > 0) {
@@ -948,10 +884,8 @@ async function run(args, ctx) {
                 "than a resolver honestly declining — each is written into the evidence stream as a " +
                 "COLLECTOR_ERROR, and the counts below are correspondingly incomplete.");
         }
-        // A service that died is a witnessed failure, and this run is the only
-        // thing that will ever have seen it. Recorded before the edge write so a
-        // failure in one does not silently cost the other.
-        // See `runtime-incident.ts` for why an EXCEPTION alone is not an incident.
+        // Recorded before the edge write so a failure in one doesn't silently cost the other.
+        // See runtime-incident.ts for why an EXCEPTION alone is not an incident.
         const incident = runtimeObservedIncident({
             repo: root.repo,
             repoRoot: root.absolutePath,
@@ -1004,33 +938,17 @@ async function run(args, ctx) {
             `${String(wrote.promoted.length)} edge(s) promoted to R4 and ${String(wrote.created.length)} minted at R4.`;
         return answer({
             headline,
-            // Deliberately not `empty` when nothing was witnessed: `empty` is a claim
-            // about the population, and "this run took no path that exercised the
-            // code" is not "this code does nothing". The counts say what happened.
-            //
-            // `timed_out` when the budget bound this run — see the block above. It
-            // is the same distinction one step further out: `empty` and `ok` both
-            // claim the window was watched to its end.
+            // Not `empty` when nothing was witnessed — `empty` claims the population, and "this run
+            // took no path exercising the code" isn't "this code does nothing". `timed_out` when the
+            // budget bound this run (see above): `empty`/`ok` both claim the window ran to its end.
             state: timedOut ? "timed_out" : "ok",
             nameLevel: true,
-            // R4 unconditionally, and honestly so — every fact in `wrote` was
-            // witnessed at runtime, which is the one resolution level that does not
-            // rest on inference (DEC-115). The correlated-but-unwritten items are
-            // not claimed here at all; they resolved a node and asserted nothing, so
-            // a run that wrote nothing reports R0 rather than borrowing the tier its
-            // successful path would have reached.
+            // R4 unconditionally: every `wrote` fact was witnessed at runtime (DEC-115, no inference).
+            // A run that wrote nothing reports R0 rather than borrowing the tier a success would reach.
             resolutionFloor: (written > 0 ? 4 : 0),
-            // G3's precondition and G4's `E`, declared because this run actually
-            // watched something. Only on a path where evidence really came back: a
-            // completed run that collected nothing witnessed nothing, and saying
-            // otherwise would assert a precondition on an empty array.
-            //
-            // Note this is deliberately *not* gated on `written > 0`. Whether an
-            // edge could be written is a fact about the graph path, and rule 3
-            // already caps the category through `resolutionFloor` just above — a
-            // run that saw three channels and wrote no edge is reported
-            // `unconfirmed` by the cap, not by pretending it saw nothing. Two
-            // separate facts, each stated once.
+            // G3/G4's E, declared only when evidence actually came back — not gated on `written > 0`:
+            // rule 3 already caps the category via resolutionFloor above, so a run that saw channels
+            // but wrote no edge is `unconfirmed` by that cap, not by pretending it saw nothing.
             ...(execution.evidence.length === 0
                 ? {}
                 : { runtimeEvidence: { independentSignalTypes: witnessedSignalTypes(execution.evidence) } }),
@@ -1056,16 +974,8 @@ async function run(args, ctx) {
         evidenceStore.close();
     }
 }
-/**
- * Stop a process this run spawned, and the group it leads.
- *
- * The controller spawns detached specifically so a service that forks — a dev
- * server that runs a compiler, a runtime that supervises a worker — can be
- * stopped whole. Signalling the leader alone would reap the parent and leave
- * its children holding the port, which reads as a successful cleanup and is
- * not one. `ESRCH` is the ordinary case, not an error: the process may have
- * exited on its own between the abort and this call.
- */
+/** Stop a process this run spawned, and the group it leads — signalling the leader alone
+ *  would leave forked children holding the port. ESRCH is ordinary: it may have already exited. */
 function terminateSpawnedProcess(pid) {
     try {
         process.kill(-pid, "SIGTERM");
@@ -1082,12 +992,8 @@ function terminateSpawnedProcess(pid) {
         // Already gone. Nothing to report and nothing to do.
     }
 }
-/**
- * One row per **declared** service, not one per spawned process — a service
- * that never started must appear with `started: false` rather than vanish from
- * the list, which is the difference between "it ran and did nothing" and "it
- * never ran".
- */
+/** One row per **declared** service, not per spawned process — a never-started service
+ *  appears with `started: false` rather than vanishing ("it did nothing" vs "it never ran"). */
 function describeServices(processes, declared) {
     const byService = new Map();
     for (const handle of processes) {
@@ -1113,32 +1019,9 @@ function tally(evidence) {
         byType[item.eventType] = (byType[item.eventType] ?? 0) + 1;
     return byType;
 }
-/**
- * One evidence row onto one of `@descryy/ir`'s six `RUNTIME_SIGNAL_TYPES`, or
- * `null`.
- *
- * **Decided by `eventType`, with `source` consulted only where the event type
- * is genuinely ambiguous** — an exception can come off a browser console or a
- * backend process, and nothing but the collector says which. The obvious
- * alternative, reading `source` alone, is wrong and was measured to be wrong
- * rather than reasoned about: every row this repository's own conformance run
- * produces carries `source: "backend-process"`, and `EVIDENCE_SOURCES` also
- * has a `backend-log` value that nothing in the shipped dependency closure
- * emits. A source-driven table would have counted zero channels on every real
- * run while passing a hand-built test — the exact shape of failure that gets
- * caught by running the thing.
- *
- * **Everything not listed returns `null` and is counted as nothing.** That is
- * `RuntimeEvidence`'s own rule, not caution added here: `TEST_*` is excluded
- * by design (its evidentiary weight is `M`'s, never double-counted as a
- * channel too), harness actions are Descry driving the application rather than
- * observing it, process lifecycle is a fact about the process rather than
- * about its behaviour, and a collector or version-mismatch error is a fact
- * about the run. A kind this table has not ruled on must fail closed, because
- * the alternative — mapping it to the nearest-looking channel — raises `E`,
- * and therefore the reported category, with nobody having decided that it
- * should.
- */
+/** One evidence row onto one of @descryy/ir's six RUNTIME_SIGNAL_TYPES, or null. Decided by
+ *  `eventType`; `source` consulted only for the ambiguous EXCEPTION/STACK_TRACE pair (reading
+ *  `source` alone was measured wrong). Unlisted kinds fail closed to null, never guess-mapped. */
 function signalOf(item) {
     switch (item.eventType) {
         case "CONSOLE_MESSAGE":
@@ -1157,9 +1040,7 @@ function signalOf(item) {
             return "database";
         case "EXTERNAL_REQUEST":
             return "external-service";
-        // The ambiguous pair, and the only place `source` decides: a thrown error
-        // reaches Descry through whichever collector saw it, and that collector is
-        // the channel.
+        // The ambiguous pair: a thrown error reaches Descry through whichever collector saw it.
         case "EXCEPTION":
         case "STACK_TRACE":
             return item.source === "browser-console" ? "browser-console" : "backend-log";
@@ -1167,31 +1048,15 @@ function signalOf(item) {
             return null;
     }
 }
-/**
- * `E` for this run — how many of the six channels it actually saw.
- *
- * The count itself is `@descryy/ir`'s `independentSignalTypes`, deliberately:
- * the clamp to six and the drop of `null` signals are that function's rules,
- * and a second implementation of them here is a second place for the
- * vocabulary to drift. This function's only job is the translation above.
- *
- * Exported for its own test — the mapping decides whether a witnessed answer
- * reads `strongly supported` or `unconfirmed`, which is too load-bearing to be
- * asserted only through a category two layers downstream.
- */
+/** `E` for this run — channels actually seen, via @descryy/ir's independentSignalTypes
+ *  (clamp-to-six and null-drop are that function's rules, not duplicated here). Exported for
+ *  its own test — this mapping decides `strongly supported` vs `unconfirmed`. */
 export function witnessedSignalTypes(evidence) {
     return independentSignalTypes(evidence.map((item) => ({ signal: signalOf(item), detail: item.eventType })));
 }
-/**
- * The R4 write, and the one join this tool performs itself.
- *
- * For every evidence item the correlation pass resolved to an endpoint, if that
- * same item also carried a call-site stack, ask `confirmObservedFrontendCaller`
- * whether the stack names a function — and when it does, it writes. Both
- * endpoints of the resulting edge come from the one observation; nothing here
- * pairs two separate items together. See the module header for why that
- * restraint is the whole design rather than a limitation of it.
- */
+/** The R4 write, and the one join this tool performs: for every evidence item resolved to an
+ *  endpoint that also carries a call-site stack, ask confirmObservedFrontendCaller. Both
+ *  endpoints come from one observation — nothing here pairs two separate items (see header). */
 function writeObservations(input) {
     const promoted = [];
     const created = [];
@@ -1199,19 +1064,13 @@ function writeObservations(input) {
     const refused = [];
     const contradictions = [];
     const staleR4 = [];
-    // One evidence item can be attributed twice (an endpoint and a second naming
-    // the same line carries). Keyed on both so the same (evidence, endpoint) pair
-    // is never confirmed twice within one run.
+    // One evidence item can be attributed twice; keyed on both so the same (evidence,
+    // endpoint) pair is never confirmed twice within one run.
     const seen = new Set();
     for (const attribution of input.pass.attributed) {
-        // `endpoint` only, and `log-text-endpoint` deliberately excluded. That
-        // family fires when a backend log LINE mentions a route and carries its
-        // own stack frame — which establishes that the function logged about the
-        // endpoint, not that it called it. The commonest real shape is a handler
-        // logging "GET /invoices -> 500", and that function SERVES the endpoint
-        // rather than USING it, so an edge minted from it could point the wrong
-        // way. Rule 2: a wrong edge corrupts diff scoping, impact scores and
-        // root-cause traversal; a missing one is a disclosed gap. Omitted.
+        // "endpoint" only — "log-text-endpoint" fires when a log line mentions a route, which
+        // means the function SERVES it, not calls it; minting from that could point the wrong
+        // way. Rule 2: a wrong edge is worse than a missing (disclosed) one. Omitted.
         if (attribution.family !== "endpoint")
             continue;
         const key = `${attribution.evidenceId}::${attribution.graphNodeId}`;
@@ -1238,29 +1097,9 @@ function writeObservations(input) {
     }
     return { promoted, created, confirmed, refused, contradictions, staleR4 };
 }
-/**
- * What confirming this call would do, in the caller's own terms.
- *
- * Always returns a sentence — unlike `questions`, whose unconfirmed shape is a
- * genuine pure read of the question queue, there is no argument to this tool
- * that makes it not run anything. Every valid call spawns or attaches, and
- * every one of them can write.
- */
-/**
- * §7's `willDo`, and — since `readArguments` is the first thing it does — the
- * point where an invalid call is refused.
- *
- * Returns a string on every valid call rather than ever returning `undefined`:
- * `undefined` means "this particular call has nothing to confirm", and there
- * is no such call here. Every accepted declaration boots or attaches to
- * something and may write durable R4 facts.
- *
- * Reads the *parsed* services rather than the raw object, so the sentence a
- * developer confirms is built from the same values the run will use — which
- * is also what makes "spawn" and "attach" here mean exactly what
- * `readServices` decided they mean, rather than a second, looser guess at the
- * same distinction.
- */
+/** §7's `willDo` — and, since readArguments runs first, where an invalid call is refused.
+ *  Always returns a string, never undefined: unlike `questions`, no call here has nothing
+ *  to confirm. Reads the *parsed* services so the confirmation sentence matches the run exactly. */
 function describeAction(args, ctx) {
     const { declared } = readArguments(args, ctx.session.repoPath);
     const spawned = declared.filter((service) => !service.attached).map((service) => service.name);