@henols/vice-mcp 0.2.2 → 0.2.4

package/resources/vice-launcher.sh

@@ -15,7 +15,10 @@
 # --check-container is now forwarded through to the Node entry point, which
 # answers it, preserving the exact same exit-code contract this launcher
 # always had: 2 when the guard refuses, 3 for the report path, 0 for
-# --print-paths.
+# --print-paths, and (new below) 4 when no interpreter this launcher is
+# willing to exec into could be resolved -- distinct from 2/3 so a triage
+# reader can tell "no usable interpreter" from "container guard refused"
+# at a glance.
 #
 # Copies vice-broker.sh's own opening shape: SELF_PATH/SELF_DIR resolution,
 # resolve_repo_root(). Plan 11 INLINES resolve_repo_root() here (it used to
@@ -131,12 +134,105 @@ REPO_ROOT="$(resolve_repo_root "$SELF_DIR")"
 # deployed tools/ copy that may be stale or hand-edited.
 BROKER_ARTIFACT="$SELF_DIR/vice-broker.mjs"
 
+# ---------------------------------------------------------------- interpreter resolution
+#
+# WHY THIS EXISTS: this launcher used to `exec node ...`, trusting whatever
+# `node` a shell's PATH resolved first. On a development host with several
+# Node majors installed side by side that is an accident waiting to happen,
+# and a service environment (a systemd unit's own PATH, carrying no
+# interactive-shell version-manager entry) resolves a DIFFERENT one than an
+# interactive shell -- the same script started two different ways running
+# two different interpreters, with no record of which. Nothing spawns this
+# script (the broker never spawns itself; the only thing that ever prints
+# this path is a message telling a HUMAN to run it), so there is no parent
+# process whose own interpreter this launcher could inherit or receive as an
+# argument -- the ladder below, plus a refusal, is the whole of it.
+#
+# NODE_FLOOR_MAJOR mirrors src/mcp/vice/package.json's `engines.node` --
+# pinned to that single number by a test (host-scripts.test.ts) precisely so
+# this floor cannot silently drift into a second, disagreeing number, which
+# is the same failure class as the bare-interpreter exec this section
+# replaces.
+NODE_FLOOR_MAJOR=24
+
+# probe_node_version <candidate-path>
+#
+# On success, sets NODE_RESOLVED_VERSION (the raw "vX.Y.Z" string) and
+# NODE_RESOLVED_MAJOR (just the leading number) and returns 0. On any
+# failure -- not executable, crashes, or prints something this launcher
+# cannot parse as a version -- returns 1 and sets neither. Called only from
+# inside an `if`, so a failure here becomes a named refusal downstream
+# rather than aborting the whole script under `set -e`.
+probe_node_version() {
+  local candidate="$1" raw major
+  if ! raw="$("$candidate" --version 2>/dev/null)"; then
+    return 1
+  fi
+  case "$raw" in
+    v[0-9]*) : ;;
+    *) return 1 ;;
+  esac
+  major="${raw#v}"
+  major="${major%%.*}"
+  case "$major" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  NODE_RESOLVED_VERSION="$raw"
+  NODE_RESOLVED_MAJOR="$major"
+  return 0
+}
+
+# Resolution ladder -- exactly two rungs, then a refusal. There is no third
+# rung to invent: see the WHY note above for why the broker's own
+# interpreter can never be threaded in as a candidate.
+#
+#   1. VICE_BROKER_NODE, an absolute-path override, accepted only when it
+#      names an executable file -- this is the rung that fixes a service
+#      unit whose PATH carries no usable node at all: point it at one
+#      directly instead of depending on PATH.
+#   2. `node` as found on PATH.
+NODE_BIN=""
+NODE_VERSION=""
+NODE_MAJOR=""
+NODE_RESOLUTION_ERROR=""
+
+if [ -n "${VICE_BROKER_NODE:-}" ]; then
+  if [ -f "${VICE_BROKER_NODE}" ] && [ -x "${VICE_BROKER_NODE}" ]; then
+    if probe_node_version "$VICE_BROKER_NODE"; then
+      NODE_BIN="$VICE_BROKER_NODE"
+      NODE_VERSION="$NODE_RESOLVED_VERSION"
+      NODE_MAJOR="$NODE_RESOLVED_MAJOR"
+    else
+      NODE_RESOLUTION_ERROR="VICE_BROKER_NODE is set to '$VICE_BROKER_NODE', but running it with --version failed or produced output this launcher could not parse. Set VICE_BROKER_NODE to an absolute path to a working node executable, or unset it to fall back to node on PATH."
+    fi
+  else
+    NODE_RESOLUTION_ERROR="VICE_BROKER_NODE is set to '$VICE_BROKER_NODE', which does not resolve to an executable file. Set VICE_BROKER_NODE to an absolute path to an executable node interpreter, or unset it to fall back to node on PATH."
+  fi
+else
+  NODE_CANDIDATE="$(command -v node 2>/dev/null || true)"
+  if [ -n "$NODE_CANDIDATE" ]; then
+    if probe_node_version "$NODE_CANDIDATE"; then
+      NODE_BIN="$NODE_CANDIDATE"
+      NODE_VERSION="$NODE_RESOLVED_VERSION"
+      NODE_MAJOR="$NODE_RESOLVED_MAJOR"
+    else
+      NODE_RESOLUTION_ERROR="Resolved 'node' on PATH at '$NODE_CANDIDATE', but running it with --version failed or produced output this launcher could not parse. Install a working Node >= v${NODE_FLOOR_MAJOR} and put it on PATH, or set VICE_BROKER_NODE to an absolute path to one."
+    fi
+  else
+    NODE_RESOLUTION_ERROR="No 'node' executable was found on PATH and VICE_BROKER_NODE is not set. Install Node >= v${NODE_FLOOR_MAJOR} and put it on PATH, or set VICE_BROKER_NODE to an absolute path to one."
+  fi
+fi
+
 # ---------------------------------------------------------------- --print-paths
 #
