oh-my-opencode 4.13.0 → 4.14.0

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.0",
 	"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/sparkshell-awareness.ts

@@ -81,8 +81,8 @@ export function getSparkShellRuntimeAwareness(env: RuntimeEnv = process.env, dep
 	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 <command> [args...]\` first for repo inspection, CLI smoke tests, git/history checks, and bounded command output. Pass ordinary commands as executable and arguments in separate argv tokens, for example \`${command} sparkshell rg --files\`; not \`${command} sparkshell 'rg --files'\`, because the quoted string is treated as one executable name. 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 syntax such as metacharacters, pipelines, redirects, command substitution, or variable expansion.`,
 		`- 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.",

package/packages/omo-codex/plugin/components/rules/test/sparkshell-awareness.test.ts

@@ -1,3 +1,5 @@
+// allow: SIZE_OK - rules sparkshell-awareness coverage validates one injected guidance contract; this release adds narrow prompt cases and future growth should split by guidance surface.
+
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -26,7 +28,8 @@ function normalizeGuidance(value: string): string {
 function expectSparkshellFirstContract(value: string): void {
 	const guidance = normalizeGuidance(value);
 
-	expect(guidance).toMatch(/`omo sparkshell <command>`[^.]*\bfirst\b/);
+	expect(value).toContain("`omo sparkshell <command> [args...]`");
+	expect(guidance).toMatch(/`omo sparkshell <command> \[args\.\.\.\]`[^.]*\bfirst\b/);
 	expect(guidance).toMatch(/\brepo inspection\b/);
 	expect(guidance).toMatch(/\bcli smoke tests\b/);
 	expect(guidance).toMatch(/\bgit\/history checks\b/);
@@ -34,11 +37,17 @@ function expectSparkshellFirstContract(value: string): void {
 	expect(guidance).toMatch(/\braw\b[^.]*`rg`\/`grep`\/`cat`\/`git`[^.]*\bfallbacks?\b/);
 	expect(guidance).toMatch(/\bsparkshell is unavailable\b/);
 	expect(guidance).toMatch(/\btoo narrow\b/);
+	expect(value).toContain("`omo sparkshell rg --files`");
+	expect(guidance).toMatch(/\bseparate argv tokens\b/);
+	expect(value).toContain("not `omo sparkshell 'rg --files'`");
+	expect(guidance).toMatch(/\bone executable name\b/);
 	expect(guidance).toMatch(/`omo sparkshell --shell '<command>'`[^.]*\bmetacharacters\b[^.]*\bpipelines\b/);
 	expect(guidance).toMatch(
 		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bonly\b[^.]*\binspect\b[^.]*\bexisting pane\b/,
 	);
-	expect(guidance).toMatch(/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bnever\b[^.]*\blaunch ordinary commands\b/);
+	expect(guidance).toMatch(
+		/`omo sparkshell --tmux-pane <pane-id> --tail-lines 400`[^.]*\bnever\b[^.]*\blaunch ordinary commands\b/,
+	);
 	expect(guidance).not.toMatch(/\bprefer\b[^.]*\bbefore raw shell commands\b/);
 }
 

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.0",
 	"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.0",
 	"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

@@ -89,10 +89,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 +121,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 +155,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

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.`;
 }

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

@@ -20,7 +20,7 @@ import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildGuide, buildMemberPrompt } from "./team-guide.mjs";
+import { buildGuide, buildMemberPrompt, codexThreadLink } from "./team-guide.mjs";
 import {
 	addMember,
 	archive,
@@ -164,8 +164,11 @@ const handlers = {
 		setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
 		await persist(team, dir);
 		const note = result.created ? "" : " (already exists)";
+		const thread = member.threadId
+			? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
+			: "\nMember thread is not bound yet; wait for the real Codex thread id, then bind-thread before sending bootstrap. After binding, send the member this worktree path.";
 		process.stdout.write(
-			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).\nTell that member to: cd "${result.path}"\n`,
+			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).${thread}\n`,
 		);
 	},
 
