Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix: name probe 421s, match empty owner refs by dir, give tunnels their own advice

reviewba1d873111f3
diff --git a/CLAUDE.md b/CLAUDE.md
index 56252a2c7..2c3cf6195 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2510,8 +2510,11 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
`node-tokens` — never from the global search `nt_read_node_token` walks (that search exists to
PRESENT a capability, #384; as a reference it let a Server Edition that opened the same
project.json supply the "owner's" token whenever the desktop's token write had failed). Once
- that dir EXISTS, a candidate must hold the same value in its own dir, "both hold nothing"
- included; only a session with no such dir at all keeps legacy discovery. What a match shows is
+ that dir EXISTS, a candidate must hold the same value in its own dir — and when the reference
+ is EMPTY (the write failed), a value proves nothing (a Server Edition that never heard of the
+ node holds nothing too, and `"" = ""` relayed its permanent refusal, measured in review), so the
+ candidate's token dir must be the same REAL directory (`pwd -P`) instead. Only a session with no
+ such dir at all keeps legacy discovery. What a match shows is
that the candidate reads the same token file for this node — on an SSH host that file is shared
per unix ACCOUNT (`remote-hooks.ts`, KNOWN LIMITATION), so two desktops driving one account are
indistinguishable here, and the receiving server still authorizes every request. Actual
@@ -2525,7 +2528,11 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
foreign Server Edition stopped absorbing the walk, a call posted straight into such a socket
hung. The bound is on the probe only: the primary is never probed and every real POST stays
unbounded, because a confirm-gated verb waits for a human (see "two canvases cannot raise two
- dialogs" below).
+ dialogs" below). The probe writes into `$nt_out` like the POST would, so a 421 at the probe
+ still prints its body (into /dev/null it left the control shim exiting 1 with an EMPTY stderr),
+ and the control shim names a final 421 with `CONTROL_UNREACHABLE_MSG` as the context shim does.
+ Consequence to know: while sshd still holds the session's OWN tunnel socket, the primary POST
+ itself still hangs — unbounded by design, for the dialogs.
**Measured on an SSH host (2026-09-28/29):** the desktop slept, the session's tunnel socket
stayed on disk with no listener, and the walk reached an unrelated Server Edition whose
`control-unsupported-on-this-edition … permanent … do not retry` (and, for context reads,
@@ -2533,7 +2540,10 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
back minutes later. When a foreign candidate was skipped and no owner answered, the shims now
print `FOREIGN_ENDPOINT_HINT` — the owning connection is unreachable, the state is temporary,
the usual cause for an SSH project is the tunnel — INSTEAD OF `STALE_ENDPOINT_HINT`, so a failure
- carries one retry advice, not two. All four agent-facing bodies quote its lead via
+ carries one retry advice, not two. With nothing foreign skipped, a primary that is an SSH tunnel
+ file (`~/.nodeterm/hook-endpoint*.env`, the only files the desktop writes there) gets
+ `TUNNEL_DOWN_HINT` (reconnect) instead of the stale-endpoint advice (app restart); both hints
+ open with the lead the bodies quote. All four agent-facing bodies quote its lead via
`ownerUnreachableGuidanceLines`, because their other refusal lines rightly say "do not retry".
`src/server/control-owner-tunnel-down.test.ts` rebuilds that host under real `/bin/sh` with the
real Server Edition handlers as the foreign endpoint; `src/core/owned-endpoint-walk.test.ts`
@@ -3257,7 +3267,8 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
gives that curl a timeout, this paragraph stops being true: a confirm-gated verb would then fail
over mid-wait and a second instance WOULD open a second dialog for the same logical request.
(The walk's liveness probe IS bounded, and does not break this: it runs only against a FALLBACK
- candidate, only after the primary's transport already failed, and before any POST to it.)
+ candidate, only after the primary failed — a dead transport, or a 421 wrong-owner answer, which
+ the server gives before dispatch, so no dialog exists — and before any POST to that candidate.)
**Grouping verbs** (`group` / `ungroup` / `move` / `arrange` / `align`): `group` wraps **sibling**
objects — nodes or frames — into a new frame in their shared container (a mixed-container set, or
an ancestor plus its descendant, is refused with that reason); `ungroup --group <id>` dissolves a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 41b92226f..247ad5822 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1056,7 +1056,8 @@ session was born on. A foreign server being reachable is not evidence that it ow
and a matching token is not proof either (on an SSH host the token dir is shared per unix
account); it is a routing rule, and the server still authorizes. Take the reference token from the
primary endpoint's own dir, never from a global directory, and match each candidate's own dir
-against it. Probe a fallback candidate (bounded) before posting to it, but never put a timeout on
+against it — by value, or, when the reference is empty, by the directory's real path (an empty
+value matches every stranger). Probe a fallback candidate (bounded) before posting to it, but never put a timeout on
the real POST: a confirm-gated verb waits for a human. Keep real owning-endpoint refusals final and
legacy hook delivery unchanged. When no owner answers, say so once, as a temporary state
(`FOREIGN_ENDPOINT_HINT`); never let another instance's "permanent, do not retry" stand in for a
diff --git a/src/core/agents/hook-endpoint-failover-sh.ts b/src/core/agents/hook-endpoint-failover-sh.ts
index dea9bdb01..d6ac56aa1 100644
--- a/src/core/agents/hook-endpoint-failover-sh.ts
+++ b/src/core/agents/hook-endpoint-failover-sh.ts
@@ -135,10 +135,13 @@ export const HOOK_ENDPOINT_FALLBACK_SH = [
* ownership reference it let a Server Edition that opened the same project.json (same node ids)
* supply the "owner's" token whenever the desktop's own token write had failed, and then pass
* the owner check against itself.
- * - OWNER MODE needs that dir to EXIST. Then a candidate must hold exactly the same value in its
- * own dir — including both holding nothing, which is what a failed token write looks like on
- * every endpoint of the owning family. No such dir at all (a session with no endpoint file, a
- * pre-token layout) is the only unknown-owner case, and keeps the legacy walk: adopt, re-read.
+ * - OWNER MODE needs that dir to EXIST. With a token there, a candidate must hold the same value
+ * in its own dir. With NONE there (the desktop's token write failed), a value proves nothing — a
+ * Server Edition that never heard of this node holds nothing either, and "" === "" adopted it —
+ * so the candidate's token dir must be the SAME real directory (`pwd -P`, so an adjacent-derived
+ * or symlinked spelling still matches): sibling tunnels and a restarted desktop share it, an
+ * unrelated instance does not. No such dir at all (a session with no endpoint file, a pre-token
+ * layout) is the only unknown-owner case, and keeps the legacy walk: adopt, re-read.
* - A FALLBACK candidate is probed before it is posted to (`nt_probe_endpoint`). The real POST has
* no --max-time on purpose — a confirm-gated verb waits for a human, and a client-side timeout
* would fail over mid-wait and let a second instance raise a second dialog — but a reverse-
@@ -149,22 +152,29 @@ export const HOOK_ENDPOINT_FALLBACK_SH = [
* the last endpoint this node could use, which is what the codex-sandbox hint names as the
* socket to allow. */
export const OWNED_ENDPOINT_FALLBACK_SH = `
-# nt_owned_token_in <endpoint-file>: print the token the CURRENTLY SOURCED endpoint keeps for this
-# node, from the dir it advertises or else the one beside its file. Fails (status 1) when neither
-# names an existing directory — the unknown-owner case. Never the global dirs (see above).
-nt_owned_token_in() {
+# nt_token_dir_of <endpoint-file>: print the REAL path (pwd -P) of the token dir the CURRENTLY
+# SOURCED endpoint keeps — the one it advertises, else the one beside its file. Fails (status 1) when
+# neither names an existing directory: the unknown-owner case. Never the global dirs (see above).
+nt_token_dir_of() {
nt_otd="$NODETERM_NODE_TOKEN_DIR"
[ -n "$nt_otd" ] || nt_otd=$(nt_token_dir_beside "$1")
[ -n "$nt_otd" ] && [ -d "$nt_otd" ] || return 1
- head -n 1 "$nt_otd/$NODETERM_NODE_ID" 2>/dev/null || :
- return 0
+ (cd "$nt_otd" 2>/dev/null && pwd -P)
}
nt_owner_known=""
+nt_owner_dir=""
nt_owner_node_token=""
nt_skipped_foreign_endpoint=""
-if nt_owner_node_token=$(nt_owned_token_in "$NODETERM_HOOK_ENDPOINT"); then
+if nt_owner_dir=$(nt_token_dir_of "$NODETERM_HOOK_ENDPOINT"); then
nt_owner_known=1
+ nt_owner_node_token=$(head -n 1 "$nt_owner_dir/$NODETERM_NODE_ID" 2>/dev/null) || nt_owner_node_token=""
fi
+# An SSH project's reverse-tunnel endpoint: the only files the desktop writes under ~/.nodeterm.
+# Decides which advice a dead transport gets (TUNNEL_DOWN_HINT vs STALE_ENDPOINT_HINT).
+nt_primary_tunnel=""
+case "$NODETERM_HOOK_ENDPOINT" in
+ "$HOME"/.nodeterm/hook-endpoint.env|"$HOME"/.nodeterm/hook-endpoint-*.env) nt_primary_tunnel=1 ;;
+esac
nt_restore_endpoint() {
NODETERM_HOOK_SOCK="$nt_prev_sock"
@@ -188,9 +198,22 @@ nt_adopt_for_node() {
nt_read_node_token "$1"
return 0
fi
- nt_cand_token=$(nt_owned_token_in "$1") || nt_cand_token=""
- if [ "$nt_cand_token" = "$nt_owner_node_token" ]; then
- nt_node_token="$nt_cand_token"
+ nt_cand_dir=$(nt_token_dir_of "$1") || nt_cand_dir=""
+ if [ -n "$nt_owner_node_token" ]; then
+ # A reference VALUE: the candidate's own dir must hold the same capability for this node.
+ nt_cand_token=""
+ if [ -n "$nt_cand_dir" ]; then
+ nt_cand_token=$(head -n 1 "$nt_cand_dir/$NODETERM_NODE_ID" 2>/dev/null) || nt_cand_token=""
+ fi
+ if [ "$nt_cand_token" = "$nt_owner_node_token" ]; then
+ nt_node_token="$nt_cand_token"
+ return 0
+ fi
+ elif [ -n "$nt_cand_dir" ] && [ "$nt_cand_dir" = "$nt_owner_dir" ]; then
+ # An EMPTY reference proves nothing by value — a Server Edition that never heard of this node
+ # holds nothing too. Compare WHERE the tokens are kept: the same real directory is the same
+ # family of endpoints (sibling tunnels, a restarted desktop), and it holds nothing to present.
+ nt_node_token=""
return 0
fi
nt_skipped_foreign_endpoint=1
@@ -201,16 +224,18 @@ nt_adopt_for_node() {
# Bounded liveness probe for an ADOPTED fallback candidate. /hook/verify answers 204 on the bearer
# alone on every server build (the desktop's own tunnel probe used it before /verify existed, and
# the server keeps it answering for that reason) and 421 for a bearer it does not own. On failure
-# nt_code is set as the POST would have left it (421, or 000 for a dead transport) so the final
-# diagnosis reads the same; the candidate stays adopted, since it is this node's own endpoint.
+# nt_code is set as the POST would have left it (421, or 000 for a dead transport), and the reply
+# body lands in $nt_out exactly where the POST's would have, so the final diagnosis reads the same
+# (a 421 into /dev/null once left the control shim exiting 1 with an empty stderr). The candidate
+# stays adopted, since it is this node's own endpoint.
nt_probe_endpoint() {
nt_pc=""
if [ -n "$NODETERM_HOOK_SOCK" ]; then
nt_pc=$(nt_hook_headers |
- curl -s -o /dev/null -w '%{http_code}' -X POST --config - --connect-timeout 0.5 --max-time 1.5 --unix-socket "$NODETERM_HOOK_SOCK" "http://localhost/hook/verify" --data '' 2>/dev/null)
+ curl -s -o "$nt_out" -w '%{http_code}' -X POST --config - --connect-timeout 0.5 --max-time 1.5 --unix-socket "$NODETERM_HOOK_SOCK" "http://localhost/hook/verify" --data '' 2>/dev/null)
elif [ -n "$NODETERM_HOOK_PORT" ]; then
nt_pc=$(nt_hook_headers |
- curl -s -o /dev/null -w '%{http_code}' -X POST --config - --connect-timeout 0.5 --max-time 1.5 "http://127.0.0.1:$NODETERM_HOOK_PORT/hook/verify" --data '' 2>/dev/null)
+ curl -s -o "$nt_out" -w '%{http_code}' -X POST --config - --connect-timeout 0.5 --max-time 1.5 "http://127.0.0.1:$NODETERM_HOOK_PORT/hook/verify" --data '' 2>/dev/null)
else
nt_code=""
return 1
@@ -243,6 +268,18 @@ export const FOREIGN_ENDPOINT_HINT =
"project it usually means the desktop's reverse tunnel is down (the desktop is asleep, offline or " +
'reconnecting). Retry the same command after it reconnects.'
+/**
+ * The same diagnosis when nothing foreign was skipped but the session's primary endpoint is an SSH
+ * project's reverse-tunnel file (`~/.nodeterm/hook-endpoint*.env` — the only files the desktop
+ * writes under that dir). On that host the stale-endpoint advice ("retry once — it re-advertises the
+ * endpoint on start") describes an app restart; what brings a tunnel back is the desktop
+ * reconnecting. Starts with OWNER_UNREACHABLE_LEAD, so the agent-facing bodies' quote covers it.
+ */
+export const TUNNEL_DOWN_HINT =
+ `${OWNER_UNREACHABLE_LEAD} This session reaches it through an SSH project's reverse tunnel, and ` +
+ 'the tunnel is not answering: the desktop is asleep, offline or reconnecting, or nodeterm on it ' +
+ 'has quit. This is temporary — retry the same command after the desktop reconnects.'
+
/** The agent-facing half of FOREIGN_ENDPOINT_HINT, rendered into all four bodies (canvas skill +
* instructions block, context skill + instructions block). Without it an agent has only the
* bodies' other refusal lines to go on, and several of those correctly say "do not retry". */
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 7f33e4bab..46629eab9 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -9,6 +9,7 @@ import {
OWNED_ENDPOINT_FALLBACK_SH,
FOREIGN_ENDPOINT_HINT,
STALE_ENDPOINT_HINT,
+ TUNNEL_DOWN_HINT,
ownerUnreachableGuidanceLines
} from './agents/hook-endpoint-failover-sh'
import { codexSandboxGuidanceLines } from './context-link-core'
@@ -919,11 +920,20 @@ if [ -z "$nt_code" ] || [ "$nt_code" = "000" ]; then
else
nt_codex_sandbox_hint || echo "${CONTROL_UNREACHABLE_MSG}" >&2
# One piece of advice per failure: when the walk skipped a foreign endpoint, the owner-unreachable
- # sentence above already says what happened and when to retry.
+ # sentence above already says what happened and when to retry. Otherwise an SSH tunnel primary
+ # gets the tunnel advice (reconnect), anything else the stale-endpoint advice (app restart).
if [ -z "$CODEX_SANDBOX_NETWORK_DISABLED" ] && [ -z "$nt_skipped_foreign_endpoint" ]; then
- echo "${STALE_ENDPOINT_HINT}" >&2
+ if [ -n "$nt_primary_tunnel" ]; then
+ echo "${TUNNEL_DOWN_HINT}" >&2
+ else
+ echo "${STALE_ENDPOINT_HINT}" >&2
+ fi
fi
fi
+elif [ "$nt_code" = "421" ]; then
+ # Every endpoint that answered refused this bearer before dispatch (its body is printed above):
+ # nothing was delivered. Say so in the shim's own words, as the context shim always has.
+ echo "${CONTROL_UNREACHABLE_MSG}" >&2
fi
exit 1
`
diff --git a/src/core/context-link-core.test.ts b/src/core/context-link-core.test.ts
index 3797151b3..150d28078 100644
--- a/src/core/context-link-core.test.ts
+++ b/src/core/context-link-core.test.ts
@@ -11,7 +11,7 @@ import {
CONTEXT_UNREACHABLE_MSG
} from './context-link-core'
import { CODEX_SANDBOX_BLOCKED_LINE } from './agents/hook-sandbox-hint-sh'
-import { FOREIGN_ENDPOINT_HINT, OWNER_UNREACHABLE_LEAD } from './agents/hook-endpoint-failover-sh'
+import { FOREIGN_ENDPOINT_HINT, OWNER_UNREACHABLE_LEAD, TUNNEL_DOWN_HINT } from './agents/hook-endpoint-failover-sh'
describe('buildLinkDoc', () => {
it('enriches each link with tmux name, injected transcript path, and cwd', () => {
@@ -227,6 +227,9 @@ describe('buildLinkedContextInstructions', () => {
// owner-unreachable sentence that replaces it must be taught as temporary, in its own words.
it('both agent-facing texts teach the owner-unreachable failure as temporary', () => {
expect(CONTEXT_SHIM_SCRIPT).toContain(`echo "${FOREIGN_ENDPOINT_HINT}" >&2`)
+ // The tunnel variant (no foreign endpoint, SSH tunnel primary) opens with the same quoted lead.
+ expect(TUNNEL_DOWN_HINT.startsWith(OWNER_UNREACHABLE_LEAD)).toBe(true)
+ expect(CONTEXT_SHIM_SCRIPT).toContain(`echo "${TUNNEL_DOWN_HINT}" >&2`)
for (const body of [buildContextLinkSkillBody('/x/context.sh'), buildLinkedContextInstructions('/x/context.sh')]) {
expect(body).toContain(OWNER_UNREACHABLE_LEAD.replace(/\.$/, ''))
expect(body).toMatch(/This is temporary: *\n?retry the same *\n?command later/)
diff --git a/src/core/context-link-core.ts b/src/core/context-link-core.ts
index c337152a8..08a47e75e 100644
--- a/src/core/context-link-core.ts
+++ b/src/core/context-link-core.ts
@@ -10,6 +10,7 @@ import {
OWNED_ENDPOINT_FALLBACK_SH,
FOREIGN_ENDPOINT_HINT,
STALE_ENDPOINT_HINT,
+ TUNNEL_DOWN_HINT,
ownerUnreachableGuidanceLines
} from './agents/hook-endpoint-failover-sh'
import { NODE_TOKEN_READ_SH } from './agents/node-token-sh'
@@ -310,8 +311,13 @@ echo "${CONTEXT_UNREACHABLE_MSG}" >&2
# the agent stops relinking a healthy canvas (the link is fine; the app behind it is not there).
# One piece of advice per failure: when the walk skipped a foreign endpoint, the owner-unreachable
# sentence above already says what happened and when to retry.
+# An SSH tunnel primary gets the tunnel advice (reconnect), anything else the stale one (restart).
if { [ -z "$nt_code" ] || [ "$nt_code" = "000" ]; } && [ -z "$nt_skipped_foreign_endpoint" ]; then
- echo "${STALE_ENDPOINT_HINT}" >&2
+ if [ -n "$nt_primary_tunnel" ]; then
+ echo "${TUNNEL_DOWN_HINT}" >&2
+ else
+ echo "${STALE_ENDPOINT_HINT}" >&2
+ fi
fi
exit 1
`
diff --git a/src/core/owned-endpoint-walk.test.ts b/src/core/owned-endpoint-walk.test.ts
index 08d158bc4..c012ae3cc 100644
--- a/src/core/owned-endpoint-walk.test.ts
+++ b/src/core/owned-endpoint-walk.test.ts
@@ -23,9 +23,13 @@ import { createServer as createNetServer, type Server, type Socket } from 'node:
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
-import { CONTROL_SHIM_SCRIPT } from './canvas-control-core'
-import { CONTEXT_SHIM_SCRIPT } from './context-link-core'
-import { FOREIGN_ENDPOINT_HINT, STALE_ENDPOINT_HINT } from './agents/hook-endpoint-failover-sh'
+import { CONTROL_SHIM_SCRIPT, CONTROL_UNREACHABLE_MSG } from './canvas-control-core'
+import { CONTEXT_SHIM_SCRIPT, CONTEXT_UNREACHABLE_MSG } from './context-link-core'
+import {
+ FOREIGN_ENDPOINT_HINT,
+ STALE_ENDPOINT_HINT,
+ TUNNEL_DOWN_HINT
+} from './agents/hook-endpoint-failover-sh'
const NODE = 'n1'
const OWNER_TOKEN = 'owner-kid.owner-mac'
@@ -381,3 +385,103 @@ skipWin('4. a skipped foreign candidate leaves no endpoint behind', () => {
expect(foreign.posts).toEqual([])
}, T)
})
+
+// Review round 2 on #1018: three more shapes of the same incident class.
+skipWin('5. a probe that answers 421 still leaves the agent a sentence', () => {
+ // The primary is dead and the only fallback refuses this bearer (421) at the probe. The probe used
+ // to write to /dev/null, so the control shim exited 1 with EMPTY stderr — an agent sees a failed
+ // call and nothing to act on. It must print what a POST's 421 would have printed.
+ it.each(['control', 'context'] as const)('%s: exits 1 naming the wrong-owner answer', async (which) => {
+ const host = await sshHost()
+ const sock = path.join(host.home, '.nodeterm', 'b.sock')
+ const other = await endpoint(sock, 'rebound-bearer', { status: 200, body: 'never' })
+ endpointFile(path.join(host.home, '.nodeterm', 'hook-endpoint-pb.env'), sock, 'desk-bearer', host.tokens)
+ const r = await shim(host.d, which, ['list'], host.env)
+ expect(r.code).toBe(1)
+ expect(r.stderr).toContain('hook-endpoint-wrong-owner')
+ expect(r.stderr).toContain(which === 'control' ? CONTROL_UNREACHABLE_MSG : CONTEXT_UNREACHABLE_MSG)
+ expect(other.posts).toEqual([])
+ }, T)
+})
+
+skipWin('6. an EMPTY owner reference compares where tokens are kept, not what they say', () => {
+ // The primary's token dir exists but holds nothing for this node (the desktop's token write
+ // failed), and the Server Edition holds nothing for it either. "" === "" matched, the Server
+ // Edition was adopted, and its permanent refusal was relayed — measured in review.
+ it.each(['control', 'context'] as const)(
+ '%s: a Server Edition with no token for this node is skipped; the sibling tunnel is not',
+ async (which) => {
+ const host = await sshHost({ ownerToken: false })
+ const se = await serverEdition(host.home)
+ const sibling = await endpoint(path.join(host.home, '.nodeterm', 'b.sock'), 'desk-bearer', {
+ status: 200,
+ body: 'owner reply'
+ })
+ endpointFile(path.join(host.home, '.nodeterm', 'hook-endpoint-pb.env'), path.join(host.home, '.nodeterm', 'b.sock'), 'desk-bearer', host.tokens)
+ const r = await shim(host.d, which, ['list'], host.env)
+ expect(r).toMatchObject({ code: 0, stdout: 'owner reply' })
+ expect(se.probes).toEqual([])
+ expect(se.posts).toEqual([])
+ },
+ T
+ )
+
+ it('with no sibling alive, the refusal is never relayed', async () => {
+ const host = await sshHost({ ownerToken: false })
+ const se = await serverEdition(host.home)
+ const r = await shim(host.d, 'control', ['list'], host.env)
+ expect(r.code).toBe(1)
+ expect(r.stderr).toContain(FOREIGN_ENDPOINT_HINT)
+ expect(r.stderr).not.toMatch(/permanent|do not retry|control-unsupported/i)
+ expect(se.posts).toEqual([])
+ }, T)
+
+ // The comparison is by the directory's REAL path: an older sibling file that advertises no dir
+ // (so its dir is derived as <file's dir>/node-tokens) and a spelling through a symlink are the
+ // same place.
+ it('matches an adjacent-derived or symlinked spelling of the same dir', async () => {
+ const host = await sshHost({ ownerToken: false })
+ const alias = path.join(host.home, 'tok-alias')
+ fs.symlinkSync(host.tokens, alias)
+ endpointFile(host.primary, path.join(host.home, '.nodeterm', 'a.sock'), 'desk-bearer', alias)
+ const sibling = await endpoint(path.join(host.home, '.nodeterm', 'b.sock'), 'desk-bearer', {
+ status: 200,
+ body: 'owner reply'
+ })
+ endpointFile(path.join(host.home, '.nodeterm', 'hook-endpoint-pb.env'), path.join(host.home, '.nodeterm', 'b.sock'), 'desk-bearer')
+ const r = await shim(host.d, 'control', ['list'], host.env)
+ expect(r).toMatchObject({ code: 0, stdout: 'owner reply' })
+ expect(sibling.posts).toHaveLength(1)
+ }, T)
+})
+
+skipWin('7. a dead SSH tunnel with nothing foreign around says the desktop is down, once', () => {
+ // The common host: no Server Edition, just the session's own tunnel gone quiet. "retry once — it
+ // re-advertises the endpoint on start" is advice about an app restart; here the fix is the
+ // desktop reconnecting.
+ it.each(['control', 'context'] as const)('%s: tunnel primary → the tunnel advice, not the stale one', async (which) => {
+ const host = await sshHost()
+ const r = await shim(host.d, which, ['list'], host.env)
+ expect(r.code).toBe(1)
+ expect(r.stderr).toContain(TUNNEL_DOWN_HINT)
+ expect(r.stderr).not.toContain(STALE_ENDPOINT_HINT)
+ expect(r.stderr).not.toContain(FOREIGN_ENDPOINT_HINT)
+ expect(r.stderr).not.toMatch(/retry once|permanent|do not retry/i)
+ }, T)
+
+ it('a primary that is not an SSH tunnel file keeps the stale-endpoint advice', async () => {
+ const d = tmp()
+ const home = path.join(d, 'h')
+ const userData = path.join(home, '.config', 'node-terminal')
+ fs.mkdirSync(path.join(userData, 'node-tokens'), { recursive: true })
+ const primary = path.join(userData, 'hook-endpoint.env')
+ const sock = path.join(userData, 'x.sock')
+ await staleSocket(sock)
+ endpointFile(primary, sock, 'b', path.join(userData, 'node-tokens'))
+ const r = await shim(d, 'control', ['list'], { HOME: home, NODETERM_HOOK_ENDPOINT: primary })
+ expect(r.code).toBe(1)
+ expect(r.stderr).toContain(STALE_ENDPOINT_HINT)
+ expect(r.stderr).not.toContain(TUNNEL_DOWN_HINT)
+ }, T)
+})
+
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index e1a01823d..e18463e56 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -13,7 +13,7 @@ import {
CODEX_SANDBOX_RETRY_LINE
} from '../core/agents/hook-sandbox-hint-sh'
import { RETRYABLE } from '../core/agents/agent-message-decide'
-import { FOREIGN_ENDPOINT_HINT, OWNER_UNREACHABLE_LEAD } from '../core/agents/hook-endpoint-failover-sh'
+import { FOREIGN_ENDPOINT_HINT, OWNER_UNREACHABLE_LEAD, TUNNEL_DOWN_HINT } from '../core/agents/hook-endpoint-failover-sh'
import { PROJECT_TARGETABLE_VERBS } from '../core/project-grants'
import { DRY_RUN_VERBS } from '../shared/control-verbs'
import {
@@ -411,6 +411,9 @@ describe('parseControlRequest', () => {
it('both agent-facing texts teach the owner-unreachable failure as temporary', () => {
expect(FOREIGN_ENDPOINT_HINT.startsWith(OWNER_UNREACHABLE_LEAD)).toBe(true)
expect(CONTROL_SHIM_SCRIPT).toContain(`echo "${FOREIGN_ENDPOINT_HINT}" >&2`)
+ // The tunnel variant (no foreign endpoint, SSH tunnel primary) opens with the same quoted lead.
+ expect(TUNNEL_DOWN_HINT.startsWith(OWNER_UNREACHABLE_LEAD)).toBe(true)
+ expect(CONTROL_SHIM_SCRIPT).toContain(`echo "${TUNNEL_DOWN_HINT}" >&2`)
for (const body of [buildCanvasSkillBody('/x/shim.sh'), buildCanvasControlInstructions('/tmp/nodeterm.sh')]) {
expect(body).toContain(OWNER_UNREACHABLE_LEAD.replace(/\.$/, ''))
expect(body).toMatch(/This is temporary: *\n?retry the same *\n?command later/)