-# Prints already-resolved variables only -- writes no state, spawns nothing,
-# so (like vice-broker.sh's own --print-paths) it needs no guard enforcement
-# to report what this launcher would use. Checked BEFORE --check-container is
-# forwarded, since --print-paths needs no guard verdict at all.
+# Prints already-resolved variables only -- writes no state and spawns
+# nothing beyond the version probe above, so (like vice-broker.sh's own
+# --print-paths) it needs no guard enforcement to report what this launcher
+# would use. Checked BEFORE --check-container is forwarded, since
+# --print-paths needs no guard verdict at all, and BEFORE the floor is
+# enforced below: this diagnostic reports what it found, or reports it
+# found nothing, but never refuses -- a diagnostic that dies exactly when
+# the thing it diagnoses is broken is worthless.
 PRINT_PATHS=0
 for arg in "$@"; do
   case "$arg" in
@@ -150,9 +246,29 @@ if [ "$PRINT_PATHS" -eq 1 ]; then
   echo "repo_root=$REPO_ROOT"
   echo "self_dir=$SELF_DIR"
   echo "broker_artifact=$BROKER_ARTIFACT"
+  echo "node_bin=$NODE_BIN"
+  echo "node_version=$NODE_VERSION"
   exit 0
 fi
 
+# ---------------------------------------------------------------- interpreter gate
+#
+# Refuses BEFORE exec, by name, with a remedy -- a below-floor or
+# unresolvable interpreter must never reach the broker artifact, because
+# once it does, whatever fails next presents as a wedge with no obvious
+# cause. This project detects and refuses by name; it never installs
+# anything and never shells out to a package manager.
+if [ -z "$NODE_BIN" ]; then
+  printf 'vice-launcher: refusing to start -- %s\n' "$NODE_RESOLUTION_ERROR" >&2
+  exit 4
+fi
+
+if [ "$NODE_MAJOR" -lt "$NODE_FLOOR_MAJOR" ]; then
+  printf 'vice-launcher: refusing to start -- resolved node interpreter %s reports %s, which is below the required floor v%s.x. Install a Node >= v%s and put it on PATH, or set VICE_BROKER_NODE to an absolute path to one that satisfies the floor.\n' \
+    "$NODE_BIN" "$NODE_VERSION" "$NODE_FLOOR_MAJOR" "$NODE_FLOOR_MAJOR" >&2
+  exit 4
+fi
+
 # ---------------------------------------------------------------- exec
 #
 # The guard now runs INSIDE the Node entry point, at its own process
@@ -161,9 +277,11 @@ fi
 # enforcement path (exit 2, refusal) are the broker's own job now. This
 # launcher forwards every argument, including --repo-root, unchanged, and
 # no longer inspects --check-container itself; the exit-code contract this