@@ -232,7 +235,8 @@ const handlers = {
 		const { team } = await loadTeam(cwd, sessionId);
 		process.stdout.write(`Team ${team.teamName} [${team.status}] - leader: main session - ${team.members.length} member(s)\n`);
 		for (const m of team.members) {
-			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${m.threadId ? ` thread=${m.threadId}` : ""}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
+			const thread = m.threadId ? ` thread=${m.threadId} link=${codexThreadLink(m.threadId)}` : "";
+			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${thread}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
 		}
 		if (isUnderstaffed(team)) {
 			process.stdout.write(

package/packages/omo-codex/plugin/components/teammode/src/codex-hook.ts

@@ -64,7 +64,7 @@ function threadTitleReminder(threadReference: ThreadCreationReference): string {
 	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.`;
+		: `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: string): string {
@@ -73,18 +73,33 @@ function formatIdentifier(value: string): string {
 }
 
 function extractThreadCreationReference(toolResponse: unknown): ThreadCreationReference | null {
-	if (!isRecord(toolResponse)) return null;
-	const threadId = toolResponse["threadId"];
+	const response = parseToolResponseRecord(toolResponse);
+	if (response === null) return null;
+	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: unknown): Record<string, unknown> | null {
+	if (isRecord(toolResponse)) return toolResponse;
+	if (typeof toolResponse !== "string") return null;
+	const trimmed = toolResponse.trim();
+	if (trimmed.length === 0) return null;
+	try {
+		const parsed: unknown = JSON.parse(trimmed);
+		return isRecord(parsed) ? parsed : null;
+	} catch (error) {
+		if (error instanceof SyntaxError) return null;
+		return null;
+	}
+}
+
 function isPostToolUsePayload(value: unknown): value is PostToolUsePayload {
 	if (!isRecord(value)) return false;
 	return (

package/packages/omo-codex/plugin/components/teammode/test/thread-title-hook.test.ts

@@ -34,6 +34,36 @@ describe("thread title PostToolUse guidance", () => {
 		);
 	});
 
+	it("#given Codex reports create_thread output as a JSON string #when the hook runs #then it still extracts the thread id", () => {
+		// given
+		const output = runPostToolUseHook({
+			hook_event_name: "PostToolUse",
+			session_id: "s-team",
+			turn_id: "t-team",
+			transcript_path: null,
+			cwd: "/repo",
+			model: "gpt-5.5",
+			permission_mode: "default",
+			tool_name: "codex_app.create_thread",
+			tool_use_id: "tool-create-thread",
+			tool_input: {
+				prompt: "Review a worktree PR",
+				target: { type: "project", projectId: "/repo", environment: { type: "local" } },
+			},
+			tool_response: '{"threadId":"019ef350-ee78-72a3-bd5e-e40cebc3d814"}',
+		});
+
+		// when
+		const parsed: unknown = JSON.parse(output);
+
+		// then
+		expect(isHookOutput(parsed)).toBe(true);
+		if (!isHookOutput(parsed)) return;
+		expect(parsed.hookSpecificOutput.additionalContext).toBe(
+			"THREAD ID 019ef350-ee78-72a3-bd5e-e40cebc3d814: CALL codex_app.set_thread_title NOW. USE THE REAL TASK/ROLE.",
+		);
+	});
+
 	it("#given an unrelated tool completed #when the hook runs #then it stays silent", () => {
 		// given
 		const output = runPostToolUseHook({
@@ -57,7 +87,7 @@ describe("thread title PostToolUse guidance", () => {
 		expect(actual).toBe("");
 	});
 
-	it("#given worktree-backed thread creation is pending #when the hook runs #then it tells Codex to title the thread once the thread id exists", () => {
+	it("#given worktree-backed thread creation is pending #when the hook runs #then it tells Codex to wait for the real thread before bootstrapping", () => {
 		// given
 		const output = runPostToolUseHook({
 			hook_event_name: "PostToolUse",
@@ -89,7 +119,7 @@ describe("thread title PostToolUse guidance", () => {
 		expect(isHookOutput(parsed)).toBe(true);
 		if (!isHookOutput(parsed)) return;
 		expect(parsed.hookSpecificOutput.additionalContext).toBe(
-			"PENDING WORKTREE ID remote-control:env:test-worktree: CALL codex_app.set_thread_title AS SOON AS THREAD ID EXISTS. USE THE REAL TASK/ROLE.",
+			"PENDING WORKTREE ID remote-control:env:test-worktree: 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.",
 		);
 	});
 });

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-telemetry",
-	"version": "4.13.0",
+	"version": "4.14.0",
 	"description": "Codex plugin component that emits omo-codex anonymous daily-active telemetry on SessionStart.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/components/ultrawork/README.md

@@ -9,7 +9,7 @@ Bundled Codex agent role TOMLs in `agents/` are installed into `CODEX_HOME/agent
 | Mandate | Behavior |
 |---|---|
 | Goal + binding success criteria | Call `create_goal` (or open with a `# Goal` block) listing the deliverable + **3+ realistic QA scenarios** (happy path, edge cases, adjacent-surface regression). Each scenario MUST name which **Manual-QA channel** it will use. "Tests pass" is supporting signal, NEVER completion proof. |
-| Manual-QA channels (TESTS ALONE NEVER PROVE DONE) | A dedicated top-level section enumerates the **four** channels you can use to verify a criterion in reality: **(1) HTTP call** (`curl -i` / Playwright APIRequestContext), **(2) tmux** (`tmux new-session` + `send-keys` + `capture-pane`), **(3) Browser use** (Playwright / puppeteer / Chromium driving the real page), **(4) Computer use** (OS-level GUI automation against the running app). Every criterion picks one channel, builds a real-usage scenario, runs it, and captures the artifact — every time. Aux surfaces (CLI stdout / DB diff / parsed config) only count for genuinely CLI- or data-shaped criteria. |
+| Manual-QA channels (TESTS ALONE NEVER PROVE DONE) | A dedicated top-level section enumerates the **four** channels you can use to verify a criterion in reality: **(1) HTTP call** (`curl -i` / Playwright APIRequestContext), **(2) tmux** (`tmux new-session` + `send-keys` + `capture-pane`), **(3) Browser use** (in Codex, `browser:control-in-app-browser` first when no authenticated/persistent browser profile is needed; otherwise Playwright / puppeteer / Chromium driving the real page), **(4) Computer use** (OS-level GUI automation against the running app). Every criterion picks one channel, builds a real-usage scenario, runs it, and captures the artifact — every time. Aux surfaces (CLI stdout / DB diff / parsed config) only count for genuinely CLI- or data-shaped criteria. |
 | Surface + paired cleanup | Execution loop step 4 (**SURFACE-AS-SCENARIO**) runs the chosen channel scenario end-to-end. Step 5 (**CLEANUP, PAIRED**) tears down every QA-spawned process / tmux session / browser context / container / port / temp dir, with a one-line receipt appended to the notepad. Leftover state → NOT done. |
 | Durable /tmp notepad | `mktemp -t ulw-$(date +%Y%m%d-%H%M%S).XXXXXX.md` with sections `Plan`, `Success criteria + QA scenarios`, `Now`, `Todo`, `Findings`, `Learnings`. **Append**, never rewrite. |
 | Obsessive atomic todos | Every action — even one-line edits, `ls`, single test runs — becomes a todo. Format: `path: <action> for <criterion> — verify by <check>`. One in_progress at a time, mark completed immediately. |

package/packages/omo-codex/plugin/components/ultrawork/agents/explorer.toml

@@ -46,7 +46,7 @@ If asked "where is auth?", explain the auth flow you found.]
 </results>
 
 # Tool strategy (parallel, flood the first wave)
-- Use `omo sparkshell <command>` first for repo-wide 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. Use `omo sparkshell --shell '<command>'` only for shell metacharacters or pipelines. Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` only to inspect an existing tmux pane, never to launch ordinary commands.
+- Use `omo sparkshell <command> [args...]` first for repo-wide inspection, CLI smoke tests, git/history checks, and bounded command output. Pass ordinary commands as executable and arguments in separate argv tokens, for example `omo sparkshell rg --files`; not `omo sparkshell 'rg --files'`, because the quoted string is treated as one executable name. Raw `rg`/`grep`/`cat`/`git` are fallbacks when Sparkshell is unavailable or too narrow. Use `omo sparkshell --shell '<command>'` only for shell syntax such as metacharacters, pipelines, redirects, command substitution, or variable expansion. Use `omo sparkshell --tmux-pane <pane-id> --tail-lines 400` only to inspect an existing tmux pane, never to launch ordinary commands.
 - Symbol questions -> `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`, `lsp_diagnostics`.
 - Structural shapes -> the `ast-grep` skill helper or `sg` CLI with `$VAR` / `$$$` metavars.
 - Text / strings / comments / logs -> `rg` (grep).

package/packages/omo-codex/plugin/components/ultrawork/agents/plan.toml

@@ -107,10 +107,10 @@ Critical path: Task 1 -> Task 2 -> Task 6
   - [ ] <verifiable condition with the exact command or assertion>
 
   QA scenarios (MANDATORY - task incomplete without these):
-  > Name the exact tool AND its exact invocation - not "verify it works". Browser use: use Chrome to drive the page; if Chrome is not available, download and use agent-browser (https://github.com/vercel-labs/agent-browser). Computer use: OS-level GUI automation for a non-browser desktop app.
+  > Name the exact tool AND its exact invocation - not "verify it works". Browser use: in Codex, use `browser:control-in-app-browser` first when available and no authenticated/persistent user browser profile is required; otherwise use Chrome to drive the page, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable. Computer use: OS-level GUI automation for a non-browser desktop app.
   ```
   Scenario: <happy path>
-    Tool:     <bash | curl | tmux | playwright(real Chrome) | agent-browser | computer-use>
+    Tool:     <bash | curl | tmux | browser:control-in-app-browser | playwright(real Chrome) | agent-browser | computer-use>
     Steps:    <exact command / API call / page action with concrete inputs - URL, payload, keystrokes, selectors>
     Expected: <concrete, binary pass/fail observable>
     Evidence: .omo/evidence/task-<N>-<slug>.<ext>

package/packages/omo-codex/plugin/components/ultrawork/directive.md

@@ -52,8 +52,10 @@ exercises the surface; capture the artifact.
   2. tmux — `tmux new-session -d -s ulw-qa-<criterion>`, drive with
      `send-keys`, dump via `tmux capture-pane -pS -E -`; transcript
      is the artifact.
-  3. Browser use — use Chrome to drive the REAL page; if Chrome is
-     not available, download and use agent-browser
+  3. Browser use — in Codex, use `browser:control-in-app-browser`
+     first when available and no authenticated/persistent user browser
+     profile is required. Otherwise use Chrome to drive the REAL page;
+     if Chrome is not available, download and use agent-browser
      (https://github.com/vercel-labs/agent-browser). Capture action
      log + screenshot path. Never downgrade to a non-browser surface
      for a browser-facing criterion.
@@ -68,7 +70,8 @@ upfront: the literal command / API call / page action with its concrete
 inputs (URL, payload, keystrokes, selectors) and the single binary
 observable that decides PASS vs FAIL. "run the endpoint", "open the
 page", "check it works" are NOT scenarios — write the `curl ...`, the
-`send-keys ...`, the `page.click(...)`, the expected status/text.
+`send-keys ...`, the Browser plugin action, the `page.click(...)`, the
+expected status/text.
 
 Auxiliary surfaces (CLI stdout / DB state diff / parsed config dump)
 are first-class evidence for CLI- or data-shaped criteria; use a
@@ -76,6 +79,14 @@ channel scenario when the behavior is user-facing. `--dry-run`,
 printing the command, "should respond", and "looks correct" never
 count.
 
+For TUI visual QA, terminal transcripts alone are not enough when a
+visual surface is being evaluated. In this repo, prefer
+`node script/qa/web-terminal-visual-qa.mjs --title "<surface>" --from-file <capture.txt> --evidence-dir <dir>`
+or the helper's `--command` tmux-backed PTY connector when available.
+Outside this repo, capture equivalent browser/computer-use rendered
+terminal evidence: screenshot, plain transcript, rendered HTML or action
+log, and cleanup receipt.
+
 # Bootstrap (DO ALL FOUR BEFORE ANY OTHER WORK — NO SKIPPING)
 
 ## 0. Survey the skills, then size the work
@@ -178,11 +189,16 @@ serialize only when one output strictly feeds the next.
   inactive/uninitialized, or cold-start unavailable, keep moving with
   Read/Grep/Glob/LSP and the ast-grep skill.
 - Repo-wide inspection, CLI smoke tests, git/history, bounded command
-  output → use `omo sparkshell <command>` first. Raw
+  output → use `omo sparkshell <command> [args...]` first. Pass ordinary
+  commands as executable and arguments in separate argv tokens, for
+  example `omo sparkshell rg --files`; not `omo sparkshell 'rg --files'`,
+  because the quoted string is treated as one executable name. Raw
   `rg`/`grep`/`cat`/`git` are fallbacks when Sparkshell is unavailable
-  or too narrow. `--shell` is only for shell metacharacters or
-  pipelines; `--tmux-pane` is only for inspecting an existing pane,
-  never for launching ordinary commands. Sparkshell is your default lens.
+  or too narrow. `--shell` is only for shell syntax such as
+  metacharacters, pipelines, redirects, command substitution, or
+  variable expansion; `--tmux-pane` is only for inspecting an existing
+  pane, never for launching ordinary commands. Sparkshell is your
+  default lens.
 - Symbols — definitions, references, rename impact, diagnostics →
   `lsp_goto_definition`, `lsp_find_references`, `lsp_symbols`,
   `lsp_diagnostics`. Use the LSP, not text search, for anything

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

@@ -80,7 +80,7 @@ function isContextPressureTranscript(transcriptPath) {
   if (transcriptPath === undefined || transcriptPath === null)
     return false;
   try {
-    return isContextPressureRecoveryPrompt(readFileSync2(transcriptPath, "utf8"));
+    return isContextPressureRecoveryPrompt(readTranscriptTail(transcriptPath));
   } catch (error) {
     if (error instanceof Error)
       return false;

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

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/codex-ultrawork",
-	"version": "4.13.0",
+	"version": "4.14.0",
 	"description": "Codex plugin that injects the ultrawork orchestration directive and ships LazyCodex planning, review, QA, and gate agent roles.",
 	"type": "module",
 	"packageManager": "npm@11.12.1",