create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/agent-capabilities.js

@@ -1,5 +1,8 @@
 'use strict';
 
+// S-1 (D-4): the command-to-agent rule lives in ONE place — the UMD module shared with the client.
+const { detectAgentType } = require('../public/js/agent-command');
+
 const CONV_CLI_SURFACES = Object.freeze({
   conv: Object.freeze({ available: true, live: true, source: 'canonical-rows' }),
   cli: Object.freeze({ available: true, source: 'pty' }),
@@ -13,9 +16,26 @@ const CLI_ONLY_SURFACES = Object.freeze({
   conv: Object.freeze({ available: false, live: false, source: 'canonical-rows' }),
   cli: Object.freeze({ available: true, source: 'pty' }),
 });
+// D-4 (deepseek-harness-acp-agent-2026-10-28.html §5): an ACP agent driven over pipes has no
+// terminal UI, so its only surface is the Conversation view backed by canonical rows — the client
+// creates no xterm for it (public/js/stream-view.js gates on surfaces.cli.available).
+const CONV_ONLY_SURFACES = Object.freeze({
+  conv: Object.freeze({ available: true, live: true, source: 'canonical-rows' }),
+  cli: Object.freeze({ available: false, source: 'pty' }),
+});
+
+// WP-15 (§15.4 R-15.1): how an agent takes its INITIAL prompt. 'positional' = the CLI's own
+// initial-prompt operand (`claude [prompt]`, `codex [PROMPT]`, `gemini query`, `cursor-agent
+// [prompt...]`, C-15), which is the vendor-supported way to start a session already working.
+// 'queue' = the prompt must go through the session's own transport (walle: a real structured turn,
+// C-5). null = neither is measured to submit, so a server-started session must refuse instead of
+// silently never starting (C-8 dsh; OQ-15.1 opencode).
+const LAUNCH_PROMPT_POSITIONAL = 'positional';
+const LAUNCH_PROMPT_QUEUE = 'queue';
 
 const AGENT_CAPABILITIES = Object.freeze({
   claude: Object.freeze({
+    launchPrompt: LAUNCH_PROMPT_POSITIONAL,
     agentType: 'claude',
     providerId: 'claude-code',
     label: 'Claude Code',
@@ -36,12 +56,20 @@ const AGENT_CAPABILITIES = Object.freeze({
     steer: 'queue-interrupt', rewind: false, branch: false,
     modelControl: false, branching: false, export: true,
     promptNavigation: 'transcript',
+    // WP-1 (wheel-reader-only-where-history-exists-2026-10-28 §5 D-3/D-4): the continuous reader can
+    // only serve a provider whose history CTM owns as a transcript -- the exact set server.js's
+    // _transcriptHistoryProvider (:39540) can answer (claude, codex). Every other provider has no
+    // reader source, so its wheel-up must forward to the app instead of opening a reader that exits
+    // at once (opencode incident 2026-10-28). Flips to 'transcript' only in the same commit that
+    // teaches _transcriptHistoryProvider to return that provider.
+    historyReader: 'transcript',
     review: true,
     resume: true,
     resumeSpec: (id) => ({ cmd: 'claude', args: ['--resume', id] }),
     titleSpec: { kind: 'agentSdk', readsUserName: true, readsAiTitle: true, launchArgs: (name) => ['-n', name] },
   }),
   codex: Object.freeze({
+    launchPrompt: LAUNCH_PROMPT_POSITIONAL,
     agentType: 'codex',
     providerId: 'codex',
     label: 'Codex',
@@ -62,12 +90,15 @@ const AGENT_CAPABILITIES = Object.freeze({
     steer: 'queue-interrupt', rewind: false, branch: false,
     modelControl: false, branching: false, export: true,
     promptNavigation: 'transcript',
+    // Codex rollout lanes are a real reader source (_transcriptHistoryProvider, server.js:39540).
+    historyReader: 'transcript',
     review: true,
     resume: true,
     resumeSpec: (id) => ({ cmd: 'codex', args: ['resume', id] }),
     titleSpec: { kind: 'appServerJsonRpc', readsUserName: true, readsAiTitle: false },
   }),
   gemini: Object.freeze({
+    launchPrompt: LAUNCH_PROMPT_POSITIONAL,
     agentType: 'gemini',
     providerId: 'gemini',
     label: 'Gemini',
@@ -80,6 +111,8 @@ const AGENT_CAPABILITIES = Object.freeze({
     semanticApprovals: false,
     steer: false, rewind: false, branch: false, modelControl: false,
     promptNavigation: 'terminal',
+    // No CTM transcript / rollout rows for gemini -- the continuous reader has no source here.
+    historyReader: 'none',
     review: false,
     resume: true,
     // Resumes by provider session id, not a CTM-owned JSONL transcript, so restart-restore must
@@ -88,7 +121,49 @@ const AGENT_CAPABILITIES = Object.freeze({
     resumeSpec: (id) => ({ cmd: 'gemini', args: ['--session', id] }),
     titleSpec: null,
   }),
+  // WP-2 (D-3/D-4, §9 S-2): DeepSeek Harness is driven over the Agent Client Protocol on pipes
+  // (lib/acp/*, a later WP), never through node-pty, so it declares conv-only surfaces and ACP
+  // input/control fidelity. dsh resumes through ACP `session/resume` on attach using the stored ACP
+  // session id, and CTM's own transcript IS required (resumesWithoutTranscript:false — the session
+  // cannot be restored from the provider alone). resumeSpec is null because there is no CLI argv
+  // resume form. WP-2 only registers the id; no session can be created yet.
+  dsh: Object.freeze({
+    // WP-15 (§15.4 R-15.3, C-8): an ACP session has no ptyProcess, so no launch operand exists and
+    // the queue lane's sendFn answers `session_not_live` forever -- a server-started dsh session
+    // would never start. Declared null so callers refuse instead.
+    launchPrompt: null,
+    agentType: 'dsh',
+    providerId: 'dsh',
+    label: 'DeepSeek Harness',
+    liveStatus: true,
+    stateDetector: false,
+    structuredTranscript: true,
+    surfaces: CONV_ONLY_SURFACES,
+    semanticInput: true,
+    semanticQueue: false,
+    semanticApprovals: true,
+    inputFidelity: 'acp', controlFidelity: 'acp',
+    messages: Object.freeze({ stream: true, durable: true, branching: false }),
+    input: Object.freeze({ send: true, queue: false, interrupt: true, attachments: false }),
+    approvals: Object.freeze({ authoritative: true, resolve: true }),
+    work: Object.freeze({ phase: true, tasks: false, subagents: false }),
+    controls: Object.freeze({ model: false, cwd: false, sandbox: false }),
+    artifacts: Object.freeze({ files: true, diffs: false, tests: false }),
+    steer: 'queue-interrupt', rewind: false, branch: false,
+    modelControl: false, branching: false, export: true,
+    promptNavigation: 'transcript',
+    historyReader: 'none',
+    review: false,
+    resume: true,
+    resumeSpec: () => null,
+    resumesWithoutTranscript: false,
+    titleSpec: null,
+  }),
   opencode: Object.freeze({
+    // WP-15 (§15.4 R-15.3, OQ-15.1): `opencode --prompt` exists, but whether the TUI submits it is
+    // UNMEASURED, so it is not claimed here. Flips to `{ flag: '--prompt' }` only with a recorded
+    // PTY transcript.
+    launchPrompt: null,
     agentType: 'opencode',
     providerId: 'opencode',
     label: 'OpenCode',
@@ -111,6 +186,9 @@ const AGENT_CAPABILITIES = Object.freeze({
     steer: 'queue-interrupt', rewind: false, branch: false,
     modelControl: false, branching: false, export: true,
     promptNavigation: 'transcript',
+    // OpenCode rows land in session_message_rows (commitProviderSnapshot), never in the
+    // transcript_files/transcript_events the reader reads -- no reader source, so wheel-up forwards.
+    historyReader: 'none',
     review: true,
     resume: true,
     // OpenCode keeps history in its own SQLite db (no CTM JSONL transcript, file_size 0), and its
@@ -126,6 +204,8 @@ const AGENT_CAPABILITIES = Object.freeze({
     titleSpec: null,
   }),
   walle: Object.freeze({
+    // C-5: the queue lane delivers a real structured turn for a walle session, so it does submit.
+    launchPrompt: LAUNCH_PROMPT_QUEUE,
     agentType: 'walle',
     providerId: 'walle',
     label: 'Wall-E',
@@ -146,12 +226,16 @@ const AGENT_CAPABILITIES = Object.freeze({
     steer: true, rewind: true, branch: true,
     modelControl: true, branching: true, export: true,
     promptNavigation: 'chat',
+    // The reader serves terminal providers; Wall-E's native surface is not one.
+    historyReader: 'none',
     review: true,
     resume: false,
     resumeSpec: () => null,
     titleSpec: null,
   }),
   cursor: Object.freeze({
+    // C-15: `cursor-agent [options] [command] [prompt...]`.
+    launchPrompt: LAUNCH_PROMPT_POSITIONAL,
     agentType: 'cursor',
     providerId: 'cursor',
     label: 'Cursor',
@@ -164,6 +248,8 @@ const AGENT_CAPABILITIES = Object.freeze({
     semanticApprovals: false,
     steer: false, rewind: false, branch: false, modelControl: false,
     promptNavigation: 'terminal',
+    // Cursor chats are cloud-backed with no local transcript -- no reader source.
+    historyReader: 'none',
     review: false,
     resume: true,
     // Cursor chats are cloud-backed: there's no local transcript (JSONL/SQLite)
@@ -175,6 +261,8 @@ const AGENT_CAPABILITIES = Object.freeze({
     titleSpec: null,
   }),
   shell: Object.freeze({
+    // A plain shell has no agent to hand a prompt to.
+    launchPrompt: null,
     agentType: 'shell',
     providerId: 'shell',
     label: 'Shell',
@@ -187,6 +275,8 @@ const AGENT_CAPABILITIES = Object.freeze({
     semanticApprovals: false,
     steer: false, rewind: false, branch: false, modelControl: false,
     promptNavigation: 'terminal',
+    // A plain shell has no CTM transcript -- the reader has no source, so its wheel-up forwards.
+    historyReader: 'none',
     review: false,
     resume: false,
     resumeSpec: () => null,
@@ -194,24 +284,14 @@ const AGENT_CAPABILITIES = Object.freeze({
   }),
 });
 
-function detectAgentType(cmd) {
-  if (!cmd) return null;
-  const s = String(cmd).toLowerCase();
-  if (s.includes('claude')) return 'claude';
-  if (s.includes('codex')) return 'codex';
-  if (s.includes('gemini')) return 'gemini';
-  if (s.includes('opencode') || s.includes('open-code')) return 'opencode';
-  if (s.includes('cursor')) return 'cursor';
-  if (s === 'walle' || s.includes('wall-e') || s.includes('walle')) return 'walle';
-  return null;
-}
-
 function normalizeAgentType(value) {
   if (!value) return null;
   const s = String(value).toLowerCase().replace(/_/g, '-');
   if (AGENT_CAPABILITIES[s]) return s;
   if (s === 'claude-code') return 'claude';
   if (s === 'gemini-cli') return 'gemini';
+  // D-3/S-4: the `_`→`-` rewrite above already turns 'deepseek_harness' into this form.
+  if (s === 'deepseek-harness') return 'dsh';
   if (s === 'opencode-cli' || s === 'open-code') return 'opencode';
   if (s === 'cursor-agent' || s === 'cursor-cli') return 'cursor';
   return detectAgentType(s);
@@ -222,6 +302,19 @@ function getAgentCapabilities(value) {
   return AGENT_CAPABILITIES[type] || AGENT_CAPABILITIES.shell;
 }
 
+// WP-11 (D-20, docs/deepseek-harness-acp-agent-2026-10-28.html): the PER-SESSION form of the
+// capability record. The static `dsh` row above stays `input.attachments: false` — what a dsh session
+// can actually accept is the LIVE child's own `initialize` answer
+// (`agentCapabilities.promptCapabilities.image`, lib/acp/dsh-session-runtime.js), which is false for a
+// bridge that does not advertise image prompts. `imageInput:true` is therefore the ONLY way a dsh
+// session advertises attachments, and every other agent type is returned unchanged.
+function getSessionAgentCapabilities(value, { imageInput = false } = {}) {
+  const type = normalizeAgentType(value) || 'shell';
+  const caps = AGENT_CAPABILITIES[type] || AGENT_CAPABILITIES.shell;
+  if (type !== 'dsh') return caps;
+  return { ...caps, input: Object.freeze({ ...(caps.input || {}), attachments: imageInput === true }) };
+}
+
 function getAgentSurfaceIds(value) {
   const surfaces = getAgentCapabilities(value).surfaces || CLI_ONLY_SURFACES;
   return ['cli', 'web', 'conv'].filter((surface) => surfaces[surface]?.available === true);
@@ -251,14 +344,51 @@ function getTitleSpec(agentType) {
   return caps.titleSpec || null;
 }
 
+// WP-15 (§15.4 R-15.1, §15.5 API): the ONE place that knows how to turn (agentType, prompt) into
+// launch argv. `launchPromptMode` is the read-only query; `launchPromptArgv` is the argv builder for
+// the only mode that has an argv form.
+function launchPromptMode(agentType) {
+  const mode = getAgentCapabilities(agentType).launchPrompt;
+  return mode === LAUNCH_PROMPT_POSITIONAL || mode === LAUNCH_PROMPT_QUEUE ? mode : null;
+}
+
+function typedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// R-15.4: a prompt is only safe as a positional operand when it cannot be read as a flag or as a
+// subcommand. Never insert `--`: lib/create/resolve-launch-params.js:327 declines its approval-hook
+// injection for an argv whose terminator is not last, so a `--` here would silently drop the hook.
+function launchPromptArgv(agentType, prompt) {
+  const type = normalizeAgentType(agentType) || String(agentType == null ? '' : agentType).toLowerCase() || 'unknown';
+  if (launchPromptMode(agentType) !== LAUNCH_PROMPT_POSITIONAL) {
+    throw typedError('launch_prompt_unsupported', `${type} does not take its prompt as a launch argument`);
+  }
+  if (typeof prompt !== 'string' || prompt.trim() === '') {
+    throw typedError('prompt_not_argv_safe', 'a launch prompt must be a non-empty string');
+  }
+  if (prompt[0] === '-') {
+    throw typedError('prompt_not_argv_safe', 'a launch prompt must not start with "-" (it would parse as an option)');
+  }
+  if (!/\s/.test(prompt.trim())) {
+    throw typedError('prompt_not_argv_safe', 'a launch prompt must be more than one bare word (it could match a subcommand)');
+  }
+  return [prompt];
+}
+
 module.exports = {
   AGENT_CAPABILITIES,
   detectAgentType,
   normalizeAgentType,
   getAgentCapabilities,
+  getSessionAgentCapabilities,
   getAgentSurfaceIds,
   canResumeAgent,
   resumesWithoutTranscript,
   getResumeSpec,
   getTitleSpec,
+  launchPromptMode,
+  launchPromptArgv,
 };

package/template/coding-task-manager/lib/agent-cli-cache.js

@@ -8,7 +8,9 @@ const { definitionForCli } = require('./agent-definitions');
 const { canAutoUpgrade } = require('./agent-upgrade-planner');
 
 const CACHE_VERSION = 2;
-const DEFAULT_AGENTS = Object.freeze(['claude', 'codex', 'gemini', 'opencode', 'cursor-agent']);
+// WP-2 (S-5): the DeepSeek Harness CLI (`dsh`) joins discovery so an install is found on PATH;
+// _cliBinForAgentType maps agentType 'dsh' to the same binary name through its default fallback.
+const DEFAULT_AGENTS = Object.freeze(['claude', 'codex', 'gemini', 'opencode', 'cursor-agent', 'dsh']);
 
 function _pathHash(envPath) {
   return crypto.createHash('sha256').update(String(envPath || '')).digest('hex');
@@ -212,6 +214,29 @@ function _publicEntry(entry, envPath) {
   };
 }
 
+/**
+ * WP-13b: the definition's `installIdentity` (agent-definitions.js, the `dsh` entry) is the same
+ * rule lib/agent-version-service.js applies at version-check time (_installIdentityHolds), and it
+ * exists because the NAME is not unique on this host: homebrew ships the unrelated "Dancer's shell"
+ * as `dsh`, so a bare PATH hit would report the DeepSeek Harness as installed when it is not.
+ *
+ * An agent whose definition carries no `installIdentity` is untouched (claude/codex/opencode/gemini/
+ * cursor read exactly as before). An entry that is not `available` at all is also untouched — there
+ * is no path to judge, and "not found" stays "not found".
+ */
+function _installIdentityHolds(def, entry) {
+  if (!def || !def.installIdentity || !entry || !entry.available) return true;
+  // The realpath decides when discovery resolved one: a symlink's own path proves nothing.
+  return def.installIdentity.test(String(entry.realpath || entry.path || ''));
+}
+
+/** `_publicEntry`, plus the install-identity gate: a wrong-named binary is surfaced as unavailable. */
+function _publicEntryForAgent(agent, entry, envPath) {
+  const pub = _publicEntry(entry, envPath);
+  if (_installIdentityHolds(definitionForCli(agent), entry)) return pub;
+  return { ...pub, available: false };
+}
+
 function discoverAgent(agent, { env = process.env, now = Date.now(), extraBinDirs, preferCandidate } = {}) {
   const envPath = env.PATH || process.env.PATH || '';
   return _entryFromFingerprint(agent, _findOnPath(agent, envPath, extraBinDirs, preferCandidate), envPath, now, 'path-scan');
@@ -244,8 +269,8 @@ function getAvailableAgents({
       cache.agents[agent] = entry;
       changed = true;
     }
-    result.agents[agent] = _publicEntry(entry, envPath);
-    result[agent] = !!entry.available;
+    result.agents[agent] = _publicEntryForAgent(agent, entry, envPath);
+    result[agent] = !!result.agents[agent].available;
   }
 
   if (changed || !cache.generatedAt) {
@@ -266,8 +291,8 @@ function getCachedAvailableAgents({
   const result = { ok: true, cacheFile, generatedAt: cache.generatedAt || 0, agents: {} };
   for (const agent of agents) {
     const entry = cache.agents[agent];
-    result.agents[agent] = _publicEntry(entry, envPath);
-    result[agent] = !!entry?.available && !result.agents[agent].stale;
+    result.agents[agent] = _publicEntryForAgent(agent, entry, envPath);
+    result[agent] = !!result.agents[agent].available && !result.agents[agent].stale;
   }
   return result;
 }

package/template/coding-task-manager/lib/agent-definitions.js

@@ -55,6 +55,25 @@ const AGENT_DEFINITIONS = Object.freeze({
     // --method skips opencode's install-method detection and its interactive "Install anyways?" prompt.
     selfUpdate: { args: ['upgrade', '--method', 'curl'], label: 'opencode upgrade --method curl' },
   }),
+  // WP-12 (AC-12a): the DeepSeek Harness (`dsh`, package @deepseek-ai/dsh). No brew channel: homebrew
+  // and homebrew-cask have no formula/cask for it (brew's `dsh` is the unrelated "Dancer's shell"),
+  // which tests/agent-version-service.test.js records in its noSourceByDesign table.
+  //
+  // installIdentity is the same rule lib/hermetic-agent-launch-guard.js applies to the dsh entrypoint,
+  // and it exists for the same reason: the name `dsh` is NOT unique on this host. Path discovery finds
+  // homebrew's "Dancer's shell", so an install counts only when its realpath is inside the
+  // @deepseek-ai/dsh package; anything else reports as not installed instead of probing the wrong
+  // binary's `--version`. Enforced by lib/agent-version-service.js (_installIdentityHolds).
+  dsh: Object.freeze({
+    id: 'dsh',
+    cli: 'dsh',
+    name: 'DeepSeek Harness',
+    versionArgs: ['--version'],
+    latest: {
+      'npm-global': { kind: 'npm', package: '@deepseek-ai/dsh' },
+    },
+    installIdentity: /(?:^|\/)@deepseek-ai\/dsh\//,
+  }),
   cursor: Object.freeze({
     id: 'cursor',
     cli: 'cursor-agent',

package/template/coding-task-manager/lib/agent-hooks-codex-toml.js

@@ -10,9 +10,7 @@
 // table header, and a copy stranded under a table is migrated by migrateCodexNotify().
 
 const fs = require('fs');
-const path = require('path');
-
-const HOOK_BIN_DIR = path.join(path.resolve(__dirname, '..'), 'bin');
+const { hookShimPath } = require('./agent-hooks-shim');
 
 function parseTomlDottedKeySegments(value) {
   const src = String(value || '');
@@ -233,7 +231,17 @@ function stripCtmMarkerLines(text) {
     .join('\n');
 }
 
-const OWNS_NOTIFY = 'codex-notify.js';
+// The notify marker CTM owns, and the one predicate every ownership site uses. It matches BOTH
+// forms CTM has ever written: the legacy `…/codex-notify.js` script path in the array, and the
+// stable-shim form's quoted array element `"codex-notify"`. A quoted-element match is deliberately
+// exact, so a user notify like `["say", "codex-notify-done"]` is NOT treated as ours.
+const OWNS_NOTIFY = 'codex-notify';
+
+/** Does this TOML text (a line, or a whole file) name CTM's Codex notify? */
+function isCtmNotifyText(text) {
+  const t = String(text || '');
+  return t.includes(`${OWNS_NOTIFY}.js`) || t.includes(`"${OWNS_NOTIFY}"`);
+}
 
 /** Index of the line where a top-level key may be inserted: the first real table header, hoisted
  *  above any comment block attached directly to it. Returns lines.length when there is no table. */
@@ -257,8 +265,10 @@ function insertTopLevelKey(text, keyLine) {
   return out.join('\n');
 }
 
-function codexNotifyLine(port) {
-  return `notify = ["node", ${JSON.stringify(path.join(HOOK_BIN_DIR, OWNS_NOTIFY))}, "${port}", "stop"]`;
+/** The top-level `notify` line CTM writes. It names the per-port stable shim (`~/.walle/bin/ctm-hook-<port>`),
+ *  never a repo path, so a CTM checkout move cannot change a byte Codex hashes for hook trust. */
+function codexNotifyLine(port, { shimPath = hookShimPath(port) } = {}) {
+  return `notify = [${JSON.stringify(shimPath)}, "codex-notify", "${port}", "stop"]`;
 }
 
 /** Codex's otlp-http exporter posts to the endpoint verbatim, so it must carry the OTLP logs path. */
@@ -284,7 +294,7 @@ function stripLegacyNotifyTable(text) {
   scan.statements.forEach((s, idx) => {
     if (!isPlainTable(s, 'notify')) return;
     const body = tableBodyStatements(scan.statements, idx);
-    if (body.some((b) => stmtText(scan.lines, b).includes(OWNS_NOTIFY))) doomed.push(...body);
+    if (body.some((b) => isCtmNotifyText(stmtText(scan.lines, b)))) doomed.push(...body);
   });
   return doomed.length ? tidyTail(linesWithout(scan.lines, doomed)) : text;
 }
@@ -308,7 +318,7 @@ function codexPatchRefusal(scan) {
   for (const s of scan.statements) {
     if (s.kind === 'key' && s.table === null && s.key === 'notify') {
       if (s.end > s.start) return 'notify-multiline';
-      if (!stmtText(scan.lines, s).includes(OWNS_NOTIFY)) return 'notify-user-value';
+      if (!isCtmNotifyText(stmtText(scan.lines, s))) return 'notify-user-value';
     }
     if (s.kind === 'header' && s.header.segments[0] === 'otel' && s.header.segments[1] === 'exporter') return 'otel-exporter-subtable';
   }
@@ -322,18 +332,18 @@ function codexPatchRefusal(scan) {
  */
 const workspaceHooks = require('./agent-hooks-codex-workspace')({ scanTomlStatements, tableBodyStatements, stmtText, linesWithout });
 
-function patchCodexConfig(text, port) {
+function patchCodexConfig(text, port, { shimPath = hookShimPath(port) } = {}) {
   const input = String(text || '');
   let scan = scanTomlStatements(input);
   const refused = codexPatchRefusal(scan) || workspaceHooks.refusal(scan);
   if (refused) return { text: input, changed: false, refused };
 
-  const notifyLine = codexNotifyLine(port);
+  const notifyLine = codexNotifyLine(port, { shimPath });
   let cur = stripLegacyNotifyTable(input);
   scan = scanTomlStatements(cur);
   // A CTM-written notify stranded under [otel] is scoped otel.notify and never fires.
   const stranded = scan.statements.filter((s) => s.kind === 'key' && s.key === 'notify' && s.table === 'otel'
-    && stmtText(scan.lines, s).includes(OWNS_NOTIFY));
+    && isCtmNotifyText(stmtText(scan.lines, s)));
   if (stranded.length) cur = dropStatements(scan.lines, stranded).join('\n');
   cur = stripCtmMarkerLines(cur);
 
@@ -355,7 +365,8 @@ function patchCodexConfig(text, port) {
     lines.splice(header.end + 1, 0, exporterLine);
     cur = lines.join('\n');
   }
-  const hookCommand = `node ${JSON.stringify(path.join(HOOK_BIN_DIR, 'codex-workspace-hook.js'))} ${port} PostToolUse`;
+  // The command names the stable per-port shim, so Codex's trusted-hook hash survives a checkout move.
+  const hookCommand = `${JSON.stringify(shimPath)} codex-workspace-hook ${port} PostToolUse`;
   cur = workspaceHooks.patch(cur, port, hookCommand);
   return { text: cur, changed: cur !== input };
 }
@@ -369,7 +380,7 @@ function unpatchCodexConfig(text, port) {
   let scan = scanTomlStatements(cur);
   if (!scan.balanced) return input;
   const doomed = scan.statements.filter((s) => s.kind === 'key' && s.key === 'notify' && (s.table === null || s.table === 'otel')
-    && stmtText(scan.lines, s).includes(OWNS_NOTIFY));
+    && isCtmNotifyText(stmtText(scan.lines, s)));
   doomed.push(...scan.statements.filter((s) => s.table === 'otel' && isExporterKey(s) && stmtText(scan.lines, s).includes(`localhost:${port}`)));
   if (doomed.length) cur = dropStatements(scan.lines, doomed).join('\n');
   scan = scanTomlStatements(cur);
@@ -387,7 +398,8 @@ function unpatchCodexConfig(text, port) {
 }
 
 /**
- * Boot-prune migration: move a CTM `notify = [... codex-notify.js ...]` line stranded under a table
+ * Boot-prune migration: move a CTM `notify = [...]` line (legacy `codex-notify.js` path or the shim
+ * form's `"codex-notify"` array element) stranded under a table
  * (the live [otel] shape) to the top level. If a top-level notify already exists the stranded
  * copy is just dropped. Single-line values only (what the installer writes). Pure.
  * Returns { text, moved, removed } — `removed` lists the dropped lines for logging.
@@ -398,7 +410,7 @@ function migrateCodexNotify(text) {
   if (!scan.balanced || otelShapeRefusal(scan)) return { text: input, moved: false, removed: [] };
   const topLevelNotify = scan.statements.some((s) => s.kind === 'key' && s.table === null && s.key === 'notify');
   const doomed = scan.statements.filter((s) => s.kind === 'key' && s.key === 'notify' && s.table !== null
-    && s.end === s.start && scan.lines[s.start].includes(OWNS_NOTIFY));
+    && s.end === s.start && isCtmNotifyText(scan.lines[s.start]));
   if (!doomed.length) return { text: input, moved: false, removed: [] };
   const removed = doomed.map((s) => ({ table: s.table, line: scan.lines[s.start].trim() }));
   const cleaned = dropStatements(scan.lines, doomed).join('\n');
@@ -418,7 +430,7 @@ function backupCodexConfig(filePath) {
 }
 
 module.exports = {
-  codexExporterForm,
+  codexExporterForm, codexNotifyLine, isCtmNotifyText,
   parseTomlTableHeader, stripTomlSection, stripCtmMarkerLines,
   patchCodexConfig, unpatchCodexConfig, migrateCodexNotify, backupCodexConfig,
   scanTomlStatements,

package/template/coding-task-manager/lib/agent-hooks-codex-workspace.js

@@ -18,6 +18,14 @@ module.exports = function createCodexWorkspaceHooks({ scanTomlStatements, tableB
     return null;
   }
 
+  // CTM-owned PostToolUse hook command for <port>, in either form CTM has ever written:
+  //   legacy — node "<any checkout>/bin/codex-workspace-hook.js" <port> PostToolUse
+  //   shim   — "<home>/.walle/bin/ctm-hook-<port>" codex-workspace-hook <port> PostToolUse
+  // Ownership is the command shape (port-matched), never a filename anywhere in the text: a comment
+  // that merely names codex-workspace-hook.js is not an entry. Matching both forms is what makes the
+  // 2026-11-01 migration REPLACE the legacy group instead of duplicating it (design doc §5 D-6).
+  const OWNED_COMMAND = /^(?:node\s+(?:"[^"\n]*codex-workspace-hook\.js"|[^\s]*codex-workspace-hook\.js)|"[^"\n]*\/ctm-hook-\d+")\s+(?:codex-workspace-hook\s+)?(\d+)\s+PostToolUse$/;
+
   function remove(text, port) {
     const scan = scanTomlStatements(text);
     if (!scan.balanced) return text;
@@ -38,7 +46,7 @@ module.exports = function createCodexWorkspaceHooks({ scanTomlStatements, tableB
         const command = body.find(entry => entry.kind === 'key' && entry.key === 'command');
         const type = body.find(entry => entry.kind === 'key' && entry.key === 'type');
         const value = command && stringValue(scan.lines, command);
-        const match = typeof value === 'string' && value.match(/^node\s+(?:"[^"\n]*codex-workspace-hook\.js"|[^\s]*codex-workspace-hook\.js)\s+(\d+)\s+PostToolUse$/);
+        const match = typeof value === 'string' && value.match(OWNED_COMMAND);
         if (match && Number(match[1]) === Number(port) && type && stringValue(scan.lines, type) === 'command') {
           group.owned += 1;
           doomed.push(...body);

package/template/coding-task-manager/lib/agent-hooks-installer.js

@@ -25,7 +25,8 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { getPreset, PRESETS } = require('./agent-presets');
-const { codexExporterForm, patchCodexConfig, unpatchCodexConfig, stripTomlSection, backupCodexConfig } = require('./agent-hooks-codex-toml');
+const { codexExporterForm, isCtmNotifyText, patchCodexConfig, unpatchCodexConfig, stripTomlSection, backupCodexConfig } = require('./agent-hooks-codex-toml');
+const { hookShimPath, ensureHookShim, hookShimState, removeHookShim } = require('./agent-hooks-shim');
 const { PLUGIN_SOURCE, MANAGED_LINE } = require('./agent-hooks-opencode-plugin');
 
 const CTM_ROOT = path.resolve(__dirname, '..');
@@ -375,7 +376,8 @@ function planInstall(agent, port) {
       ...(patched.refused ? { refused: patched.refused } : {}),
       changes: [
         { description: `[otel] block → http://localhost:${port}/v1/logs (OTLP/HTTP JSON)` },
-        { description: `notify array (top-level, above the first [table]) → bin/codex-notify.js` },
+        { description: `notify array (top-level, above the first [table]) → ${hookShimPath(port)} codex-notify ${port} stop` },
+        { description: `[[hooks.PostToolUse]] command → ${hookShimPath(port)} codex-workspace-hook ${port} PostToolUse` },
       ],
     };
   }
@@ -442,9 +444,18 @@ function applyPlan(plan) {
   return { written: true, filePath: plan.filePath, bytes: plan.nextText.length };
 }
 
-/** Convenience for tests / CLI: install = plan + apply. */
-function install(agent, port) { return applyPlan(planInstall(agent, port)); }
-function uninstall(agent, port) { return applyPlan(planUninstall(agent, port)); }
+/** Convenience for tests / CLI: install = plan + apply. Codex writes its per-port shim first (a config must
+ *  never name a shim CTM could not create; a refused plan writes nothing); uninstall drops the shim. */
+function install(agent, port) {
+  const plan = planInstall(agent, port);
+  if (agent === 'codex' && !plan.refused) ensureHookShim({ port });
+  return applyPlan(plan);
+}
+function uninstall(agent, port) {
+  const result = applyPlan(planUninstall(agent, port));
+  if (agent === 'codex') removeHookShim({ port });
+  return result;
+}
 
 // ─── hookStatus: structural, never a marker ───────────────────────────────
 
@@ -483,9 +494,13 @@ function hookStatus(agent, port) {
   try {
     if (agent === 'codex') {
       const { text } = readCodexConfig();
-      // Key on our notify binary + the OTEL endpoint port (a user-owned [otel] elsewhere is no match); the path-less endpoint is stale.
-      const form = codexExporterForm(text, port);
-      return { state: !form || !text.includes('codex-notify.js') ? 'missing' : (form === 'current' ? 'installed' : 'outdated'), ...base };
+      // Plan-equality, not a shape probe (design codex-hook-stable-shim-trust-safe-self-repair-2026-11-01 D-2):
+      // `outdated` whenever the idempotent patcher would change a byte or the shim body drifted; a
+      // refusal carries `error`, which refreshOutdatedHooks never writes.
+      if (!isCtmNotifyText(text) || !codexExporterForm(text, port)) return { state: 'missing', ...base };
+      const plan = planInstall('codex', port);
+      const drift = plan.willWrite || hookShimState({ port }) !== 'current';
+      return { state: drift ? 'outdated' : 'installed', ...base, ...(plan.refused ? { error: `refused:${plan.refused}` } : {}) };
     }
     if (preset.configFormat === 'plugin') {
       const { text, managed } = readOpencodePlugin(preset);