-# launcher always exposed (2/3/0) is preserved because the guard functions
-# ported into container-guard.mts return the SAME codes
+# launcher always exposed (2/3/0, now also 4) is preserved because the guard
+# functions ported into container-guard.mts return the SAME codes
 # container_guard_enforce()/container_guard_report() always did. Signal
 # delivery still passes straight through to the broker process with no bash
-# trap in between.
-exec node "$BROKER_ARTIFACT" --repo-root "$REPO_ROOT" "$@"
+# trap in between -- exec replaces the process image with the RESOLVED
+# interpreter, never a bare command name, so the interpreter this launcher
+# actually gated is the one that actually runs.
+exec "$NODE_BIN" "$BROKER_ARTIFACT" --repo-root "$REPO_ROOT" "$@"

package/stock-address.ts

@@ -32,7 +32,7 @@
 //     installs one object implementing both; a second holder or a
 //     re-derived address->name map in a family module would force it to
 //     install itself twice.
-import { ViceError, type ViceErrorOptions } from "./vice.ts";
+import { ViceError, type ViceErrorOptions } from "./vice-errors.ts";
 
 export interface SymbolResolver {
   resolve(name: string): number | undefined;

package/stock-condition.ts

@@ -46,7 +46,7 @@
 // session, never touches a socket, never imports anything from the
 // session/session-handler layer.
 
-import { ViceError } from "./vice.ts";
+import { ViceError } from "./vice-errors.ts";
 
 // ---------------------------------------------------------------------------
 // Errors

package/stock-connect.ts

@@ -42,7 +42,7 @@ import {
   StockRequestTimeoutError,
 } from "./stock-protocol.ts";
 import { readCapabilityRecord, writeCapabilityRecord, type CapabilityDeps } from "./backend-detect.mts";
-import { MachineRestartedError, ViceError, readEpoch, type EpochResult } from "./vice.ts";
+import { MachineRestartedError, ViceError, readEpoch, type EpochResult } from "./vice-errors.ts";
 import {
   MonitorOwnershipError,
   type ClaimMonitorOptions,
@@ -402,12 +402,14 @@ async function safeResume(client: ViceMonitorClient): Promise<void> {
  * leave a frozen C64 behind either.
  */
 export async function stockConnect({ host, port, targetId, brokerControl, deps = {} }: StockConnectOptions): Promise<StockConnectSession> {
-  const claimOutcome = await brokerControl.claimMonitor({ targetId });
+  // Plan 41-03 (D-14): explicit, not relying on claimMonitor()'s own default
+  // -- the binary path names its own channel at the call site.
+  const claimOutcome = await brokerControl.claimMonitor({ targetId, channel: "binary" });
   if (!claimOutcome.ok) {
     if (claimOutcome.reason === "monitor_owned") {
       throw new MonitorOwnershipError(
         `stockConnect: monitor for target ${targetId} on port ${port} is already claimed by grant ${claimOutcome.holder.grantId}`,
-        { holderGrantId: claimOutcome.holder.grantId, holderClaimedAt: claimOutcome.holder.claimedAt, port },
+        { holderGrantId: claimOutcome.holder.grantId, holderClaimedAt: claimOutcome.holder.claimedAt, port, channel: claimOutcome.holder.channel },
       );
     }
     // "timeout" (the broker did not answer) is kept strictly distinct from
@@ -474,7 +476,9 @@ export async function stockConnect({ host, port, targetId, brokerControl, deps =
     // reason. Both outcomes are now reported on stderr and neither can
     // displace `err`.
     try {
-      const released = await brokerControl.releaseMonitor({ targetId });
+      // Plan 41-03 (D-14): explicit "binary" -- never releases the "text"
+      // claim as a side effect of a failed binary handshake.
+      const released = await brokerControl.releaseMonitor({ targetId, channel: "binary" });
       if (!released.ok) {
         console.error(
           `stockConnect: monitor release for target ${targetId} after a failed handshake was refused (${released.reason}) -- the instance may still be claimed`,
@@ -493,7 +497,7 @@ export async function stockConnect({ host, port, targetId, brokerControl, deps =
  * stockConnect()'s own failure-path release above. */
 export async function stockDisconnect(session: StockConnectSession): Promise<void> {
   await safeDisconnect(session.client);
-  await session.brokerControl.releaseMonitor({ targetId: session.targetId });
+  await session.brokerControl.releaseMonitor({ targetId: session.targetId, channel: "binary" });
 }
 
 // ---------------------------------------------------------------------------

package/stock-derived.ts

@@ -18,48 +18,32 @@
 // hazard. There, NOT translating an emulator-side path is the bug -- four
 // tools carry a filename stock VICE opens on the HOST, and stock-paths.ts's
 // whole job is making sure that translation happens. HERE, translating a
-// CLIENT-SIDE-DERIVED path is the bug: `forwardToVice()` calls
-// `rewriteArguments(args, name)` itself, before it ever delegates to
-// `call()` -- so a derived tool sitting behind `call()` would receive
-// HOST-translated paths and act on them INSIDE THE CONTAINER (ROADMAP Phase 4
-// Notes, CLAUDE.md). The derived-tool seam this file anchors exists so a
-// derived tool's handler is reached BEFORE `forwardToVice()` runs
-// `rewriteArguments()` at all.
+// CLIENT-SIDE-DERIVED path is the bug: a derived tool answers from data this
+// proxy already holds, so handing its arguments through a HOST path
+// translator meant for a forwarded call would act on a translated path
+// INSIDE THE CONTAINER instead of the untranslated one the derived handler
+// actually needs.
 //
-// SECOND CONSUMER: `gatherWedgeEvidence()` in vice-proxy.ts calls
-// `rewriteArguments()` itself, for `vice_display_screenshot`. On the stock
-// backend, PERFORMING that translation becomes the bug -- its own comment
-// inverts. Phase 5 criterion 5 owns that fix; it is deliberately NOT
-// repointed here.
-//
-// CITATION STYLE, deliberate (07-REVIEW.md WR-12): the two call sites above
-// are named by SYMBOL (`forwardToVice()`'s own `rewriteArguments(args, name)`
-// call; `gatherWedgeEvidence()`'s own call), never by line number. This header
-// used to cite `vice-proxy.ts:2773`, `:1343` and `:1367`; by the time WR-12 was
-// filed the real lines were 2889, 1344 and 1368 -- 07-16 edited vice-proxy.ts
-// without re-verifying them, and this header is the in-tree statement of
-// CLAUDE.md's derived-tool constraint, so its citations are load-bearing. Line
-// numbers in this file drift every phase; grep for the symbol instead.
-//
-// WHY THE HAZARD IS UNREACHABLE ON STOCK TODAY -- restated in terms of what
-// actually enforces it (WR-12 again; the previous reason had gone stale):
-// `buildBackendAwareTool()` routes EVERY stock tool call to
-// `dispatchStock()`, so `forwardToVice()`, `handleRecycle()` and
-// `gatherWedgeEvidence()` are reachable only on the fork arm. That is a
-// structural property of the registration, not of any tool's name. The reason
-// this header used to give -- "handleRecycle() is backend-aware and refused by
-// name after CR-07, and vice_display_screenshot does not exist on stock until
-// Phase 5" -- is now WRONG on its first clause: Phase 7 implemented
-// `vice_recycle` on stock (`handleRecycleStock`) and registered it in
-// STOCK_DERIVED_TOOLS below. The conclusion held; the stated reason did not,
-// which is worse than no reason for a constraint a future reader will
-// re-derive.
+// WHY THE HAZARD IS UNREACHABLE ON STOCK TODAY: it no longer has anywhere to
+// come FROM. The fork-only generic forwarding function and its own
+// per-call argument path-rewriter, and the fork-only wedge-evidence
+// gatherer that also ran that rewriter for `vice_display_screenshot`, are
+// both deleted outright -- there is no remaining call site anywhere in this
+// package that translates a host path before dispatch. Every stock tool
+// call, derived or direct, reaches `dispatchStock()` in stock-dispatch.ts
+// through exactly one registration seam in vice-proxy.ts, with no
+// per-backend branch left to route around it. The hazard this file was
+// built to close is now closed by construction, not merely by a runtime
+// backend check: there is no path-translating function left for a derived
+// tool's runner to be reached behind.
 //
 // WHAT NOT TO DO:
 //   - Never `import` hostpath.ts from this file, or from any module listed
 //     in STOCK_DERIVED_TOOLS' implementations -- hostpath-consumers.test.ts
 //     fails the build if you do.
-//   - Never `import` vice-proxy.ts, and never call rewriteArguments().
+//   - Never `import` vice-proxy.ts, and never re-introduce a per-call
+//     argument path-translator that a derived tool's runner could be
+//     reached behind.
 //   - Never add a client-side-derived tool to stock-paths.ts's
 //     STOCK_EMULATOR_SIDE_PATH_TOOLS -- that file's own header already warns
 //     against exactly this.
@@ -76,7 +60,7 @@
 //     withDerivedTool() refuses on this set, and a declared-but-unshipped
 //     module fails at module load in the published tarball rather than at
 //     dispatch.
-import { ViceError, type ViceErrorOptions } from "./vice.ts";
+import { ViceError, type ViceErrorOptions } from "./vice-errors.ts";
 import type { StockToolResult } from "./stock-handler.ts";
 import type { StockDispatchDeps } from "./stock-dispatch.ts";
 
@@ -114,6 +98,14 @@ export const STOCK_DERIVED_TOOLS: ReadonlySet<string> = new Set([
   "vice_run_until", // Phase 7, TIME-02
   "vice_diagnose", // Phase 7, TIME-04
   "vice_recycle", // Phase 7, TIME-04
+  "vice_device_console", // Plan 41-06, CHAN-03 -- text-channel remedy tool, needsSession:false (text-tools.ts)
+  "vice_warp_set", // Plan 41-06, CHAN-03 -- text-channel remedy tool, needsSession:false (text-tools.ts)
+  "vice_memmap_show", // Plan 42-01, PARSE-01 -- text-channel access-map tool, needsSession:false (text-tools.ts)
+  "vice_memmap_zap", // Plan 43-03, EVID-05 -- text-channel access-map bracket-reset tool, needsSession:false (text-tools.ts)
+  "vice_cpu_history", // Plan 42-07, PARSE-02 -- text-channel CPU-history tool, needsSession:false (text-tools.ts)
+  "vice_profile_flat", // Plan 42-07, PARSE-02 -- text-channel flat-profile tool, needsSession:false (text-tools.ts)
+  "vice_backtrace", // Plan 42-07, PARSE-02/D-42-4 -- text-channel backtrace tool, shares the fork's own name, needsSession:false (text-tools.ts)
+  "vice_io_registers", // Plan 42-07, PARSE-02 -- text-channel register-decode tool, needsSession:false (text-tools.ts)
 ]);
 
 /**

package/stock-diagnose.ts

@@ -48,8 +48,9 @@ import { ensureStockSession, type StockDispatchDeps, type EnsureStockSessionOutc
 import type { DerivedPureHandler } from "./stock-derived.ts";
 import type { StockConnectSession } from "./stock-connect.ts";
 import { runStateFor, jamObservedFor } from "./stock-runstate.ts";
-import { MachineRestartedError, readEpoch, type EpochResult } from "./vice.ts";
+import { MachineRestartedError, readEpoch, type EpochResult } from "./vice-errors.ts";
 import { MonitorOwnershipError } from "./vice-broker-client.ts";
+import { tryAcquireChannelLock, currentChannelLockHolder, type ChannelLockHandle, type ChannelLockHolder, type MonitorChannel } from "./channel-lock.ts";
 
 /** True iff `value` is a well-formed, generic JSON object -- not null, not
  * an array. Matches this module tree's own isPlainObject() convention,
@@ -649,6 +650,29 @@ function renderStockWedgedReport(bracket1: StockLivenessBracketResult, bracket2:
   );
 }
 
+/** D-10/D-11: rendered when step 4's guard finds a FOREIGN hold already live
+ * -- `tryAcquireChannelLock()` returned `null`, so no bracket was ever run.
+ * `holder` is a snapshot taken at the moment the guard observed it; the
+ * authoritative `evidence.channelContention` is derived independently and
+ * slightly later, inside diagnoseVerdictResult() -- a few milliseconds'
+ * difference in `heldMs` between the two is expected and honest, not a bug.
+ * Deliberately self-contained (repeats the channel/operation/duration the
+ * universal channelContentionNote() will also append), so this report reads
+ * completely even if the note above it is somehow stripped. Must never
+ * contain wedge, wedged, hang, hung, frozen, stuck or unresponsive. */
+function renderStockContendedReport(holder: ChannelLockHolder): string {
+  const heldMs = Math.max(0, Date.now() - holder.heldSince);
+  const grantId = holder.grantId ?? "unknown";
+  return (
+    "vice_diagnose verdict: live\n\n" +
+    `The ${holder.channel} channel currently holds this instance's halt authority (operation "${holder.operation}", ` +
+    `grant ${grantId}, held for ${heldMs}ms). No liveness bracket was run: this call was never granted halt ` +
+    "authority, so the machine was never resumed and liveness was not measured here -- the contention evidence is " +
+    "what explains the zero bracket count, not a bracket that read zero. The instance is healthy and answering: " +
+    "this is never a reason to recycle. Wait for the other channel's operation to finish, or find its holder."
+  );
+}
+
 /** The `detail` half of the `liveness_unmeasurable` refusal (07-REVIEW.md
  * WR-02). Deliberately carries NO "vice_diagnose:" prefix of its own --
  * diagnoseUnavailableResult() owns the documented, machine-parseable prefix,
@@ -751,24 +775,118 @@ const JAM_OBSERVED_NOTE =
   "a wedge. Recover with vice_machine_reset -- do NOT vice_recycle, which destroys an instance a reset " +
   "would have fixed.";
 
+// ---------------------------------------------------------------------------
+// D-09/D-10/D-11 (plan 41-04, CHAN-05): channelContention -- always-present
+// cross-cutting evidence on the jamObserved model, plus the guard (in
+// handleDiagnoseStock()'s step 4, below) that makes `wedged` structurally
+// unreachable while contended.
+//
+// DELIBERATE ASYMMETRY WITH jamObserved, RECORDED HERE SO A LATER READER DOES
+// NOT "FIX" IT: jamObserved guards only in vice-wedge-triage/SKILL.md's
+// prose and still lets `wedged` return -- the caller has to read the
+// evidence and choose not to recycle. channelContention guards in CODE, in
+// the handler itself, and makes `wedged` structurally unreachable while a
+// foreign hold is live. The reason is the cost of being wrong: a contended
+// instance is not merely misdiagnosed, it would be DESTROYED by the
+// documented `wedged` remedy (T-41-15). Do not collapse this asymmetry by
+// demoting the code guard to a prose-only warning to match jamObserved's
+// shape -- they are deliberately different because what they are protecting
+// against is not the same severity.
+// ---------------------------------------------------------------------------
+
+/** Always-present evidence on every `vice_diagnose` verdict (D-09), naming
+ * whether the OTHER monitor channel currently holds this instance's halt
+ * authority. `channel`/`operation`/`grantId`/`heldMs` are `null` exactly when
+ * `held` is `false` -- never omitted, so "not held" and "held for under a
+ * millisecond" stay distinguishable (`heldMs: null` vs `heldMs: 0`). */
+export interface StockChannelContention {
+  held: boolean;
+  channel: MonitorChannel | null;
+  operation: string | null;
+  grantId: string | null;
+  heldMs: number | null;
+}
+
+/**
+ * Derives `StockChannelContention` from channel-lock.ts's holder record.
+ *
+ * `self` is the handle THIS diagnose call itself currently holds, if any --
+ * passed only from inside handleDiagnoseStock()'s own step-4 guard, while it
+ * holds the lock across its own liveness bracket(s). When `self` is
+ * non-null, this call IS the current holder by construction (only one
+ * holder can exist at a time), so reporting that as "contention" would be
+ * dishonest -- a diagnose call's own halt authority over its own bracket is
+ * not a FOREIGN hold. Every other caller (the four verdicts reached before
+ * the guard ever runs) passes no `self`, and a genuine foreign hold observed
+ * at that moment is reported exactly as measured.
+ *
+ * `grantId` reads the literal `unknown` when the holder recorded none --
+ * never fabricated, matching claimMonitor()'s own posture. `heldMs` is
+ * `Math.max(0, Math.trunc(nowMs - holder.heldSince))`, a non-negative whole
+ * millisecond integer.
+ */
+export function channelContentionFor(nowMs: number, self: ChannelLockHandle | null): StockChannelContention {
+  if (self !== null) {
+    return { held: false, channel: null, operation: null, grantId: null, heldMs: null };
+  }
+  const holder = currentChannelLockHolder();
+  if (holder === null) {
+    return { held: false, channel: null, operation: null, grantId: null, heldMs: null };
+  }
+  return {
+    held: true,
+    channel: holder.channel,
+    operation: holder.operation,
+    grantId: holder.grantId ?? "unknown",
+    heldMs: Math.max(0, Math.trunc(nowMs - holder.heldSince)),
+  };
+}
+
+/** Appended to a verdict's report in the same register as JAM_OBSERVED_NOTE
+ * above, whenever `channelContention.held` is true -- deliberately UNIVERSAL:
+ * contention is evidence cutting across all five verdicts (D-09), not
+ * exclusive to the live-with-bracketsRun:0 path the guard itself reaches. A
+ * concurrent foreign hold can just as easily be observed while THIS call is
+ * answering restarted/checkpoint_trap/monitor_held_elsewhere. Must never
+ * contain wedge, wedged, hang, hung, frozen, stuck or unresponsive -- the
+ * same register channelLockRefusalMessage() (channel-lock.ts) already
+ * establishes, and the instance is healthy and answering regardless of which
+ * verdict carries this note. */
+function channelContentionNote(contention: StockChannelContention): string {
+  return (
+    "\n\nCHANNEL CONTENTION: the " +
+    `${contention.channel} channel currently holds this instance's halt authority (operation ` +
+    `"${contention.operation}", grant ${contention.grantId}, held for ${contention.heldMs}ms). The instance is ` +
+    "healthy and answering -- this is never a reason to recycle."
+  );
+}
+
 /** WR-04: `jamObserved` is derived HERE, from the same seam as
  * `machinePaused`, and stamped into EVERY verdict's evidence -- not added
  * per-call-site, for the same reason WR-03 removed the hand-passed
  * `machinePaused`. It is evidence on the existing five verdicts, never a
  * sixth verdict (D-03). Always present (never omitted when false), so an
- * absent field can never be read as "no jam". */
+ * absent field can never be read as "no jam". D-09: `channelContention` joins
+ * it here, on the identical always-present, derived-once, spread-unconditionally
+ * shape -- see `self`'s doc comment on channelContentionFor() above for why
+ * this function must be told which handle (if any) THIS call itself holds. */
 function diagnoseVerdictResult(
   session: StockConnectSession | null,
   verdict: StockDiagnoseVerdict,
   evidence: Record<string, unknown>,
   report: string,
+  self: ChannelLockHandle | null = null,
 ): StockToolResult {
   const { machinePaused, machinePausedSource } = deriveMachinePaused(session);
   const jamObserved = session === null ? false : jamObservedFor(session.client);
+  const channelContention = channelContentionFor(Date.now(), self);
+  let finalReport = report;
+  if (jamObserved) finalReport += JAM_OBSERVED_NOTE;
+  if (channelContention.held) finalReport += channelContentionNote(channelContention);
   const payload: Record<string, unknown> = {
     verdict,
-    evidence: { ...evidence, jamObserved },
-    report: jamObserved ? report + JAM_OBSERVED_NOTE : report,
+    evidence: { ...evidence, jamObserved, channelContention },
+    report: finalReport,
     machinePaused,
     machinePausedSource,
   };
@@ -936,47 +1054,93 @@ export async function handleDiagnoseStock(_args: Record<string, unknown>, deps:
     }
 
     // Step 4: the liveness bracket -- the only step that resumes.
-    let bracket1: StockLivenessBracketResult;
-    try {
-      bracket1 = await runStockLivenessBracket(session);
-    } catch (err) {
-      return diagnoseUnavailableResult("evidence_gathering_failed", `the liveness bracket failed (${describeStockError(err)}).`);
+    //
+    // D-10 guard, placed immediately BEFORE the first bracket can run --
+    // that is, before the only step that resumes the machine, and therefore
+    // before any path that can reach the `wedged` return below.
+    // tryAcquireChannelLock() is the SYNCHRONOUS, non-blocking entry point,
+    // chosen deliberately over acquireChannelLock(): a diagnostic that
+    // queued behind a foreign hold would block behind the exact holder it
+    // exists to report, and one that merely peeked at the holder record
+    // without taking the lock could still have a foreign hold begin during
+    // its own bracket. On `null` a foreign hold is live RIGHT NOW --
+    // short-circuit to `live` with contention evidence and `bracketsRun: 0`
+    // (the honest count: the machine was never resumed, so liveness was not
+    // measured), with NO bracket run at all -- this is D-11's verdict choice
+    // (the instance is healthy and responsive, not wedged). On a handle,
+    // hold it across BOTH brackets and release in a `finally` covering every
+    // return from here on, so a thrown bracket still releases. This is what
+    // makes `wedged` structurally unreachable while contended: the only
+    // route to it is through a bracket, and a bracket only runs when this
+    // lock was actually taken by THIS call.
+    const channelHandle = tryAcquireChannelLock({ channel: "binary", operation: "vice_diagnose" });
+    if (channelHandle === null) {
+      const holder = currentChannelLockHolder();
+      // Invariant: tryAcquireChannelLock() returning null means SOME holder
+      // exists (that is precisely why it refused) -- currentChannelLockHolder()
+      // reading null here would be a lock-module invariant violation, not a
+      // reachable case this handler needs to degrade gracefully for.
+      if (holder === null) {
+        return diagnoseUnavailableResult(
+          "unknown",
+          "channel-lock: tryAcquireChannelLock() refused but currentChannelLockHolder() reported no holder -- internal invariant violation.",
+        );
+      }
+      return diagnoseVerdictResult(session, "live", { bracketsRun: 0 }, renderStockContendedReport(holder));
     }
+    try {
+      let bracket1: StockLivenessBracketResult;
+      try {
+        bracket1 = await runStockLivenessBracket(session);
+      } catch (err) {
+        return diagnoseUnavailableResult("evidence_gathering_failed", `the liveness bracket failed (${describeStockError(err)}).`);
+      }
 
-    if (bracket1.advanced === null) {
-      return diagnoseUnavailableResult("liveness_unmeasurable", inconclusiveBracketText(bracket1));
-    }
-    if (bracket1.advanced) {
-      return diagnoseVerdictResult(session, "live", { bracketsRun: 1, bracket: serializeBracket(bracket1) }, renderStockLiveReport(bracket1));
-    }
+      if (bracket1.advanced === null) {
+        return diagnoseUnavailableResult("liveness_unmeasurable", inconclusiveBracketText(bracket1));
+      }
+      if (bracket1.advanced) {
+        return diagnoseVerdictResult(
+          session,
+          "live",
+          { bracketsRun: 1, bracket: serializeBracket(bracket1) },
+          renderStockLiveReport(bracket1),
+          channelHandle,
+        );
+      }
 
-    // Run a second bracket only when the first shows no advance -- mirroring
-    // the fork's own short-circuit.
-    let bracket2: StockLivenessBracketResult;
-    try {
-      bracket2 = await runStockLivenessBracket(session);
-    } catch (err) {
-      return diagnoseUnavailableResult("evidence_gathering_failed", `the second liveness bracket failed (${describeStockError(err)}).`);
-    }
+      // Run a second bracket only when the first shows no advance -- mirroring
+      // the fork's own short-circuit.
+      let bracket2: StockLivenessBracketResult;
+      try {
+        bracket2 = await runStockLivenessBracket(session);
+      } catch (err) {
+        return diagnoseUnavailableResult("evidence_gathering_failed", `the second liveness bracket failed (${describeStockError(err)}).`);
+      }
+
+      if (bracket2.advanced === null) {
+        return diagnoseUnavailableResult("liveness_unmeasurable", inconclusiveBracketText(bracket2));
+      }
+      if (bracket2.advanced) {
+        return diagnoseVerdictResult(
+          session,
+          "live",
+          { bracketsRun: 2, bracket1: serializeBracket(bracket1), bracket2: serializeBracket(bracket2) },
+          renderStockLiveReport(bracket2),
+          channelHandle,
+        );
+      }
 
-    if (bracket2.advanced === null) {
-      return diagnoseUnavailableResult("liveness_unmeasurable", inconclusiveBracketText(bracket2));
-    }
-    if (bracket2.advanced) {
       return diagnoseVerdictResult(
         session,
-        "live",
+        "wedged",
         { bracketsRun: 2, bracket1: serializeBracket(bracket1), bracket2: serializeBracket(bracket2) },
-        renderStockLiveReport(bracket2),
+        renderStockWedgedReport(bracket1, bracket2),
+        channelHandle,
       );
+    } finally {
+      channelHandle.release();
     }
-
-    return diagnoseVerdictResult(
-      session,
-      "wedged",
-      { bracketsRun: 2, bracket1: serializeBracket(bracket1), bracket2: serializeBracket(bracket2) },
-      renderStockWedgedReport(bracket1, bracket2),
-    );
   } catch (err) {
     // WR-02: the outer catch-all goes through the classifier too, so there is
     // no isError answer this handler can produce that lacks the documented