oh-my-opencode 4.13.0 → 4.14.1

package/packages/omo-codex/plugin/components/rules/dist/cli.js

@@ -3927,7 +3927,7 @@ function createRulesEngine(options, config = configFromEnvironment(options.env))
 }
 
 // components/rules/src/static-injection.ts
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 
 // components/rules/src/post-compact-directive.ts
 var DIRECTIVE_HEADER = [
@@ -3965,96 +3965,6 @@ function buildPostCompactReadDirective(rulePaths, maxChars) {
 `)}${DIRECTIVE_FOOTER}`;
 }
 
-// components/rules/src/sparkshell-awareness.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join7 } from "node:path";
-var SPARKSHELL_AWARENESS_MARKER = "## Sparkshell Runtime";
-var SPARKSHELL_AWARENESS_DEDUP_KEY = "__omo_sparkshell_awareness__";
-function isCodexAppServerActive(env = process.env) {
-  const originator = env["CODEX_INTERNAL_ORIGINATOR_OVERRIDE"]?.toLowerCase() ?? "";
-  const bundleIdentifier = env["__CFBundleIdentifier"]?.toLowerCase() ?? "";
-  const shellActive = isTruthy2(env["CODEX_SHELL"]);
-  return shellActive && (originator.includes("codex desktop") || originator.includes("codex app") || bundleIdentifier === "com.openai.codex");
-}
-function isSparkShellAppServerConfigured(env = process.env) {
-  const codexSocketPath = env["CODEX_APP_SERVER_SOCKET"]?.trim() ?? "";
-  const omoSocketPath = env["OMO_SPARKSHELL_APP_SERVER_SOCKET"]?.trim() ?? "";
-  return codexSocketPath.length > 0 || omoSocketPath.length > 0;
-}
-function resolveOmoInvocation(env = process.env, deps = {}) {
-  const fileExists = deps.fileExists ?? existsSync4;
-  const platform = deps.platform ?? process.platform;
-  const binNames = platform === "win32" ? ["omo.cmd", "omo.exe", "omo"] : ["omo"];
-  const pathDelimiter = platform === "win32" ? ";" : ":";
-  const pathEntries = (env["PATH"] ?? "").split(pathDelimiter).filter((entry) => entry.trim().length > 0);
-  for (const pathEntry of pathEntries) {
-    for (const binName of binNames) {
-      if (fileExists(join7(pathEntry, binName)))
-        return "omo";
-    }
-  }
-  for (const candidateDir of omoCandidateBinDirs(env)) {
-    for (const binName of binNames) {
-      const candidate = join7(candidateDir, binName);
-      if (fileExists(candidate))
-        return candidate;
-    }
-  }
-  return null;
-}
-function omoCandidateBinDirs(env) {
-  const dirs = [];
-  const localBinDir = env["CODEX_LOCAL_BIN_DIR"]?.trim() ?? "";
-  if (localBinDir.length > 0)
-    dirs.push(localBinDir);
-  const home = env["HOME"]?.trim() || env["USERPROFILE"]?.trim() || "";
-  const codexHome = env["CODEX_HOME"]?.trim() || (home.length > 0 ? join7(home, ".codex") : "");
-  if (codexHome.length > 0)
-    dirs.push(join7(codexHome, "bin"));
-  if (home.length > 0)
-    dirs.push(join7(home, ".local", "bin"));
-  return dirs;
-}
-function getSparkShellRuntimeAwareness(env = process.env, deps = {}) {
-  const override = env["OMO_SPARKSHELL_AWARENESS"] ?? env["LAZYCODEX_SPARKSHELL_AWARENESS"];
-  if (isFalsy(override)) {
-    return "";
-  }
-  if (!isTruthy2(override) && !isCodexAppServerActive(env) && !isSparkShellAppServerConfigured(env)) {
-    return "";
-  }
-  const resolved = resolveOmoInvocation(env, deps);
-  const invocation = resolved ?? (isTruthy2(override) ? "omo" : null);
-  if (invocation === null) {
-    return "";
-  }
-  const command = /\s/.test(invocation) ? `"${invocation}"` : invocation;
-  return [
-    SPARKSHELL_AWARENESS_MARKER,
-    "",
-    `- Use \`${command} sparkshell <command>\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Raw \`rg\`/\`grep\`/\`cat\`/\`git\` are fallbacks when Sparkshell is unavailable or too narrow for the task.`,
-    `- Use \`${command} sparkshell --shell '<command>'\` only for shell metacharacters or pipelines.`,
-    `- Use \`${command} sparkshell --tmux-pane <pane-id> --tail-lines 400\` only to inspect an existing pane, never to launch ordinary commands. Tail lines must stay between 100 and 1000.`,
-    "- When no native sidecar or appserver is available, Sparkshell silently falls back to raw command execution. `OMO_SPARKSHELL_BIN` selects a native sidecar path.",
-    "- When `CODEX_THREAD_ID` identifies a Codex session, Sparkshell feeds recent session context (first/latest user request + last 5 conversation messages) into oversized-output condensation for relevance ranking, but never appends that context to command output. `OMO_SPARKSHELL_SESSION_CONTEXT=0` disables the lookup.",
-    `- Route potentially huge output (full log files, big diffs, \`cat\`/\`grep\` over large artifacts) through \`${command} sparkshell\` instead of reading it raw: oversized output is condensed to a budget while preserving error signatures, repeated patterns, session-goal-relevant lines, and head/tail. Tune with \`--budget <chars>\`; disable with \`OMO_SPARKSHELL_CONDENSE=0\`.`,
-    "- Oversized output is first summarized by the spark model (`codex exec`, default `gpt-5.3-codex-spark`) fed with the shell output plus session context: the summary keeps selected output as-is (no masking) and ends with a `[sparkshell caption]` line describing what ran, what the full output contained, and which lines were omitted. `OMO_SPARKSHELL_SPARK=0` skips the model and uses deterministic condensation directly."
-  ].join(`
-`);
-}
-function isTruthy2(value) {
-  if (value === undefined) {
-    return false;
-  }
-  return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
-}
-function isFalsy(value) {
-  if (value === undefined) {
-    return false;
-  }
-  return ["0", "false", "no", "off"].includes(value.trim().toLowerCase());
-}
-
 // components/rules/src/transcript-rule-filter.ts
 function filterRulesAlreadyInTranscript(rules, transcriptPath, markInjected, options = {}) {
   if (rules.length === 0 || transcriptPath === null) {
@@ -4131,8 +4041,7 @@ function runStaticInjection(cwd, transcriptPath, eventName, cachePath, options,
   const rules = filterRulesAlreadyInTranscript(loaded.rules.filter((rule) => !engine.isStaticInjected(rule)), transcriptPath, (rule) => {
     engine.markStaticInjected(rule);
   }, transcriptSearchOptions);
-  const sparkshellAwareness = engine.state.staticDedup.has(SPARKSHELL_AWARENESS_DEDUP_KEY) ? "" : getSparkShellRuntimeAwareness(options.env);
-  if (rules.length === 0 && sparkshellAwareness.length === 0) {
+  if (rules.length === 0) {
     persistEngineState(engine, cachePath);
     return "";
   }
@@ -4140,11 +4049,8 @@ function runStaticInjection(cwd, transcriptPath, eventName, cachePath, options,
   for (const rule of rules) {
     engine.markStaticInjected(rule);
   }
-  if (sparkshellAwareness.length > 0) {
-    engine.state.staticDedup.add(SPARKSHELL_AWARENESS_DEDUP_KEY);
-  }
   persistEngineState(engine, cachePath);
-  return formatAdditionalContextOutput(eventName, combineStaticContext(block, sparkshellAwareness));
+  return formatAdditionalContextOutput(eventName, block);
 }
 function runPostCompactRecovery(input) {
   const effectiveConfig = withPostCompactBudget(input.config, {
@@ -4160,8 +4066,7 @@ function runPostCompactRecovery(input) {
     engine.markStaticInjected(rule);
   });
   const dynamicRulePaths = recoverDynamicRulePaths(engine, transcriptText, loaded.rules);
-  const sparkshellAwareness = engine.state.staticDedup.has(SPARKSHELL_AWARENESS_DEDUP_KEY) ? "" : getSparkShellRuntimeAwareness(input.options.env);
-  if (missingRules.length === 0 && dynamicRulePaths.length === 0 && sparkshellAwareness.length === 0) {
+  if (missingRules.length === 0 && dynamicRulePaths.length === 0) {
     persistEngineState(engine, input.cachePath, input.channel);
     return "";
   }
@@ -4172,11 +4077,8 @@ function runPostCompactRecovery(input) {
   for (const rule of missingRules) {
     engine.markStaticInjected(rule);
   }
-  if (sparkshellAwareness.length > 0) {
-    engine.state.staticDedup.add(SPARKSHELL_AWARENESS_DEDUP_KEY);
-  }
   persistEngineState(engine, input.cachePath, input.channel);
-  return formatAdditionalContextOutput(input.eventName, combineStaticContext(bodyBlock, directive, sparkshellAwareness));
+  return formatAdditionalContextOutput(input.eventName, combineStaticContext(bodyBlock, directive));
 }
 function readRecoveryTranscriptText(transcriptPath) {
   if (transcriptPath === null) {
@@ -4200,7 +4102,7 @@ function recoverDynamicRulePaths(engine, transcriptText, staticRules) {
       if (transcriptText !== null && transcriptText.includes(rulePath)) {
         continue;
       }
-      if (!existsSync5(rulePath)) {
+      if (!existsSync4(rulePath)) {
         continue;
       }
       recoveredPaths.add(rulePath);
@@ -4218,7 +4120,7 @@ function combineStaticContext(...blocks) {
 }
 
 // components/rules/src/tool-paths.ts
-import { existsSync as existsSync6, statSync as statSync6 } from "node:fs";
+import { existsSync as existsSync5, statSync as statSync6 } from "node:fs";
 import { isAbsolute as isAbsolute4, resolve as resolve10 } from "node:path";
 var COMMAND_TOOL_NAMES = new Set(["bash", "shell_command", "exec_command"]);
 var TRACKED_TOOL_NAMES = new Set([
@@ -4329,7 +4231,7 @@ function resolvePath(cwd, filePath) {
 }
 function isExistingFile(filePath) {
   try {
-    return existsSync6(filePath) && statSync6(filePath).isFile();
+    return existsSync5(filePath) && statSync6(filePath).isFile();
   } catch {
     return false;
   }

package/packages/omo-codex/plugin/components/rules/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-rules",
-	"version": "4.13.0",
+	"version": "4.14.1",
 	"description": "Codex plugin that injects project rule files into model context through lifecycle hooks.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/rules/src/static-injection.ts

@@ -11,7 +11,6 @@ import type { Engine } from "@oh-my-opencode/rules-engine/engine";
 import { isNeverTruncatedRule } from "@oh-my-opencode/rules-engine/engine";
 import type { LoadedRule, PiRulesConfig } from "@oh-my-opencode/rules-engine/engine";
 import { createRulesEngine } from "./rules-engine-factory.js";
-import { getSparkShellRuntimeAwareness, SPARKSHELL_AWARENESS_DEDUP_KEY } from "./sparkshell-awareness.js";
 import { filterRulesAlreadyInTranscript, filterRulesNotInTranscriptText } from "./transcript-rule-filter.js";
 import type { TranscriptSearchOptions } from "./transcript-search.js";
 import { readTranscriptSearchText } from "./transcript-search.js";
@@ -61,10 +60,7 @@ export function runStaticInjection(
 		},
 		transcriptSearchOptions,
 	);
-	const sparkshellAwareness = engine.state.staticDedup.has(SPARKSHELL_AWARENESS_DEDUP_KEY)
-		? ""
-		: getSparkShellRuntimeAwareness(options.env);
-	if (rules.length === 0 && sparkshellAwareness.length === 0) {
+	if (rules.length === 0) {
 		persistEngineState(engine, cachePath);
 		return "";
 	}
@@ -73,11 +69,8 @@ export function runStaticInjection(
 	for (const rule of rules) {
 		engine.markStaticInjected(rule);
 	}
-	if (sparkshellAwareness.length > 0) {
-		engine.state.staticDedup.add(SPARKSHELL_AWARENESS_DEDUP_KEY);
-	}
 	persistEngineState(engine, cachePath);
-	return formatAdditionalContextOutput(eventName, combineStaticContext(block, sparkshellAwareness));
+	return formatAdditionalContextOutput(eventName, block);
 }
 
 interface PostCompactRecoveryInput {
@@ -110,11 +103,8 @@ function runPostCompactRecovery(input: PostCompactRecoveryInput): string {
 		},
 	);
 	const dynamicRulePaths = recoverDynamicRulePaths(engine, transcriptText, loaded.rules);
-	const sparkshellAwareness = engine.state.staticDedup.has(SPARKSHELL_AWARENESS_DEDUP_KEY)
-		? ""
-		: getSparkShellRuntimeAwareness(input.options.env);
 
-	if (missingRules.length === 0 && dynamicRulePaths.length === 0 && sparkshellAwareness.length === 0) {
+	if (missingRules.length === 0 && dynamicRulePaths.length === 0) {
 		persistEngineState(engine, input.cachePath, input.channel);
 		return "";
 	}
@@ -129,13 +119,10 @@ function runPostCompactRecovery(input: PostCompactRecoveryInput): string {
 	for (const rule of missingRules) {
 		engine.markStaticInjected(rule);
 	}
-	if (sparkshellAwareness.length > 0) {
-		engine.state.staticDedup.add(SPARKSHELL_AWARENESS_DEDUP_KEY);
-	}
 	persistEngineState(engine, input.cachePath, input.channel);
 	return formatAdditionalContextOutput(
 		input.eventName,
-		combineStaticContext(bodyBlock, directive, sparkshellAwareness),
+		combineStaticContext(bodyBlock, directive),
 	);
 }
 

package/packages/omo-codex/plugin/components/start-work-continuation/directive.md

@@ -20,7 +20,7 @@ You are mid-flight on a Prometheus work plan; this turn is an automatic continua
 3. Follow the `start-work` skill in full. The skill is already loaded from your earlier turn — re-read its file at `packages/omo-codex/plugin/skills/start-work/SKILL.md` if you have lost context.
 4. Apply the checkbox's tier from its ledger entry, or classify it now per the start-work skill: LIGHT (default — a narrow change inside existing layers) needs one real-surface proof of the deliverable, with auxiliary surfaces first-class for CLI- or data-shaped work, and only trigger-mapped adversarial classes; HEAVY (new module/abstraction, auth/security, external integration, schema/migration, concurrency, cross-domain refactor, care signals) takes the full per-criterion regime. When unsure, take HEAVY; never downgrade.
 5. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `multi_agent_v1.spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Use `fork_context: false` unless full history is truly required. Put role and specialty instructions inside `message`.
-6. Every sub-task message MUST be self-contained, an executable assignment rather than a context handoff: start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. It must include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app.
+6. Every sub-task message MUST be self-contained, executable, not a context handoff: start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. It must include all 7 sections and a Manual-QA channel with exact invocation (`curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`) and PASS/FAIL observable, plus ultraqa classes, artifact, and cleanup receipt. Channels: HTTP (`curl -i`); tmux (`send-keys` + `capture-pane`); browser (Codex: `browser:control-in-app-browser` first unless auth/persistent profile needed; else Chrome/agent-browser); computer use.
 7. Treat every worker DoneClaim as untrusted input. Run independent AdversarialVerify before any checkbox can become FullyDone; `confirmed` is the only pass verdict, while `false-positive`, `needs-fix`, and `needs-human-review` loop back to the executor with exact feedback.
 8. Use `multi_agent_v1.wait_agent` for mailbox signals, not proof of completion — a timeout only means no new mailbox update arrived; a running child is alive. For sub-tasks likely to exceed one wait cycle, require `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. Send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` only when the child is completed without the deliverable, ack-only, or no longer running. If that followup is still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_context: false` task with the missing deliverable.
 9. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
@@ -30,17 +30,17 @@ You are mid-flight on a Prometheus work plan; this turn is an automatic continua
 
 - No production code before a failing-first proof exists: a unit test at a seam, otherwise the sub-task's Manual-QA scenario captured failing. A test that mirrors its implementation (mock-call assertions, pinned constants) is not evidence. When the change touches existing behavior, PIN it first: a baseline characterization test that passes on the unchanged code, with exact inputs, exact observable, and exact assertion. PIN → RED → GREEN → SURFACE.
 - No `--dry-run` as evidence. No "should work". No "tests pass" as completion proof.
+- TUI visual evidence MUST use the web terminal pattern when a task drives an OpenCode/Codex/terminal UI: capture the pane or run `node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --from-file <capture.txt> --evidence-dir <dir>` (or `--command` when tmux is available), then cite `terminal.png`, `terminal.txt`, and `metadata.json`.
 - No `as any` / `@ts-ignore` / `@ts-expect-error`. No deleting failing tests.
 - Probe every ultraqa adversarial class whose trigger fact holds (malformed input, prompt injection, cancel/resume, stale state, dirty worktree, hung or long commands, flaky tests, misleading success output, repeated interruptions — trigger map in the start-work skill) and capture the observable for each. A clean happy-path artifact alone is NOT a PASS when an applicable class went unprobed; record skipped classes with a one-line not-applicable reason.
-- Cleanup receipt is mandatory. Register each QA resource teardown (scripts, tmux sessions, browser contexts, PIDs, ports, containers, temp dirs) as its own todo the moment it spawns, then execute it. Leftover QA state = BLOCKED, not PASS.
+- Cleanup receipt is mandatory. Register each QA teardown (scripts, tmux, browser contexts, PIDs, ports, containers, temp dirs) as a todo when it spawns, then execute it. Leftover QA state = BLOCKED, not PASS.
 - The worktree path (if set in boulder.json) governs every file edit and command. Do not stray into the main repo.
+- PR or branch implementation/review/merge work requires a task-owned git worktree. Treat the main worktree as read-only context.
 - session_ids you write to boulder.json MUST be prefixed `codex:`. Bare ids on read are legacy `opencode:`.
 
-# Global Review and Debugging Gate
+# Final gate
 
-Before completion, run `review-work` and a `debugging` runtime audit. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, and inconclusive review lanes as failures, not progress. Record at least three debugging hypotheses and the runtime evidence that confirms or refutes each one.
-
-Do not print `ORCHESTRATION COMPLETE`. Do not create a PR, PR handoff, or branch handoff. Do not write a final completion answer until this gate passes. Always redact secrets, tokens, credentials, auth headers, cookies, env dumps, private logs, and PII from ledgers, PR bodies, and handoffs.
+Before completion, run `review-work` and a `debugging` runtime audit; inconclusive lanes fail. Do not create a PR, PR handoff, branch handoff, merge, or final completion answer until this gate passes. For PR/branch work, stay in the task-owned worktree: create/update the PR, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, then clean up. Redact secrets, tokens, credentials, auth headers, cookies, env dumps, logs, and PII.
 
 # Stop conditions for THIS turn
 

package/packages/omo-codex/plugin/components/start-work-continuation/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-start-work-continuation",
-	"version": "4.13.0",
+	"version": "4.14.1",
 	"description": "Codex Stop hook continuation injector for omo-codex start-work plans.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/start-work-continuation/test/codex-hook.test.ts

@@ -138,6 +138,29 @@ describe("start-work Stop hook", () => {
 		expect(parsed.reason.split(/\s+/).filter(Boolean).length).toBeLessThanOrEqual(1100);
 	});
 
+	it("#given active codex work #when continuation directive is emitted #then PR lifecycle stays worktree-bound", () => {
+		// given
+		const workspace = createWorkspace({
+			boulderJson: createBoulderJson({
+				sessionIds: ["codex:sess_abc"],
+				status: "active",
+				worktreePath: "/tmp/worktree",
+			}),
+			planMarkdown: ["# Plan", "", "## TODOs", "- [ ] First"].join("\n"),
+		});
+		const fs = createMemoryFs();
+
+		// when
+		const output = runStopHook(createStopInput(workspace), fs);
+
+		// then
+		const parsed = parseBlockOutput(output);
+		expect(parsed.reason).toContain("PR or branch implementation/review/merge work requires a task-owned git worktree");
+		expect(parsed.reason).toContain("Treat the main worktree as read-only context");
+		expect(parsed.reason).toContain("create/update the PR, wait for CI/review/Cubic gates, merge by default");
+		expect(parsed.reason).toContain("Do not create a PR, PR handoff, branch handoff, merge");
+	});
+
 	it("#given stop hook source #when inspected #then it remains Boulder-only without planning bootstrap logic", () => {
 		// given
 		const hook = readFileSync(new URL("../src/codex-hook.ts", import.meta.url), "utf8");

package/packages/omo-codex/plugin/components/teammode/dist/cli.js

@@ -41,25 +41,43 @@ async function runTeammodeHookCli(stdin, stdout) {
 }
 function threadTitleReminder(threadReference) {
   const id = formatIdentifier(threadReference.id);
-  return threadReference.kind === "thread" ? `THREAD ID ${id}: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.` : `PENDING WORKTREE ID ${id}: CALL codex_app.set_thread_title AS SOON AS THREAD ID EXISTS. USE THE REAL TASK/ROLE.`;
+  return threadReference.kind === "thread" ? `THREAD ID ${id}: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.` : `PENDING WORKTREE ID ${id}: WORKTREE THREAD IS NOT READY YET. DO NOT bind-thread OR SEND THE MEMBER BOOTSTRAP UNTIL A REAL THREAD ID EXISTS. THEN CALL codex_app.set_thread_title USING THE REAL TASK/ROLE.`;
 }
 function formatIdentifier(value) {
   const normalized = value.replace(/\s+/g, " ").trim();
   return normalized.length <= 200 ? normalized : `${normalized.slice(0, 197)}...`;
 }
 function extractThreadCreationReference(toolResponse) {
-  if (!isRecord(toolResponse))
+  const response = parseToolResponseRecord(toolResponse);
+  if (response === null)
     return null;
-  const threadId = toolResponse["threadId"];
+  const threadId = response["threadId"];
   if (typeof threadId === "string" && threadId.trim().length > 0) {
     return { kind: "thread", id: threadId };
   }
-  const pendingWorktreeId = toolResponse["pendingWorktreeId"];
+  const pendingWorktreeId = response["pendingWorktreeId"];
   if (typeof pendingWorktreeId === "string" && pendingWorktreeId.trim().length > 0) {
     return { kind: "pendingWorktree", id: pendingWorktreeId };
   }
   return null;
 }
+function parseToolResponseRecord(toolResponse) {
+  if (isRecord(toolResponse))
+    return toolResponse;
+  if (typeof toolResponse !== "string")
+    return null;
+  const trimmed = toolResponse.trim();
+  if (trimmed.length === 0)
+    return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return isRecord(parsed) ? parsed : null;
+  } catch (error) {
+    if (error instanceof SyntaxError)
+      return null;
+    return null;
+  }
+}
 function isPostToolUsePayload(value) {
   if (!isRecord(value))
     return false;

package/packages/omo-codex/plugin/components/teammode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sisyphuslabs/codex-teammode",
-	"version": "4.13.0",
+	"version": "4.14.1",
 	"description": "Codex team-mode hook component that keeps background thread titles descriptive after create_thread.",
 	"type": "module",
 	"private": true,

package/packages/omo-codex/plugin/components/teammode/skills/teammode/SKILL.md

@@ -68,7 +68,7 @@ node "<skill-root>/scripts/team.mjs" set-status   --team <session_id> --id A --s
 node "<skill-root>/scripts/team.mjs" worktree-add    --team <session_id> --id A [--base-branch <branch>]
 node "<skill-root>/scripts/team.mjs" worktree-remove --team <session_id> --id A [--force]
 node "<skill-root>/scripts/team.mjs" integrate       --team <session_id> [--id A]
-node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A]
+node "<skill-root>/scripts/team.mjs" archive      --team <session_id> [--id A] [--note "<...>"]
 node "<skill-root>/scripts/team.mjs" delete       --team <session_id> [--force]
 node "<skill-root>/scripts/team.mjs" status       --team <session_id>
 ```
@@ -80,6 +80,13 @@ space). `{session_id}` is the leader's Codex session id when you can pass it via
 otherwise the script generates a stable handle. Re-running `init` is a safe no-op. Every mutating
 subcommand rewrites `guide.md`, so the manual always matches the current team.
 
+Mutating subcommands take a per-team state lock before reading and rewriting `team.json`. It is
+safe to run independent `add-member`, `bind-thread`, `set-status`, `archive`, `delete`, `guide`,
+and worktree mutation commands concurrently against the same team: they serialize and each command
+reads the latest committed state before writing. If a command reports that team state is locked,
+do not treat the intended mutation as complete; retry after the named command finishes, or inspect
+`.omo/teams/{session_id}/.team.lock/owner.json` if the previous command crashed.
+
 ## Create the team and its threads
 
 1. `init` the team, then `add-member` once per member.
@@ -89,10 +96,18 @@ subcommand rewrites `guide.md`, so the manual always matches the current team.
    exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
    set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
    Use `codex_app.set_thread_title` if the title did not land at creation.
+   If Codex returns only `pendingWorktreeId`, the worktree-backed thread is not ready yet: do not
+   `bind-thread` and do not send the member bootstrap. Wait until Codex surfaces a real `threadId`
+   or the thread appears in the thread list, then set the title, bind that real id with the cwd,
+   and only then send the bootstrap.
 3. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
    trigger (printed by `add-member` / `member-prompt`) as the thread's first message. The trigger
    is short on purpose: it tells the new thread to READ its `guide.md` and `team.json` rather than
    carrying the whole protocol inline.
+4. Whenever you report, audit, reopen, or hand off a member thread, include the app deep link
+   `codex://threads/<thread_id>` next to the raw id. For example:
+   `codex://threads/019ef350-ee78-72a3-bd5e-e40cebc3d814`. Worktree-backed threads are easy to
+   lose in the sidebar without this link.
 
 Every team member is a real Codex thread created with `codex_app.create_thread` - this is strict,
 not a preference. NEVER substitute `multi_agent_v1.spawn_agent`, or any other in-process subagent,
@@ -113,8 +128,28 @@ members to the hard rules, so you mainly keep the channel open: expect frequent
 from each member - findings, `WORKING:`/`BLOCKED:` markers, peer digests - rather than one final
 dump, and act on them as they arrive. All member-to-member and member-to-leader traffic is in English;
 when the END user addresses a member, that member replies in the user's own language. Members hand off
-files and memos through the team `artifacts/` directory and reference them by path. Wait for every
-required member's final report before you declare the team done.
+files and memos through the team `artifacts/` directory and reference them by path.
+
+## Let members work - do not rush them
+
+Members heartbeat every few tool calls and message you on every finding, blocker, and finished
+slice (their manual binds them to this). So a member that is quiet between heartbeats is **working,
+not stalled** - a stretch of silence is the normal sound of focused work, not a problem to chase.
+Re-reading `codex_app.read_thread` to check on a calm member, or sending "any update?" / "are you
+done?" / "hurry up" pings, interrupts that member and slows the whole team. Trust the heartbeat and
+let them cook.
+
+Message a member only when one of these is true:
+- you have new information, context, or a correction it needs to do its slice right;
+- you are reassigning, narrowing, or unblocking its scope;
+- a peer's result changes what it should do; or
+- it has gone fully silent well past its heartbeat cadence AND that stall is blocking the team -
+  then send one specific question, not a barrage.
+
+Otherwise stay calm and keep the channel open: read inbound updates as they arrive and act on them.
+A long-running member is alive; a heartbeat you have not received yet is not a failure. Wait for
+every required member's final report before you declare the team done - rushing toward "done" while
+members are still mid-slice just produces half-built work you will have to redo.
 
 ## Worktrees - isolate members who would touch the same files
 
@@ -127,6 +162,16 @@ its own worktree. To land the work, `integrate --team <id>` merges every member
 current branch with a merge commit (never a squash or rebase); resolve any conflict it reports, then
 `worktree-remove` each worktree at cleanup.
 
+After `worktree-add`, immediately send the member a follow-up that includes both its assigned
+worktree path and its `codex://threads/<thread_id>` link. Use `bind-thread --cwd <worktree>` or
+`--worktree-path <worktree>` after the thread exists so `team.json`, `guide.md`, `status`, and
+`member-prompt` all point at the same worktree-backed thread.
+
+When the member starts inside a worktree, it must verify the assigned cwd exists and contains the
+repository checkout before editing. If the directory is missing, empty, or does not look like a git
+worktree/repository yet, the member reports `BLOCKED: worktree not ready` to the leader and waits
+instead of editing a parent checkout or an empty directory.
+
 ## Run a ulw-plan in parallel
 
 When a decision-complete plan already exists at `.omo/plans/<slug>.md` (from ulw-plan), execute its
@@ -145,12 +190,17 @@ result against that todo's acceptance criteria before you integrate.
 
 DISBAND the team the moment it is no longer needed. A team exists only to do its work; once that
 work is done, or the user no longer wants it, do not leave it lying around - archive every member,
-then delete the team state. A finished team that is never disbanded is a leak.
+then delete the team state only after archival evidence is clean or preserved. A finished team that
+is never disbanded is a leak.
 
 - `archive` closes the team: notify each active member, copy anything useful into `artifacts/`,
-  archive each member thread with `codex_app.set_thread_archived`, then `archive` flips the team
-  and all members to archived. If a thread-archive tool is unavailable, record that in the team log
-  and tell the user - never pretend a member was archived.
+  then try to archive each member thread with `codex_app.set_thread_archived`. Treat Codex App
+  failures such as "Ambiguous Codex thread id" or a thread id that is ambiguous across hosts as an
+  app-thread archival blocker, not as a team-state blocker: record the failure in the team log,
+  tell the user which member thread was not proven archived, and continue the team-state archive
+  with `archive --note "<blocker>"`. Never pretend a member thread was archived. Do not delete the
+  team state after an app-thread archival blocker unless the evidence has been copied elsewhere or
+  the user explicitly accepts that evidence loss.
 - `delete` removes `.omo/teams/{session_id}` and refuses while the team is unarchived or any member
   is still active unless `--force`.
 - When the work wraps up, land it the way the user asked: `integrate --team <id>` for a direct merge

package/packages/omo-codex/plugin/components/teammode/skills/teammode/scripts/team-guide.mjs

@@ -5,8 +5,12 @@
 // writes it once at team creation, and every member thread is told to READ it instead of
 // receiving the rules inline each turn.
 
+export function codexThreadLink(threadId) {
+	return `codex://threads/${threadId}`;
+}
+
 function memberLine(member) {
-	const thread = member.threadId ? ` | thread ${member.threadId}` : " | thread not created yet";
+	const thread = member.threadId ? ` | thread ${member.threadId} (${codexThreadLink(member.threadId)})` : " | thread not created yet";
 	const wt = member.worktree?.path ? ` | worktree ${member.worktree.path}` : "";
 	const name = member.name ? ` "${member.name}"` : "";
 	const title = member.threadTitle ? ` | thread title \`${member.threadTitle}\`` : "";
@@ -23,13 +27,23 @@ that is a coordination signal: mark yourself \`blocked\` and tell the leader at
 	}
 	const lines = team.members
 		.filter((m) => m.worktree?.path || m.worktree?.branch)
-		.map((m) => `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\``);
+		.map((m) => {
+			const thread = m.threadId ? `; thread ${codexThreadLink(m.threadId)}` : "";
+			return `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\`${thread}`;
+		});
 	return `## Worktrees (ISOLATION IS ON - this is not optional for you)
 
 This team runs each member in its own git worktree branched off \`${team.worktree.baseBranch}\`.
 **You MUST work only inside your own worktree.** The very first thing you do is \`cd\` into it;
 every edit, command, and commit happens there. Never touch another member's worktree, and
 never edit files outside your assigned scope. Commit your work so the leader can integrate it.
+Before editing, verify that your assigned worktree exists and contains repo files. If the path is
+missing, empty, or does not look like a git worktree/repository yet, send \`BLOCKED: worktree not ready\`
+to the leader and wait instead of editing any parent checkout or empty directory.
+
+If Codex returns only \`pendingWorktreeId\` while the leader is creating a worktree-backed member
+thread, the thread is not ready yet. The leader must wait until Codex surfaces a real thread id,
+then bind that real id and send the bootstrap.
 
 ${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
 }
@@ -71,6 +85,8 @@ coordinate with each other, but the leader owns the final decision and integrati
 - **Reach the leader and your peers with \`codex_app.send_message_to_thread\` - not by narrating in
   your own thread, where no one reads it.** The address book is in team.json: the leader thread id
   is \`leader.sessionId\`, and each peer thread id is its \`members[].threadId\`.
+- **When you mention a Codex thread, include its app link too:** \`codex://threads/<threadId>\`.
+  These links are the fastest way for the leader to reopen worktree-backed member threads.
 - **Push a short message at each of these moments - never batch them into one report at the end:**
   - to the **leader**: every finding or decision, every file or sub-task you finish, a
     \`WORKING: <focus> - <phase>\` heartbeat every few tool calls so you never look stale, a
@@ -78,7 +94,9 @@ coordinate with each other, but the leader owns the final decision and integrati
   - to a **peer**: the instant you learn anything that touches their slice - a shared finding, a
     changed assumption, an interface they depend on. When unsure who owns it, send it to the leader.
 - **Going quiet is the only failure.** Many small lean messages beat one end-of-work dump; keep
-  every message short.
+  every message short. Your heartbeats are what let the leader relax and leave you to work: a leader
+  who can see your progress has no reason to interrupt you, while silence forces it to break in and
+  ask where things stand. Frequent lean updates buy you uninterrupted focus.
 
 ## Artifacts (how you hand work off)
 
@@ -103,10 +121,19 @@ export function buildMemberPrompt(team, id) {
 	if (!member) throw new Error(`no member with id "${id}"`);
 	const guide = team.paths?.guide ?? ".omo/teams/<session_id>/guide.md";
 	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
-	const where = member.cwd ? `Work inside \`${member.cwd}\`.` : "Work from the repository root unless your manual assigns a worktree.";
+	const where = member.cwd
+		? `Work inside \`${member.cwd}\`.`
+		: team.worktree?.enabled
+			? "Wait for the leader to bind your worktree cwd before editing."
+			: "Work from the repository root unless your manual assigns a worktree.";
+	const threadLink = member.threadId ? `\nYour Codex thread link is ${codexThreadLink(member.threadId)}. Include it when reporting handoffs or worktree status.` : "";
+	const readiness =
+		team.worktree?.enabled
+			? "\nBefore editing, verify that your assigned worktree exists and contains repo files. If this prompt arrived before your Codex worktree checkout is ready, or the path is missing, empty, or not a git worktree/repository yet, report `BLOCKED: worktree not ready` to the leader and wait."
+			: "";
 	return `You are member ${member.id}${member.name ? ` (${member.name})` : ""} of team ${team.teamName} - owner of: ${member.focus}. Your thread title is \`${member.threadTitle}\`.
 FIRST read your field manual at \`${guide}\`, then the team state at \`${teamJson}\`; they define your scope, deliverable, the leader, the artifacts directory, and the communication rules.
-${where}
+${where}${threadLink}${readiness}
 Communicate with the team and leader in English; reply to the end user in the user's own language.
 Start now. Push updates to the leader and relevant peers with \`codex_app.send_message_to_thread\` as you work - findings, \`WORKING:\` heartbeats, and \`BLOCKED:\` the instant you stall - never just one report at the end.`;
 }