The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
fix(cli): bind hooks from engines that post them outside their own process tree
0xken15e115b675c4ce
diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex ffb987e1b..a29b97ea6 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -48,7 +48,7 @@ import { processRows, type DiscoveredTerminalAgent } from './lib/terminalAgentDiimport { terminalActionNotStarted, type HookTerminalHint, type TerminalActionResult, type TerminalRuntimeRef } from './lib/terminalTypes.js'import { readTerminalConfigSnapshot, writeTerminalConfigSnapshot } from './lib/terminalConfigSnapshot.js'import { Watcher, type LineEvent } from './watcher/watcher.js'-import { startHookServer } from './hookServer.js'+import { chooseHookAgent, startHookServer } from './hookServer.js'import { BackendSocket } from './backendSocket.js'import { foldTranscript, lastTurnTextFromRawLines, lineToEvents, newTurnState, type LiveEvent, type TurnState } from './lib/normalize.js'import { AnalyticsCollector } from './lib/analytics/collector.js'@@ -1603,9 +1603,25 @@ async function runForeground(token: string): Promise<void> {return false}const candidates = new Map<string, RegisteredSession>()+ /**+ * Agents the hint points at whose ancestry we could NOT confirm.+ *+ * Caller ancestry is the strongest evidence and stays the first choice, but it assumes every engine+ * spawns its hook from inside its own process tree — and Cursor does not. Measured on both+ * backends: `agent` in a pane registers fine, then every one of its hooks is rejected because the+ * process that POSTs is not a descendant of the pane's engine, so no session ever binds. It is not+ * a Herdr problem; tmux fails identically.+ *+ * The pane is itself proof: the hook knew a runtime id, that runtime carries exactly one agent of+ * this engine, and the caller already had to read the 0600 hook credential to be heard at all. So+ * fall back to that, and only when it is unambiguous.+ */+ const onHintedRuntime = new Map<string, RegisteredSession>()for (const runtime of resolved) {const candidate = registry.byRuntimeEngine(runtime, engine)- if (candidate && callerBelongsTo(candidate)) candidates.set(candidate.agentId, candidate)+ if (!candidate) continue+ if (callerBelongsTo(candidate)) candidates.set(candidate.agentId, candidate)+ else onHintedRuntime.set(candidate.agentId, candidate)}// A moved Herdr pane may leave an inherited stale route. Caller/process correlation is the// deterministic fallback, but only within a configured Herdr session named by the hook.@@ -1622,7 +1638,24 @@ async function runForeground(token: string): Promise<void> {}}}- return candidates.size === 1 ? [...candidates.values()][0] : null+ const choice = chooseHookAgent([...candidates.values()], [...onHintedRuntime.values()])+ if (choice.agent) {+ if (choice.reason === 'runtime') {+ console.log(`[hooks] ${engine} hook accepted on runtime evidence alone`+ + ` · agent=${sid(choice.agent.agentId)} · caller=${callerPid} is outside that engine's process tree`)+ }+ return choice.agent+ }+ // Say WHY, once per rejected hook. "no_matching_engine_process" alone sent two people down the+ // wrong path already: the interesting question is never "did it match" but which of the three+ // gates closed — no runtime resolved from the hint, no registered agent on that runtime, or the+ // hook's own process is not a descendant of the engine we registered.+ const onRuntime = resolved.map((runtime) => registry.byRuntimeEngine(runtime, engine)).filter(Boolean)+ console.log(`[hooks] unmatched ${engine} hook · hints=${(runtimeHints ?? []).map((hint) => `${hint.backend}:${hint.paneId}`).join(',') || 'none'}`+ + ` · resolvedRuntimes=${resolved.length} · agentsOnRuntime=${onRuntime.length}`+ + ` · callerPid=${callerPid}${onRuntime.length && !candidates.size ? ' · caller is not a descendant of that engine process' : ''}`+ + `${candidates.size > 1 ? ` · ambiguous (${candidates.size} candidates)` : ''}`)+ return null},onRegistered: handleRegistered,onSessionEnd,diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.tsindex 5fe7bdbb9..e0ec6baca 100644--- a/cli/src/hookServer.spec.ts+++ b/cli/src/hookServer.spec.ts@@ -1,6 +1,6 @@import type { Server } from 'node:http'import { afterEach, describe, expect, it, vi } from 'vitest'-import { startHookServer, type HookServerHandlers } from './hookServer.js'+import { startHookServer, type HookServerHandlers, chooseHookAgent } from './hookServer.js'import { env } from './config/env.js'import { readHookCredential } from './lib/hookAuth.js'@@ -138,3 +138,24 @@ describe('process-owned hook server', () => {expect(handler).not.toHaveBeenCalled()})})++describe('chooseHookAgent', () => {+ it('prefers caller ancestry, the evidence that cannot be guessed at', () => {+ expect(chooseHookAgent(['strong'], ['weak'])).toEqual({ agent: 'strong', reason: 'ancestry' })+ })++ it('accepts the runtime alone when ancestry is unavailable and the pane is unambiguous', () => {+ // Cursor posts its hooks from outside the pane's process tree — on tmux and on Herdr alike — so+ // demanding ancestry rejected every hook it ever sent and no session bound. The pane is the proof:+ // the hook named a runtime, and that runtime carries exactly one agent of this engine.+ expect(chooseHookAgent([], ['only-agent-on-that-pane'])).toEqual({+ agent: 'only-agent-on-that-pane', reason: 'runtime',+ })+ })++ it('answers nothing rather than guessing', () => {+ expect(chooseHookAgent([], [])).toEqual({ agent: null, reason: 'none' })+ expect(chooseHookAgent([], ['a', 'b'])).toEqual({ agent: null, reason: 'ambiguous' })+ expect(chooseHookAgent(['a', 'b'], ['c'])).toEqual({ agent: null, reason: 'ambiguous' })+ })+})diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.tsindex 1c09ffefd..5ec7c6eb5 100644--- a/cli/src/hookServer.ts+++ b/cli/src/hookServer.ts@@ -20,6 +20,29 @@ import { hookCredentialMatches, loadOrCreateHookCredential } from './lib/hookAutimport type { HookTerminalHint } from './lib/terminalTypes.js'import { ENGINES, type AgentEngine } from './engines/types.js'+/**+ * Which agent does a hook belong to, given the two grades of evidence?+ *+ * Caller ancestry — the hook's process descends from the engine we registered — is the strong one and+ * always wins. It is not always available: Cursor posts its hooks from outside the pane's process tree,+ * on tmux and on Herdr alike, so requiring ancestry rejected every hook that engine ever sent and no+ * session bound at all.+ *+ * The weaker grade is the runtime itself: the hook named a pane, and that pane carries exactly one agent+ * of this engine. Accepted only when it is unambiguous, and only after the caller has already proven it+ * can read the 0600 hook credential. Two candidates is not a tie to break — it is a question we cannot+ * answer, so we answer nothing.+ */+export function chooseHookAgent<T>(byAncestry: readonly T[], byRuntimeOnly: readonly T[]): {+ agent: T | null+ reason: 'ancestry' | 'runtime' | 'ambiguous' | 'none'+} {+ if (byAncestry.length === 1) return { agent: byAncestry[0], reason: 'ancestry' }+ if (byAncestry.length > 1) return { agent: null, reason: 'ambiguous' }+ if (byRuntimeOnly.length === 1) return { agent: byRuntimeOnly[0], reason: 'runtime' }+ return { agent: null, reason: byRuntimeOnly.length ? 'ambiguous' : 'none' }+}+export interface PairOutcome {status: numberbody: Record<string, unknown>