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(ssh): review fixes for the agent-tools freshness check

review00344afffb22
diff --git a/CLAUDE.md b/CLAUDE.md
index 0e96241e3..ee7dc1936 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2441,12 +2441,25 @@ else, and its context links must keep classifying across restarts).
builds, and would trust a file's claim about itself. `cksum` because it is the one checksum POSIX
requires; CRC-32 + length is not collision resistant and does not need to be, because this
detects drift and is not a security check. Ubuntu's own BusyBox build omits `cksum`, so such a
- host exists: it falls back to writing everything on a connect or repair, which is what every
- connect did before. The probe is tested under dash, bash, BusyBox sh and zsh with mawk, gawk,
- BusyBox awk and the one-true awk (the macOS dialect, via `NT_PROBE_EXTRA_AWK`).
+ host exists: missing, unreadable and gated files are still told apart there, the files it can
+ read are written without comparison (what every connect did before) and the blocks merged. An
+ awk that fails on a block is reported (`X`, through fd 3 — `awk | cksum` exits with cksum's
+ status) and that block is merged, which writes only on a change. Only files ACTUALLY written
+ are logged as "rewrote" or make the outcome `refreshed`. The permanent suite runs the probe
+ under every shell × awk the machine has (what the CI image has); a one-off manual run added
+ BusyBox sh, zsh 5.9 and the one-true awk 20231127 (`NT_PROBE_EXTRA_AWK` / `_SH`). macOS's own
+ awk (20200816) and BSD `cksum` have never been run — that is on the PR's Mac checklist.
+ - **The end marker is searched AFTER the start marker** — in both `merge*Block` functions and in
+ the probe's awk alike. Taking the first end marker anywhere read a hand-deleted block's leftover
+ end line as "no block": the merge appended a fresh copy every time, and with an hourly check a
+ host's AGENTS.md grew by one block an hour (measured in review: 41,693 → 81,279 → 120,865 →
+ 160,451 bytes). The same merges run at boot for the desktop's and the Server Edition's own local
+ instruction files (`initCanvasControl`, `initContextLink`), which grew by one block per launch.
- **Refusals.** A file that is not a readable regular file (a directory, a dangling dotfile link,
no permission) is NEVER written over, and the host is not called confirmed. A managed account's
- skill is refreshed only when its dir ALREADY exists (never resurrected). A report that does not
+ skill is refreshed only when its dir ALREADY exists — checked by the probe and again on the host
+ in the write itself (`remoteAtomicWrite`'s `requireDir`), so a dir removed in between is not
+ brought back by the parent `mkdir -p`. A report that does not
parse changes nothing. Account ids from settings are re-validated (`isSafeAccountId`) before
they become paths. The copilot block is judged at the host's `$COPILOT_HOME` only when the
installer's validator would accept that value.
@@ -2457,10 +2470,13 @@ else, and its context links must keep classifying across restarts).
(`AGENT_TOOLS_RECHECK_MS`), because within a run only a writer outside it (another desktop,
possibly an older build, on the same host account; a hand edit) can change the files. One check
per host at a time: projects sharing a host share it.
- - **Anything new we put on a host goes into the artifact plan in `remote-hooks.ts`**
- (`canvasControlArtifacts` / `contextLinkArtifacts` / `accountSkillArtifacts`). The installers
- and the probe both read it, so a file added there is written AND kept current. A file written
- anywhere else is written once and never looked at again.
+ - **A new agent-facing doc on a host goes into the artifact plan in `remote-hooks.ts`**
+ (`canvasControlArtifacts` / `contextLinkArtifacts` / `accountSkillArtifacts`) — shims, skills,
+ instruction blocks. The installers and the probe both read it, so a file added there is written
+ AND kept current. NOT the rest of what connect writes: the hook scripts and the agents' hook
+ config belong to `setup()`'s ordered chain (after the verified tunnel and the endpoint file),
+ and the endpoint file and node tokens carry credentials — none of those may be rewritten on a
+ freshness cadence.
- **What a running agent sees.** The shim's `help` is answered by the shim itself (baked from the
verb registry), so it is current the moment the file is. Claude reads a SKILL.md body when the
skill is invoked; codex, gemini and opencode read their instruction files at session start, so
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8449bc256..c36427d77 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -475,12 +475,14 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
symlink and mode. A guard test fails on a new bare `cat >`. A remote runner RESOLVES on a
non-zero exit, so check the result or use the helper that does.
-- **Anything the app puts on an SSH host goes into the agent-tools plan.** The canvas/context
+- **A new agent-facing doc on an SSH host goes into the agent-tools plan.** The canvas/context
shims, their skills and our instruction-file blocks are listed once in `remote-hooks.ts`
(`canvasControlArtifacts` and its siblings); the installers AND the connect-time freshness check
(`RemoteHooks.refreshAgentTools`) read that list, so a host is brought up to your build's bytes
- on the next connect. A file written from anywhere else is written once and never checked again —
- hosts then keep the old text across app updates.
+ on the next connect. A shim, skill or block written from anywhere else is written once and never
+ checked again — hosts then keep the old text across app updates. This is ONLY for those docs:
+ hook scripts and hook config stay in `setup()`'s ordered chain, and the endpoint file and node
+ tokens carry credentials — never put them on a freshness cadence.
- **Never write `chmod <mode> -- <file>` into a remote command.** macOS (BSD) chmod stops parsing
options at the mode, so the `--` becomes a file operand and the command fails there while passing
diff --git a/docs/ssh-agent-skills.md b/docs/ssh-agent-skills.md
index 275ab27e4..d79188670 100644
--- a/docs/ssh-agent-skills.md
+++ b/docs/ssh-agent-skills.md
@@ -99,13 +99,17 @@ both skills (system and every managed account pinned to the host), and our instr
- **One probe, one round trip.** The host runs POSIX `cksum` over each file (over exactly our
marker span for an instruction file), and the desktop compares that with the checksum of the
bytes it would write. Only what differs is rewritten; a current host costs one read and no
- write. A host with no `cksum` gets everything written, as every connect did before.
+ write. On a host with no `cksum`, the files it can read are written without comparison (as every
+ connect did before) and the blocks merged; missing, unreadable and gated files are still told
+ apart.
- **When.** Every connect (a fresh master, or the one that survived an app restart) and every
reverse-tunnel repair. The 45 s watchdog costs nothing once the host is confirmed for this run,
retries an unconfirmed host on a 1/5/15-minute backoff, and looks again hourly — the only thing
that can change the files mid-run is someone else (another desktop, a hand edit).
- **Never.** A file that cannot be read is not written over; a managed account whose dir is gone
- from the host does not get it back; a probe reply that does not parse changes nothing.
+ from the host does not get it back (re-checked in the write itself); a probe reply that does not
+ parse changes nothing. A stray end marker left above a hand-deleted block is skipped — by the
+ merge and the probe alike — so it no longer makes every check append a new copy.
- **A running agent** keeps what it already read: the shim's `help` is current as soon as the
file is, a Claude skill is re-read when it is next invoked, and codex / gemini / opencode read
their instruction files at session start.
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index f390ccc8f..60f6fc73d 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -570,11 +570,15 @@ export function frameCanvasControlBlock(block: string): string {
}
/** Idempotently merge the canvas-control block into a global instructions file.
- * Everything outside the markers is preserved; an existing block is replaced. */
+ * Everything outside the markers is preserved; an existing block is replaced.
+ *
+ * The end marker is searched AFTER the start marker. Taking the first one anywhere read a stray
+ * end line (a block the user deleted by hand, end line kept) as "no block", so every merge
+ * appended another copy — on the desktop at every launch, and on an SSH host at every check. */
export function mergeCanvasControlBlock(existing: string, block: string): string {
const full = frameCanvasControlBlock(block)
const start = existing.indexOf(CC_START)
- const end = existing.indexOf(CC_END)
+ const end = existing.indexOf(CC_END, start)
if (start >= 0 && end > start) {
return existing.slice(0, start) + full + existing.slice(end + CC_END.length)
}
diff --git a/src/core/context-link-core.test.ts b/src/core/context-link-core.test.ts
index 150d28078..aece95227 100644
--- a/src/core/context-link-core.test.ts
+++ b/src/core/context-link-core.test.ts
@@ -197,6 +197,16 @@ describe('mergeInstructionsBlock', () => {
const out = mergeInstructionsBlock('', block)
expect(out.startsWith('<!-- nodeterm:get-linked-context:start -->')).toBe(true)
})
+ it('a stray end marker BEFORE the block does not make every merge append another copy', () => {
+ // A user who deletes our block by hand but leaves its end line: the end marker is found first,
+ // and a merge that took the first end marker anywhere read "no block" and appended — again on
+ // every connect, forever. The end marker is searched AFTER the start marker.
+ const stray = '# mine\n<!-- nodeterm:get-linked-context:end -->\n'
+ const once = mergeInstructionsBlock(stray, block)
+ expect(mergeInstructionsBlock(once, block)).toBe(once)
+ expect(once.match(/get-linked-context:start/g)).toHaveLength(1)
+ expect(once.startsWith(stray)).toBe(true)
+ })
})
describe('buildLinkedContextInstructions', () => {
diff --git a/src/core/context-link-core.ts b/src/core/context-link-core.ts
index b340821b0..732305db4 100644
--- a/src/core/context-link-core.ts
+++ b/src/core/context-link-core.ts
@@ -80,11 +80,12 @@ export function frameInstructionsBlock(block: string): string {
}
/** Idempotently merge our marker-delimited block into a global instructions file
- * (~/.codex/AGENTS.md, ~/.gemini/GEMINI.md). Everything outside the markers is preserved. */
+ * (~/.codex/AGENTS.md, ~/.gemini/GEMINI.md). Everything outside the markers is preserved.
+ * The end marker is searched AFTER the start marker (see `mergeCanvasControlBlock`). */
export function mergeInstructionsBlock(existing: string, block: string): string {
const full = frameInstructionsBlock(block)
const start = existing.indexOf(INSTR_START)
- const end = existing.indexOf(INSTR_END)
+ const end = existing.indexOf(INSTR_END, start)
if (start >= 0 && end > start) {
return existing.slice(0, start) + full + existing.slice(end + INSTR_END.length)
}
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 9c08800ea..e76ea8040 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -349,6 +349,16 @@ describe('parseControlRequest', () => {
expect(second).toContain('# My own notes')
})
+ it('a stray end marker BEFORE the block does not make every merge append another copy', () => {
+ // The end marker is searched AFTER the start marker; taking the first one anywhere read a
+ // hand-deleted block's leftover end line as "no block" and appended on every connect.
+ const block = buildCanvasControlInstructions('/tmp/nodeterm.sh')
+ const stray = '# mine\n<!-- nodeterm:manage-canvas:end -->\n'
+ const once = mergeCanvasControlBlock(stray, block)
+ expect(mergeCanvasControlBlock(once, block)).toBe(once)
+ expect(once.match(/manage-canvas:start/g)).toHaveLength(1)
+ })
+
it('instructions cover the verb set and the confirm caveat', () => {
const body = buildCanvasControlInstructions('/tmp/nodeterm.sh')
for (const verb of ['list', 'open-agent', 'spawn-team', 'group', 'ungroup', 'move', 'arrange', 'rename', 'color', 'write', 'close', 'board', 'assign']) {
diff --git a/src/main/remote-atomic-write.test.ts b/src/main/remote-atomic-write.test.ts
index 8cfbf6c57..e31323a8b 100644
--- a/src/main/remote-atomic-write.test.ts
+++ b/src/main/remote-atomic-write.test.ts
@@ -4,7 +4,13 @@ import os from 'os'
import path from 'path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { quoteRemotePath } from '../shared/ssh'
-import { remoteAtomicWrite, REMOTE_WRITE_SHORT_BODY, RemoteWriteError, runRemoteAtomicWrite } from './remote-atomic-write'
+import {
+ remoteAtomicWrite,
+ REMOTE_WRITE_NO_DIR,
+ REMOTE_WRITE_SHORT_BODY,
+ RemoteWriteError,
+ runRemoteAtomicWrite
+} from './remote-atomic-write'
const SHELL =
process.platform === 'win32'
@@ -271,6 +277,25 @@ describe('remoteAtomicWrite', { timeout: REAL_SHELL_TIMEOUT_MS }, () => {
}
)
+ it.skipIf(!SHELL)('requireDir: writes only into a directory that ALREADY exists — never brings one back', () => {
+ // A managed account's skill is refreshed only while the account's dir is on the host; the
+ // parent `mkdir -p` must not resurrect a dir removed after the caller looked.
+ const root = mkdtempSync(path.join(os.tmpdir(), 'nt-remote-requiredir-'))
+ roots.push(root)
+ const account = `${shellPath(root)}/acc`
+ const target = `${account}/skills/x/SKILL.md`
+ const write = remoteAtomicWrite(target, 'skill\n', { requireDir: account })
+
+ const refused = spawnSync(SHELL!, ['-c', write.command], { input: write.stdin, encoding: 'utf8' })
+ expect(refused.status).toBe(REMOTE_WRITE_NO_DIR)
+ expect(readdirSync(root)).toEqual([])
+ expect(new RemoteWriteError(target, REMOTE_WRITE_NO_DIR).message).toContain('no longer exists')
+
+ mkdirSync(path.join(root, 'acc'))
+ execFileSync(SHELL!, ['-c', write.command], { input: write.stdin })
+ expect(readFileSync(path.join(root, 'acc/skills/x/SKILL.md'), 'utf8')).toBe('skill\n')
+ })
+
it('refuses an empty body before any command exists, unless the caller allows one', () => {
expect(() => remoteAtomicWrite('/h/.nodeterm/nodeterm.sh', '')).toThrow(/empty body/)
const editorSave = remoteAtomicWrite('/h/notes.txt', '', { allowEmpty: true })
diff --git a/src/main/remote-atomic-write.ts b/src/main/remote-atomic-write.ts
index 1171b4d7c..3fc4faee2 100644
--- a/src/main/remote-atomic-write.ts
+++ b/src/main/remote-atomic-write.ts
@@ -16,6 +16,12 @@ export interface RemoteAtomicWrite {
*/
export const REMOTE_WRITE_SHORT_BODY = 65
+/**
+ * Exit status of a write refused because its `requireDir` did not exist when the write ran.
+ * sysexits' EX_NOINPUT; nothing else in these commands exits with it.
+ */
+export const REMOTE_WRITE_NO_DIR = 66
+
export type RemoteFileMode = '600' | '644' | '700' | '755'
export interface RemoteAtomicWriteOptions {
@@ -29,6 +35,10 @@ export interface RemoteAtomicWriteOptions {
/** An editor may legitimately save an empty file. Nothing this app GENERATES is ever empty, so
* an empty body is refused unless the caller says otherwise. */
allowEmpty?: boolean
+ /** Write only if this directory ALREADY exists on the host — checked in the same command as the
+ * write, so a directory removed after the caller looked is not recreated by the parent
+ * `mkdir -p`. Refused with `REMOTE_WRITE_NO_DIR`, the body drained so ssh sees no broken pipe. */
+ requireDir?: string
}
function remoteDirname(path: string): string {
@@ -87,7 +97,10 @@ export function remoteAtomicWrite(
: `${parentPath}/${temporaryLeaf}`
const target = quoteRemotePath(path)
const temporary = quoteRemotePath(temporaryPath)
- const prefix = options.restrictPermissions ? 'umask 077; ' : ''
+ const gate = options.requireDir
+ ? `[ -d ${quoteRemotePath(options.requireDir)} ] || { cat > /dev/null; exit ${REMOTE_WRITE_NO_DIR}; }; `
+ : ''
+ const prefix = `${gate}${options.restrictPermissions ? 'umask 077; ' : ''}`
const parent = options.makeParent === false
? ''
: `mkdir -p -- ${quoteRemotePath(parentPath)} && `
@@ -117,6 +130,7 @@ export class RemoteWriteError extends Error {
super(
`remote write of ${path} did not land (exit ${code}` +
(code === REMOTE_WRITE_SHORT_BODY ? ': the body did not arrive in full' : '') +
+ (code === REMOTE_WRITE_NO_DIR ? ': its directory no longer exists' : '') +
'); the previous file is unchanged'
)
this.name = 'RemoteWriteError'
diff --git a/src/main/remote-ssh/agent-tools-freshness.test.ts b/src/main/remote-ssh/agent-tools-freshness.test.ts
index 55851c9a0..5d35af3bc 100644
--- a/src/main/remote-ssh/agent-tools-freshness.test.ts
+++ b/src/main/remote-ssh/agent-tools-freshness.test.ts
@@ -5,7 +5,7 @@ import { execFileSync, spawnSync } from 'child_process'
import { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'fs'
import { tmpdir } from 'os'
import path from 'path'
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { afterAll, afterEach, beforeEach, describe, expect, it } from 'vitest'
import { formatCksum, posixCksum } from '../../core/remote-ssh/posix-cksum'
import { mergeCanvasControlBlock, frameCanvasControlBlock, CANVAS_CONTROL_MARKERS } from '../../core/canvas-control-core'
import { posixQuote } from '../../shared/ssh'
@@ -21,12 +21,39 @@ import {
const sum = (text: string) => formatCksum(posixCksum(Buffer.from(text, 'utf8')))
/** The formatted checksum the report holds for entry `i`, or its state when it holds none. */
function sumAt(report: ReturnType<typeof parseAgentToolsReport>, i: number): string {
- if (report?.kind !== 'report') return String(report?.kind)
+ if (!report) return 'no report'
const s = report.statuses[i]
return s.state === 'present' ? formatCksum(s.sum) : s.state
}
const { start: S, end: E } = CANVAS_CONTROL_MARKERS
+/** A PATH holding every tool this machine has EXCEPT cksum — built once for the whole file. */
+let noCksum: string | undefined
+function noCksumBin(): string {
+ if (noCksum) return noCksum
+ noCksum = mkdtempSync(path.join(tmpdir(), 'nt-no-cksum-'))
+ for (const d of ['/usr/bin', '/bin']) {
+ let names: string[] = []
+ try {
+ names = readdirSync(d)
+ } catch {
+ continue
+ }
+ for (const n of names) {
+ if (n === 'cksum') continue
+ try {
+ symlinkSync(path.join(d, n), path.join(noCksum, n))
+ } catch {
+ // already linked from the other directory
+ }
+ }
+ }
+ return noCksum
+}
+afterAll(() => {
+ if (noCksum) rmSync(noCksum, { recursive: true, force: true })
+})
+
let home: string
beforeEach(() => {
home = mkdtempSync(path.join(tmpdir(), "nt-fresh-' h-"))
@@ -63,7 +90,7 @@ describe.skipIf(process.platform === 'win32')('the freshness probe (real /bin/sh
const body = '#!/bin/sh\necho şimdi\n'
const p = put('.nodeterm/nodeterm.sh', body)
const report = parseAgentToolsReport(runProbe([file(p)]), 1)
- expect(report).toEqual({ kind: 'report', statuses: [{ state: 'present', sum: posixCksum(Buffer.from(body)) }], env: '' })
+ expect(report).toEqual({ hasCksum: true, statuses: [{ state: 'present', sum: posixCksum(Buffer.from(body)) }], env: '' })
})
it('tells missing from unreadable, and never reads through a dangling link or a directory', () => {
@@ -75,7 +102,7 @@ describe.skipIf(process.platform === 'win32')('the freshness probe (real /bin/sh
runProbe([file(path.join(home, 'absent.sh')), file(dir), file(dangling)]),
3
)
- expect(report?.kind === 'report' && report.statuses.map((s) => s.state)).toEqual([
+ expect(report?.statuses.map((s) => s.state)).toEqual([
'missing',
'unreadable',
'unreadable'
@@ -90,7 +117,7 @@ describe.skipIf(process.platform === 'win32')('the freshness probe (real /bin/sh
runProbe([file(skill, acc), file(path.join(gone, 'skills/x/SKILL.md'), gone)]),
2
)
- expect(report?.kind === 'report' && report.statuses).toEqual([
+ expect(report?.statuses).toEqual([
{ state: 'present', sum: posixCksum(Buffer.from('x\n')) },
{ state: 'no-gate' }
])
@@ -102,15 +129,22 @@ describe.skipIf(process.platform === 'win32')('the freshness probe (real /bin/sh
const stale = put('.gemini/GEMINI.md', mergeCanvasControlBlock('', 'an OLD block'))
const report = parseAgentToolsReport(runProbe([block(posixQuote(p)), block(posixQuote(stale))]), 2)
const want = frameCanvasControlBlock('the block\nsecond line')
- expect(report?.kind === 'report' && report.statuses[0]).toEqual({ state: 'present', sum: posixCksum(Buffer.from(want)) })
+ expect(report?.statuses[0]).toEqual({ state: 'present', sum: posixCksum(Buffer.from(want)) })
expect(sumAt(report, 1)).not.toBe(sum(want))
})
- it('an end marker BEFORE the start marker is no block at all, as the merge sees it', () => {
- // mergeCanvasControlBlock only replaces when the first end marker follows the first start
- // marker; otherwise it appends. The probe must not call such a file current.
+ it('a stray end marker BEFORE the start marker is skipped, as the merge skips it', () => {
+ // The merge searches the end marker AFTER the first start marker, so a hand-deleted block's
+ // leftover end line is not "the end of our block". The probe must find the same span, or such
+ // a file reads stale on every check.
const p = put('.codex/AGENTS.md', `${E}\n${frameCanvasControlBlock('b')}\n`)
const report = parseAgentToolsReport(runProbe([block(posixQuote(p))]), 1)
+ expect(sumAt(report, 0)).toBe(sum(frameCanvasControlBlock('b')))
+ })
+
+ it('a start marker with no end marker after it is no block at all', () => {
+ const p = put('.codex/AGENTS.md', `${frameCanvasControlBlock('b')}\n${S}\n`.replace(E, 'gone'))
+ const report = parseAgentToolsReport(runProbe([block(posixQuote(p))]), 1)
expect(sumAt(report, 0)).toBe(sum(''))
})
@@ -118,36 +152,50 @@ describe.skipIf(process.platform === 'win32')('the freshness probe (real /bin/sh
put('.copilot/copilot-instructions.md', 'c\n')
const expr = '"${COPILOT_HOME:-$NT_H/.copilot}/copilot-instructions.md"'
const unset = parseAgentToolsReport(runProbe([{ kind: 'file', pathExpr: expr }]), 1)
- expect(unset).toEqual({ kind: 'report', statuses: [{ state: 'present', sum: posixCksum(Buffer.from('c\n')) }], env: '' })
+ expect(unset).toEqual({ hasCksum: true, statuses: [{ state: 'present', sum: posixCksum(Buffer.from('c\n')) }], env: '' })
const hostile = '/x\nNT_END\n0 C 1 1'
const set = parseAgentToolsReport(runProbe([{ kind: 'file', pathExpr: expr }], { COPILOT_HOME: hostile }), 1)
// The env value is data: it can neither forge a status line nor end the report early.
- expect(set).toEqual({ kind: 'report', statuses: [{ state: 'missing' }], env: hostile })
+ expect(set).toEqual({ hasCksum: true, statuses: [{ state: 'missing' }], env: hostile })
+ })
+
+ it('a host with no cksum says so — and still tells missing, unreadable and gated files apart', () => {
+ // Ubuntu's own BusyBox build ships without the applet, so "no cksum" is a real host. The
+ // content of what is there cannot be compared (`unknown`), but what is NOT there, or cannot be
+ // read, still is — the fallback must not write into a directory sitting at a file's path.
+ const dir = path.join(home, 'a-directory')
+ mkdirSync(dir)
+ const out = runProbe(
+ [
+ file(put('present', 'p')),
+ file(path.join(home, 'absent')),
+ file(dir),
+ file(path.join(home, 'gone/x'), path.join(home, 'gone')),
+ block(posixQuote(put('blk', frameCanvasControlBlock('b'))))
+ ],
+ {},
+ noCksumBin()
+ )
+ expect(parseAgentToolsReport(out, 5)).toEqual({
+ hasCksum: false,
+ statuses: [{ state: 'unknown' }, { state: 'missing' }, { state: 'unreadable' }, { state: 'no-gate' }, { state: 'unknown' }],
+ env: ''
+ })
})
- it('a host with no cksum says so instead of reporting every file unreadable', () => {
- // A PATH holding every tool this machine has EXCEPT cksum (Ubuntu's own BusyBox build ships
- // without the applet, so "no cksum" is a real host, not a hypothetical one).
- const bin = mkdtempSync(path.join(tmpdir(), 'nt-no-cksum-'))
+ it('an awk that fails is reported, not hidden behind the pipeline into cksum', () => {
+ // `awk … | cksum` exits with cksum's status, so a missing or broken awk used to read as "the
+ // block is empty" — stale on every check, and a merge that changed nothing logged as a rewrite.
+ const bin = mkdtempSync(path.join(tmpdir(), 'nt-bad-awk-'))
try {
- for (const d of ['/usr/bin', '/bin']) {
- let names: string[] = []
- try {
- names = readdirSync(d)
- } catch {
- continue
- }
- for (const n of names) {
- if (n === 'cksum') continue
- try {
- symlinkSync(path.join(d, n), path.join(bin, n))
- } catch {
- // already linked from the other directory
- }
- }
- }
- const out = runProbe([file(put('a', 'a'))], {}, bin)
- expect(parseAgentToolsReport(out, 1)).toEqual({ kind: 'no-cksum', env: '' })
+ writeFileSync(path.join(bin, 'awk'), '#!/bin/sh\nexit 2\n', { mode: 0o755 })
+ const p = put('.codex/AGENTS.md', frameCanvasControlBlock('b'))
+ const f = put('owned', 'o')
+ const report = parseAgentToolsReport(
+ runProbe([block(posixQuote(p)), file(f)], {}, `${bin}:${process.env.PATH ?? '/usr/bin:/bin'}`),
+ 2
+ )
+ expect(report?.statuses).toEqual([{ state: 'unknown' }, { state: 'present', sum: posixCksum(Buffer.from('o')) }])
} finally {
rmSync(bin, { recursive: true, force: true })
}
@@ -214,7 +262,7 @@ describe.skipIf(process.platform === 'win32')('the probe under every sh × awk o
expect([0, 1, 2, 3, 4, 5].map((i) => sumAt(report, i))).toEqual([
sum(frameCanvasControlBlock('line one\nline — two')),
sum(texts.crlf), // CR stays inside its line: the span is the file's own bytes
- sum(''), // end before start: no block, as the merge sees it
+ sum(frameCanvasControlBlock('b')), // a stray end marker before the start is skipped
sum(''),
sum(frameCanvasControlBlock('tail')),
sum('#!/bin/sh\necho ğ\n')
@@ -226,34 +274,45 @@ describe.skipIf(process.platform === 'win32')('the probe under every sh × awk o
})
describe('parseAgentToolsReport', () => {
- const ok = 'NT_AGENT_TOOLS_CHECK 1\n0 C 1 2\n1 M\n2 U\n3 D\nNT_ENV COPILOT_HOME=/c\nNT_END\n'
+ const ok = 'NT_AGENT_TOOLS_CHECK 1\n0 C 1 2\n1 M\n2 U\n3 D\n4 X\nNT_ENV COPILOT_HOME=/c\nNT_END\n'
it('reads a well-formed report, tolerating a login banner before it', () => {
- expect(parseAgentToolsReport(`Welcome!\n${ok}`, 4)).toEqual({
- kind: 'report',
+ expect(parseAgentToolsReport(`Welcome!\n${ok}`, 5)).toEqual({
+ hasCksum: true,
statuses: [
{ state: 'present', sum: { crc: 1, size: 2 } },
{ state: 'missing' },
{ state: 'unreadable' },
- { state: 'no-gate' }
+ { state: 'no-gate' },
+ { state: 'unknown' }
],
env: '/c'
})
})
+ it('reads a no-cksum report, which may hold no checksum at all', () => {
+ const noCk = 'NT_AGENT_TOOLS_CHECK 1\nNT_NO_CKSUM\n0 X\n1 M\nNT_ENV COPILOT_HOME=\nNT_END\n'
+ expect(parseAgentToolsReport(noCk, 2)).toEqual({
+ hasCksum: false,
+ statuses: [{ state: 'unknown' }, { state: 'missing' }],
+ env: ''
+ })
+ expect(parseAgentToolsReport(noCk.replace('0 X', '0 C 1 2'), 2)).toBeNull()
+ })
+
it('refuses a report that is cut short, out of order, over-long or malformed — never guesses', () => {
const bad = [
'',
'NT_AGENT_TOOLS_CHECK 1\n0 C 1 2\n', // no end
ok.replace('\nNT_END\n', '\n'), // no end sentinel
ok.replace('1 M', '2 M'), // out of order
- ok.replace('3 D\n', ''), // too few
- ok.replace('3 D\n', '3 D\n4 M\n'), // too many
+ ok.replace('4 X\n', ''), // too few
+ ok.replace('4 X\n', '4 X\n5 M\n'), // too many
ok.replace('0 C 1 2', '0 C one 2'), // not a checksum
- ok.replace('2 U', '2 X'), // unknown status
+ ok.replace('2 U', '2 Z'), // unknown status
ok.replace('NT_AGENT_TOOLS_CHECK 1', 'NT_AGENT_TOOLS_CHECK 2') // a version we do not speak
]
- for (const b of bad) expect(parseAgentToolsReport(b, 4)).toBeNull()
+ for (const b of bad) expect(parseAgentToolsReport(b, 5)).toBeNull()
})
})
diff --git a/src/main/remote-ssh/agent-tools-freshness.ts b/src/main/remote-ssh/agent-tools-freshness.ts
index ab6d5e32b..625726ed5 100644
--- a/src/main/remote-ssh/agent-tools-freshness.ts
+++ b/src/main/remote-ssh/agent-tools-freshness.ts
@@ -20,7 +20,8 @@
* foreign writer that keeps the line goes unseen. Hashing the bytes catches a generator change
* with no version bump, a deletion, and a foreign or older writer, and works on day one against
* files older builds wrote. The checksum is POSIX `cksum` (see posix-cksum.ts for why not sha256);
- * a host without one falls back to the pre-check behaviour — write everything.
+ * on a host without one, the files it can read are written without comparison (what every connect
+ * did before) and the blocks merged — but missing, unreadable and gated files are still told apart.
*
* ONE ROUND TRIP. Every file is probed by one generated command whose reply is a few hundred bytes,
* so a check costs no more than the tunnel probe beside it — and a host that is current costs no
@@ -51,11 +52,18 @@ export type ProbeStatus =
* NEVER written over: we cannot see what we would be replacing. */
| { state: 'unreadable' }
| { state: 'no-gate' }
+ /** A readable regular file whose content could not be checksummed: the host has no `cksum`, or
+ * awk failed on this instruction file. Not evidence either way — the caller writes an owned file
+ * (what every connect did before the check) and MERGES an instruction block, which writes only
+ * when the merge changes something. */
+ | { state: 'unknown' }
-export type AgentToolsReport =
- | { kind: 'report'; statuses: ProbeStatus[]; env: string }
- /** The host has no `cksum`. Nothing was probed; `env` is still reported. */
- | { kind: 'no-cksum'; env: string }
+export interface AgentToolsReport {
+ /** False on a host with no `cksum`: every readable file is then `unknown`. */
+ hasCksum: boolean
+ statuses: ProbeStatus[]
+ env: string
+}
const HEADER = 'NT_AGENT_TOOLS_CHECK 1'
const END = 'NT_END'
@@ -63,19 +71,26 @@ const END = 'NT_END'
/**
* The span of an instruction file that `merge*Block` would replace, printed byte for byte (awk
* under LC_ALL=C, so `index`/`substr` count bytes): from the FIRST start marker through the end of
- * the FIRST end marker, and only when that end marker comes after the start marker — otherwise the
- * merge appends, so there is no block and nothing is printed. Lines are rejoined with the `\n` awk
- * split them on; a `\r` stays inside its line, so a CRLF file does not pass for our LF block.
+ * the first end marker AFTER it — the merge's own rule, so a stray end line left above a
+ * hand-deleted block is skipped here exactly as it is there. No start marker, or none of the end
+ * marker after it, is no block: nothing is printed and the merge appends. Lines are rejoined with
+ * the `\n` awk split them on; a `\r` stays inside its line, so a CRLF file does not pass for our
+ * LF block.
*/
const AWK_BLOCK =
'{ t = (NR == 1) ? $0 : t "\\n" $0 } ' +
- 'END { i = index(t, s); j = index(t, e); if (i > 0 && j > i) printf "%s", substr(t, i, j - i + length(e)) }'
+ 'END { i = index(t, s); if (i > 0) { r = substr(t, i); j = index(r, e); ' +
+ 'if (j > 0) printf "%s", substr(r, 1, j - 1 + length(e)) } }'
/**
- * The probe. Output, one line each: the header; then either `NT_NO_CKSUM`, or one status per entry
- * in order (`<i> C <crc> <size>` | `<i> M` | `<i> U` | `<i> D`); then `NT_ENV <name>=<value>`
- * (the one environment variable the caller needs resolved on the host — printed LAST, because it
- * is host data and must not be able to forge a status line); then `NT_END`.
+ * The probe. Output, one line each: the header; `NT_NO_CKSUM` when the host has no `cksum`; one
+ * status per entry, in order (`<i> C <crc> <size>` | `<i> M` | `<i> U` | `<i> D` | `<i> X`); then
+ * `NT_ENV <name>=<value>` (the one environment variable the caller needs resolved on the host —
+ * printed LAST, because it is host data and must not be able to forge a status line); then `NT_END`.
+ *
+ * Missing / unreadable / gate are decided for every entry even without `cksum`: those are the
+ * refusals, and a host without a checksum tool must not lose them. An awk that fails on a block is
+ * reported as `X` through fd 3 rather than hidden behind the pipeline, whose status is `cksum`'s.
*/
export function agentToolsCheckCommand(prelude: string, entries: readonly ProbeEntry[], envName: string): string {
if (!/^[A-Z_][A-Z0-9_]*$/.test(envName)) throw new Error(`not an environment variable name: ${envName}`)
@@ -87,12 +102,15 @@ export function agentToolsCheckCommand(prelude: string, entries: readonly ProbeE
}
const fns =
`nt_s() { if [ ! -e "$2" ] && [ ! -L "$2" ]; then printf '%s M\\n' "$1"; return 1; fi; ` +
- `if [ ! -f "$2" ] || [ ! -r "$2" ]; then printf '%s U\\n' "$1"; return 1; fi; return 0; }; ` +
+ `if [ ! -f "$2" ] || [ ! -r "$2" ]; then printf '%s U\\n' "$1"; return 1; fi; ` +
+ `[ -n "$nt_k" ] && return 0; printf '%s X\\n' "$1"; return 1; }; ` +
`nt_f() { nt_s "$1" "$2" || return 0; nt_c=$(cksum < "$2") || { printf '%s U\\n' "$1"; return 0; }; ` +
`printf '%s C %s\\n' "$1" "$nt_c"; }; ` +
`nt_g() { if [ -d "$3" ]; then nt_f "$1" "$2"; else printf '%s D\\n' "$1"; fi; }; ` +
- `nt_b() { nt_s "$1" "$2" || return 0; nt_c=$(awk -v s="$3" -v e="$4" ${posixQuote(AWK_BLOCK)} "$2" | cksum) || ` +
- `{ printf '%s U\\n' "$1"; return 0; }; printf '%s C %s\\n' "$1" "$nt_c"; }; `
+ `nt_b() { nt_s "$1" "$2" || return 0; ` +
+ `nt_c=$( { { awk -v s="$3" -v e="$4" ${posixQuote(AWK_BLOCK)} "$2" || printf '%s\\n' NT_AWK_FAILED >&3; } | cksum; } 3>&1 ) || ` +
+ `{ printf '%s U\\n' "$1"; return 0; }; ` +
+ `case "$nt_c" in *NT_AWK_FAILED*) printf '%s X\\n' "$1" ;; *) printf '%s C %s\\n' "$1" "$nt_c" ;; esac; }; `
const probes = entries
.map((e, i) => {
if (e.kind === 'block') return `nt_b ${i} ${e.pathExpr} ${posixQuote(e.start)} ${posixQuote(e.end)}; `
@@ -102,7 +120,8 @@ export function agentToolsCheckCommand(prelude: string, entries: readonly ProbeE
const env = `printf 'NT_ENV %s=%s\\n' ${envName} "\${${envName}:-}"; printf '%s\\n' ${END}`
return (
`${prelude}LC_ALL=C; export LC_ALL; printf '%s\\n' ${posixQuote(HEADER)}; ` +
- `if command -v cksum >/dev/null 2>&1; then ${fns}${probes}else printf '%s\\n' NT_NO_CKSUM; fi; ${env}`
+ `nt_k=; if command -v cksum >/dev/null 2>&1; then nt_k=1; else printf '%s\\n' NT_NO_CKSUM; fi; ` +
+ `${fns}${probes}${env}`
)
}
@@ -124,22 +143,25 @@ export function parseAgentToolsReport(stdout: string, count: number): AgentTools
if (eq < 0 || eq > endAt) return null
const env = tail.slice(eq + 1, endAt)
const lines = body.slice(0, envAt).split('\n').filter((l, i, all) => !(i === all.length - 1 && l === ''))
- if (lines.length === 1 && lines[0] === 'NT_NO_CKSUM') return { kind: 'no-cksum', env }
+ const hasCksum = lines[0] !== 'NT_NO_CKSUM'
+ if (!hasCksum) lines.shift()
if (lines.length !== count) return null
const statuses: ProbeStatus[] = []
for (let i = 0; i < count; i++) {
- const m = /^(\d+) (C (.+)|M|U|D)$/.exec(lines[i])
+ const m = /^(\d+) (C (.+)|M|U|D|X)$/.exec(lines[i])
if (!m || Number(m[1]) !== i) return null
if (m[2] === 'M') statuses.push({ state: 'missing' })
else if (m[2] === 'U') statuses.push({ state: 'unreadable' })
else if (m[2] === 'D') statuses.push({ state: 'no-gate' })
+ else if (m[2] === 'X') statuses.push({ state: 'unknown' })
else {
- const sum = parseCksumLine(m[3])
+ // A host that said it has no cksum cannot have produced a checksum.
+ const sum = hasCksum ? parseCksumLine(m[3]) : null
if (!sum) return null
statuses.push({ state: 'present', sum })
}
}
- return { kind: 'report', statuses, env }
+ return { hasCksum, statuses, env }
}
// ---- cadence --------------------------------------------------------------------------------
diff --git a/src/main/remote-ssh/agent-tools-refresh.test.ts b/src/main/remote-ssh/agent-tools-refresh.test.ts
index df7cb653b..503af805d 100644
--- a/src/main/remote-ssh/agent-tools-refresh.test.ts
+++ b/src/main/remote-ssh/agent-tools-refresh.test.ts
@@ -16,7 +16,7 @@ import {
} from 'fs'
import { tmpdir } from 'os'
import path from 'path'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
import {
CONTROL_SHIM_SCRIPT,
buildCanvasControlInstructions,
@@ -29,12 +29,15 @@ import { RemoteHooks, type RemoteRunner } from './remote-hooks'
const conn = { host: 'fixture', user: 'fixture' }
let home: string
let warn: ReturnType<typeof vi.spyOn>
+let info: ReturnType<typeof vi.spyOn>
beforeEach(() => {
home = mkdtempSync(path.join(tmpdir(), "nt-refresh-' h-"))
warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
- vi.spyOn(console, 'info').mockImplementation(() => {})
+ info = vi.spyOn(console, 'info').mockImplementation(() => {})
})
+/** Did any log line claim a rewrite? It must mean a file was actually written. */
+const claimedRewrite = () => info.mock.calls.flat().some((a: unknown) => typeof a === 'string' && a.includes('rewrote'))
afterEach(() => {
vi.restoreAllMocks()
rmSync(home, { recursive: true, force: true })
@@ -141,6 +144,46 @@ describe.skipIf(process.platform === 'win32')('RemoteHooks.refreshAgentTools (re
expect(publishedTo(runner, gemini)).toBe(true)
})
+ // Measured before the fix: 41,693 → 81,279 → 120,865 → 160,451 bytes over a connect and three
+ // hourly re-checks — the merge took the stray end marker for "no block" and appended each time.
+ // Two hosts, because two halves had the bug: on a normal host the PROBE must find the block (else
+ // it reads stale every check); on a host whose awk fails every block is merged on every check,
+ // so the MERGE itself must find it.
+ it.each([
+ ['a normal host', false],
+ ['a host whose awk fails (every block merged every check)', true]
+ ])('a stray end marker left by a hand-deleted block costs ONE append, not one per check — %s', async (_n, badAwk) => {
+ await freshHost()
+ const bin = mkdtempSync(path.join(tmpdir(), 'nt-bad-awk-'))
+ try {
+ writeFileSync(path.join(bin, 'awk'), '#!/bin/sh\nexit 2\n', { mode: 0o755 })
+ const opts = badAwk ? { path: `${bin}:${process.env.PATH ?? '/usr/bin:/bin'}` } : {}
+ const codex = path.join(home, '.codex/AGENTS.md')
+ // Both of our blocks gone from the file, each leaving its end line behind.
+ let text = read(codex)
+ for (const m of ['manage-canvas', 'get-linked-context']) {
+ const start = text.indexOf(`<!-- nodeterm:${m}:start -->`)
+ const end = text.indexOf(`<!-- nodeterm:${m}:end -->`)
+ text = text.slice(0, start) + text.slice(end)
+ }
+ put(codex, `# mine\n${text}`)
+ await new RemoteHooks(hostRunner(opts)).refreshAgentTools(conn, '/fixture.sock', home, [], 'connect')
+ const size = read(codex).length
+ expect(read(codex).match(/manage-canvas:start/g)).toHaveLength(1)
+ expect(read(codex).match(/get-linked-context:start/g)).toHaveLength(1)
+ for (let i = 0; i < 2; i++) {
+ const runner = hostRunner(opts)
+ expect(await new RemoteHooks(runner).refreshAgentTools(conn, '/fixture.sock', home, [], 'connect')).toBe('current')
+ expect(read(codex).length).toBe(size)
+ expect(publishes(runner)).toHaveLength(0)
+ // On a normal host the probe agrees with the merge outright: no merge read at all.
+ if (!badAwk) expect(runner.calls).toHaveLength(1)
+ }
+ } finally {
+ rmSync(bin, { recursive: true, force: true })
+ }
+ })
+
it('writes what is missing and nothing else', async () => {
await freshHost()
rmSync(CTX())
@@ -212,6 +255,49 @@ describe.skipIf(process.platform === 'win32')('RemoteHooks.refreshAgentTools (re
await new RemoteHooks(runner).refreshAgentTools(conn, '/fixture.sock', home, [], 'connect')
expect(read(path.join(home, '.copilot/copilot-instructions.md'))).toContain('nodeterm:manage-canvas:start')
expect(read(path.join(home, 'relative-dir/copilot-instructions.md'))).toBe(current)
+
+ // The probe can never vouch for ~/.copilot under that env, so every check re-merges it — and a
+ // merge that changes nothing is NOT a rewrite: no write, no "rewrote" line, outcome current.
+ info.mockClear()
+ const again = hostRunner({ env: { COPILOT_HOME: 'relative-dir' } })
+ expect(await new RemoteHooks(again).refreshAgentTools(conn, '/fixture.sock', home, [], 'connect')).toBe('current')
+ expect(publishes(again)).toHaveLength(0)
+ expect(claimedRewrite()).toBe(false)
+ })
+
+ it('a host whose awk fails has its blocks MERGED instead (which write only on a change) — never a false rewrite', async () => {
+ await freshHost()
+ const bin = mkdtempSync(path.join(tmpdir(), 'nt-bad-awk-'))
+ try {
+ writeFileSync(path.join(bin, 'awk'), '#!/bin/sh\nexit 2\n', { mode: 0o755 })
+ info.mockClear()
+ const runner = hostRunner({ path: `${bin}:${process.env.PATH ?? '/usr/bin:/bin'}` })
+ expect(await new RemoteHooks(runner).refreshAgentTools(conn, '/fixture.sock', home, [], 'connect')).toBe('current')
+ expect(publishes(runner)).toHaveLength(0)
+ expect(claimedRewrite()).toBe(false)
+ // …and said once, so a host that never confirms by checksum is visible in the log.
+ expect(warn.mock.calls.flat().join('\n')).toMatch(/could not checksum 7 instruction block/)
+ } finally {
+ rmSync(bin, { recursive: true, force: true })
+ }
+ })
+
+ it('an account dir removed between the probe and the write is not brought back', async () => {
+ mkdirSync(accountDir('acc-1'), { recursive: true })
+ const base = hostRunner()
+ const racing: HostRunner = {
+ calls: base.calls,
+ run: async (args, stdin) => {
+ const r = await base.run(args, stdin)
+ // The probe saw the dir; it is gone before the skill write lands.
+ if (args.at(-1)!.includes('NT_AGENT_TOOLS_CHECK')) rmSync(accountDir('acc-1'), { recursive: true })
+ return r
+ }
+ }
+ await new RemoteHooks(racing).refreshAgentTools(conn, '/fixture.sock', home, ['acc-1'], 'connect')
+ expect(existsSync(accountDir('acc-1'))).toBe(false)
+ // The system files still landed: a vanished account costs only its own skills.
+ expect(read(SHIM())).toBe(CONTROL_SHIM_SCRIPT)
})
it('a probe that could not run changes nothing', async () => {
@@ -241,8 +327,9 @@ describe.skipIf(process.platform === 'win32')('RemoteHooks.refreshAgentTools (re
})
describe('a host with no cksum', () => {
+ // Every tool this machine has EXCEPT cksum — thousands of links, so built once for the block.
let bin: string
- beforeEach(() => {
+ beforeAll(() => {
bin = mkdtempSync(path.join(tmpdir(), 'nt-no-cksum-'))
for (const d of ['/usr/bin', '/bin']) {
let names: string[] = []
@@ -261,9 +348,22 @@ describe.skipIf(process.platform === 'win32')('RemoteHooks.refreshAgentTools (re
}
}
})
- afterEach(() => rmSync(bin, { recursive: true, force: true }))
+ afterAll(() => rmSync(bin, { recursive: true, force: true }))
+
+ it('still never writes into what it cannot read, and still honours the account-dir gate', async () => {
+ mkdirSync(SKILL(), { recursive: true }) // a directory where our file should be
+ mkdirSync(accountDir('acc-1'), { recursive: true })
+ const runner = hostRunner({ path: bin })
+ expect(await new RemoteHooks(runner).refreshAgentTools(conn, '/fixture.sock', home, ['acc-1', 'gone'], 'connect')).toBe(
+ 'failed'
+ )
+ expect(readdirSync(SKILL())).toEqual([])
+ expect(read(`${accountDir('acc-1')}/skills/manage-nodeterm-canvas/SKILL.md`)).toBe(buildCanvasSkillBody(SHIM()))
+ expect(existsSync(accountDir('gone'))).toBe(false)
+ expect(read(SHIM())).toBe(CONTROL_SHIM_SCRIPT)
+ })
- it('falls back to writing everything, as every connect did before the check existed', async () => {
+ it('writes what it can read without comparison, as every connect did before the check existed', async () => {
put(SHIM(), 'stale\n')
const runner = hostRunner({ path: bin })
const rh = new RemoteHooks(runner)
diff --git a/src/main/remote-ssh/remote-hooks.ts b/src/main/remote-ssh/remote-hooks.ts
index 52dcd3fba..21637e25e 100644
--- a/src/main/remote-ssh/remote-hooks.ts
+++ b/src/main/remote-ssh/remote-hooks.ts
@@ -20,7 +20,13 @@ import {
updateRemoteTextFile,
type RemoteTextResult
} from '../../core/agents/hooks/remote-settings-file'
-import { remoteAtomicWrite, runRemoteAtomicWrite, type RemoteAtomicWriteOptions } from '../remote-atomic-write'
+import {
+ REMOTE_WRITE_NO_DIR,
+ RemoteWriteError,
+ remoteAtomicWrite,
+ runRemoteAtomicWrite,
+ type RemoteAtomicWriteOptions
+} from '../remote-atomic-write'
import { curlHeaderConfigLine } from '../../core/agents/hook-curl-config-sh'
import { buildManagedScript } from '../../core/agents/hooks/managed-script'
import {
@@ -896,8 +902,13 @@ export class RemoteHooks {
*
* Fail-open for the connect, never silent: a failed owned-file write THROWS and ends its group
* (the steps after it depend on the file) with a warning naming the group; a failed instruction
- * merge is logged by the transaction and the group carries on. Returns whether everything landed.
- * `copilotHome` is asked at most once, and only when a copilot block is reached.
+ * merge is logged by the transaction and the group carries on. A gated file (a managed account's
+ * skill) is written only while its dir still exists — re-checked on the host in the write itself —
+ * and is skipped, not failed, when it is gone. `copilotHome` is asked at most once, and only when
+ * a copilot block is reached.
+ *
+ * Returns whether everything that should have landed did, and what was ACTUALLY written: a merge
+ * that changed nothing, or a gated write whose dir vanished, is not a write.
*/
private async applyAgentTools(
conn: SshConnection,
@@ -905,7 +916,7 @@ export class RemoteHooks {
remoteHome: string,
artifacts: readonly AgentToolArtifact[],
copilotHome: () => Promise<string>
- ): Promise<boolean> {
+ ): Promise<{ ok: boolean; written: AgentToolArtifact[] }> {
let copilot: Promise<string> | undefined
const groups = new Map<string, AgentToolArtifact[]>()
for (const a of artifacts) {
@@ -914,11 +925,21 @@ export class RemoteHooks {
else groups.set(a.group, [a])
}
let ok = true
+ const written: AgentToolArtifact[] = []
for (const members of groups.values()) {
try {
for (const a of members) {
if (a.kind === 'file') {
- await this.writeOwnedFile(conn, controlPath, a.path, a.body, a.mode ? { mode: a.mode } : {})
+ try {
+ await this.writeOwnedFile(conn, controlPath, a.path, a.body, {
+ ...(a.mode ? { mode: a.mode } : {}),
+ ...(a.gateDir ? { requireDir: a.gateDir } : {})
+ })
+ written.push(a)
+ } catch (e) {
+ // The account was removed between the probe and this write: nothing to keep current.
+ if (!(a.gateDir && e instanceof RemoteWriteError && e.code === REMOTE_WRITE_NO_DIR)) throw e
+ }
continue
}
const target =
@@ -927,13 +948,14 @@ export class RemoteHooks {
: this.instructionTarget(remoteHome, a.target)
const r = await this.mergeRemoteInstructions(conn, controlPath, target.pathExpr, a.block, a.merge, target.prelude)
if (r === 'failed') ok = false
+ else if (r === 'written') written.push(a)
}
} catch (e) {
ok = false
warnNotInstalled(members[0].label, e)
}
}
- return ok
+ return { ok, written }
}
/** The instruction files whose path does not depend on host state we have to ask for. codex and
@@ -956,8 +978,9 @@ export class RemoteHooks {
* One probe checksums everything the host holds (see agent-tools-freshness.ts for the stamp and
* the cadence); a current host costs that one round trip and no write. A file we cannot read is
* never written over, and a host with one is not called confirmed, so the reuse branch keeps
- * looking (on the tunnel-repair backoff). A host with no `cksum` falls back to writing everything,
- * which is what every connect did before this check existed. Never throws.
+ * looking (on the tunnel-repair backoff). On a host with no `cksum` the files it can read cannot be
+ * compared: they are written (what every connect did before this check existed) and the blocks
+ * merged, but missing, unreadable and gated files are still told apart. Never throws.
*/
async refreshAgentTools(
conn: SshConnection,
@@ -1039,15 +1062,11 @@ export class RemoteHooks {
}
if (!report) return done(false, 'failed')
const copilotHome = copilotHomeFromReported(report.env, remoteHome)
-
- if (report.kind === 'no-cksum') {
- // Nothing was probed. On a connect or repair, write everything we used to write on every
- // connect (never the gated account skills: we cannot see whether their dirs exist). On the
- // hourly re-look of a host this run already wrote, write nothing blind.
- if (trigger === 'reuse' && this.agentToolsState.get(key)?.verified?.setId === setId) return done(true, 'current')
- const system = plan.filter((a) => !(a.kind === 'file' && a.gateDir))
- const ok = await this.applyAgentTools(conn, controlPath, remoteHome, system, async () => copilotHome)
- return done(ok, ok ? 'refreshed' : 'failed')
+ // With no cksum every file the host can read is `unknown`. On a connect or a repair those are
+ // written anyway, which is what every connect did before this check; on the hourly re-look of a
+ // host this run already brought up to date, nothing is written blind.
+ if (!report.hasCksum && trigger === 'reuse' && this.agentToolsState.get(key)?.verified?.setId === setId) {
+ return done(true, 'current')
}
// The probe read copilot's file at the host's raw `$COPILOT_HOME`; the installer refuses an
@@ -1055,27 +1074,44 @@ export class RemoteHooks {
const copilotProbeTrusted = report.env === '' || isSafeRemoteCopilotHome(report.env)
const stale: AgentToolArtifact[] = []
const unreadable: AgentToolArtifact[] = []
+ let unknownBlocks = 0
plan.forEach((a, i) => {
const status = report.statuses[i]
if (status.state === 'unreadable') unreadable.push(a)
else if (status.state === 'no-gate') return
- else if (status.state === 'missing' || formatCksum(status.sum) !== expected[i]) stale.push(a)
+ else if (status.state === 'missing') stale.push(a)
+ else if (status.state === 'unknown') {
+ // An owned file is written; an instruction block is MERGED, which writes only on a change.
+ stale.push(a)
+ if (a.kind === 'block') unknownBlocks++
+ } else if (formatCksum(status.sum) !== expected[i]) stale.push(a)
else if (a.kind === 'block' && a.target === 'copilot' && !copilotProbeTrusted) stale.push(a)
})
+ if (!report.hasCksum) {
+ console.info(`[remote-hooks] ${host} has no cksum: its agent tool files are written without comparison`)
+ } else if (unknownBlocks) {
+ console.warn(
+ `[remote-hooks] could not checksum ${unknownBlocks} instruction block(s) on ${host} (awk failed or is ` +
+ 'missing); merged them instead, which writes only what changed'
+ )
+ }
if (unreadable.length) {
console.warn(
`[remote-hooks] left ${unreadable.length} agent tool file(s) on ${host} untouched because they cannot be ` +
`read (not a readable regular file): ${unreadable.map(describeArtifact).join(', ')}`
)
}
- if (!stale.length) return done(!unreadable.length, unreadable.length ? 'failed' : 'current')
- const ok = await this.applyAgentTools(conn, controlPath, remoteHome, stale, async () => copilotHome)
- console.info(
- `[remote-hooks] ${host}: ${ok ? 'rewrote' : 'tried to rewrite'} ${stale.length} out-of-date agent tool file(s): ` +
- stale.map(describeArtifact).join(', ')
- )
+ const { ok, written } = stale.length
+ ? await this.applyAgentTools(conn, controlPath, remoteHome, stale, async () => copilotHome)
+ : { ok: true, written: [] }
+ if (written.length) {
+ console.info(
+ `[remote-hooks] ${host}: rewrote ${written.length} out-of-date agent tool file(s): ` +
+ written.map(describeArtifact).join(', ')
+ )
+ }
const settled = ok && !unreadable.length
- return done(settled, settled ? 'refreshed' : 'failed')
+ return done(settled, !settled ? 'failed' : written.length ? 'refreshed' : 'current')
}
/** How the probe looks at one artifact — at the SAME path the writer uses (copilot aside: the