" \\
--task-id task_SNAP
# Check for messages from the coordinator:
- orca orchestration check
+ orca orchestration check --terminal term_WORKER
=== AFTER YOU SEND worker_done ===
diff --git a/src/main/runtime/orchestration/coordinator.test.ts b/src/main/runtime/orchestration/coordinator.test.ts
index 1e94018c931..8563c3a1e87 100644
--- a/src/main/runtime/orchestration/coordinator.test.ts
+++ b/src/main/runtime/orchestration/coordinator.test.ts
@@ -76,6 +76,7 @@ function insertWorkerDone(
from?: string
dispatchId?: string
filesModified?: string[]
+ senderPaneKey?: string
}
): void {
const dispatch = db.getDispatchContext(params.taskId)
@@ -83,8 +84,9 @@ function insertWorkerDone(
if (!dispatchId) {
throw new Error(`No dispatch for task ${params.taskId}`)
}
+ const from = params.from ?? dispatch?.assignee_handle ?? 'term_unknown'
db.insertMessage({
- from: params.from ?? dispatch?.assignee_handle ?? 'term_unknown',
+ from,
to: params.to ?? 'coord',
subject: 'Done',
type: 'worker_done',
@@ -92,7 +94,10 @@ function insertWorkerDone(
taskId: params.taskId,
dispatchId,
...(params.filesModified ? { filesModified: params.filesModified } : {})
- })
+ }),
+ senderPaneKey:
+ params.senderPaneKey ??
+ (from === dispatch?.assignee_handle ? (dispatch.assignee_pane_key ?? undefined) : undefined)
})
}
@@ -595,20 +600,22 @@ describe('Coordinator', () => {
expect(db.getDispatchContextById(activeCtx.id)?.status).toBe('completed')
})
- it('accepts worker_done payload provenance after an assignee handle changes', async () => {
+ it('accepts worker_done pane provenance after an assignee handle changes', async () => {
db = new OrchestrationDb(':memory:')
const runtime = createMockRuntime()
const logs: string[] = []
const task = db.createTask({ spec: 'owned work' })
- const ctx = db.createDispatchContext(task.id, 'term_owner')
+ const leafId = '11111111-1111-4111-8111-111111111111'
+ const ctx = db.createDispatchContext(task.id, 'term_owner', `tab_before:${leafId}`)
db.insertMessage({
from: 'term_reminted',
to: 'coord',
subject: 'Done after restart',
type: 'worker_done',
- payload: JSON.stringify({ taskId: task.id, dispatchId: ctx.id })
+ payload: JSON.stringify({ taskId: task.id, dispatchId: ctx.id }),
+ senderPaneKey: `tab_after:${leafId}`
})
const coordinator = new Coordinator(db, runtime, {
@@ -622,7 +629,7 @@ describe('Coordinator', () => {
expect(result.status).toBe('completed')
expect(db.getTask(task.id)?.status).toBe('completed')
expect(db.getDispatchContextById(ctx.id)?.status).toBe('completed')
- expect(logs.some((m) => m.includes('accepting payload provenance'))).toBe(true)
+ expect(logs.some((m) => m.includes('Task') && m.includes('completed'))).toBe(true)
})
it('can be stopped', async () => {
diff --git a/src/main/runtime/orchestration/coordinator.ts b/src/main/runtime/orchestration/coordinator.ts
index e09e48942d3..73307eddd35 100644
--- a/src/main/runtime/orchestration/coordinator.ts
+++ b/src/main/runtime/orchestration/coordinator.ts
@@ -484,6 +484,7 @@ export class Coordinator {
// part of its instructions).
taskSpec: strippedSpec,
coordinatorHandle: this.opts.coordinatorHandle,
+ workerHandle: targetHandle,
devMode: process.env.ORCA_USER_DATA_PATH?.includes('orca-dev'),
// Why (§3.2): drift section fires only when behind > 0. The preamble
// builder gates on this itself; passing the object unconditionally lets
diff --git a/src/main/runtime/orchestration/db.ts b/src/main/runtime/orchestration/db.ts
index ddbdb54a0f6..80a842da530 100644
--- a/src/main/runtime/orchestration/db.ts
+++ b/src/main/runtime/orchestration/db.ts
@@ -46,6 +46,22 @@ function generateId(prefix: string): string {
return `${prefix}_${randomBytes(6).toString('hex')}`
}
+function addLifecycleRejectionMarker(payload: string | null, reason: string): string {
+ let parsed: Record = {}
+ try {
+ const value: unknown = payload ? JSON.parse(payload) : {}
+ if (value && typeof value === 'object' && !Array.isArray(value)) {
+ parsed = value as Record
+ }
+ } catch {
+ // Authority reconciliation only reaches this path with object payloads.
+ }
+ return JSON.stringify({
+ ...parsed,
+ _orcaLifecycleRejection: { code: 'sender_not_assignee', reason }
+ })
+}
+
// Why: v1 → v2 added `'heartbeat'` to messages.type CHECK + `last_heartbeat_at`
// column (preamble-hardening PR). v2 → v3 adds `delivered_at` column so
// push-on-idle can distinguish queued-but-undelivered from user-acknowledged
@@ -354,6 +370,27 @@ export class OrchestrationDb {
.all(toHandle) as MessageRow[]
}
+ convertLifecycleMessageToRejection(messageId: string, reason: string): MessageRow | undefined {
+ const message = this.getMessageById(messageId)
+ if (!message || (message.type !== 'worker_done' && message.type !== 'heartbeat')) {
+ return message
+ }
+
+ const originalBody = message.body ? `\n\nOriginal body:\n${message.body}` : ''
+ const body = `Orca rejected this ${message.type}: ${reason}${originalBody}`
+ const payload = addLifecycleRejectionMarker(message.payload, reason)
+ // Why: rejected lifecycle signals must remain auditable without reaching
+ // later read paths as actionable completion or liveness events.
+ this.db
+ .prepare(
+ `UPDATE messages
+ SET priority = 'high', subject = ?, body = ?, payload = ?
+ WHERE id = ?`
+ )
+ .run(`Rejected ${message.type}: ${message.subject}`, body, payload, messageId)
+ return this.getMessageById(messageId)
+ }
+
// Why: push-on-idle delivery must not replay messages that were already
// injected into the PTY. `read` flips only when a check-caller consumes a
// message, so delivered-but-unread rows would otherwise be re-injected on
diff --git a/src/main/runtime/orchestration/formatter.test.ts b/src/main/runtime/orchestration/formatter.test.ts
index f932aec359c..ea8ae94bc19 100644
--- a/src/main/runtime/orchestration/formatter.test.ts
+++ b/src/main/runtime/orchestration/formatter.test.ts
@@ -71,7 +71,9 @@ describe('formatMessageBanner', () => {
it('includes reply hint with message ID', () => {
const banner = formatMessageBanner(makeMessage({ id: 'msg_xyz789' }))
- expect(banner).toContain('[Reply: orca orchestration reply --id msg_xyz789 --body "..."]')
+ expect(banner).toContain(
+ '[Reply: orca orchestration reply --id msg_xyz789 --from term_coord --body "..."]'
+ )
})
it('ends with a separator line', () => {
diff --git a/src/main/runtime/orchestration/formatter.ts b/src/main/runtime/orchestration/formatter.ts
index f5526553d3b..a86f3c61edf 100644
--- a/src/main/runtime/orchestration/formatter.ts
+++ b/src/main/runtime/orchestration/formatter.ts
@@ -25,7 +25,11 @@ export function formatMessageBanner(msg: MessageRow): string {
lines.push(`[Payload: ${msg.payload}]`)
}
- lines.push(`[Reply: orca orchestration reply --id ${msg.id} --body "..."]`)
+ // Why: injected reply commands must retain the receiving pane's identity
+ // even when an older shell lacks Orca's terminal environment variables.
+ lines.push(
+ `[Reply: orca orchestration reply --id ${msg.id} --from ${msg.to_handle} --body "..."]`
+ )
lines.push(SEPARATOR)
return lines.join('\n')
diff --git a/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts b/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts
index 3ba68a67910..8fed046d421 100644
--- a/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts
+++ b/src/main/runtime/orchestration/lifecycle-reconciliation.test.ts
@@ -7,7 +7,7 @@ describe('lifecycle reconciliation', () => {
afterEach(() => db?.close())
- it('completes an active dispatch from payload IDs after its terminal handle is reminted', () => {
+ it('rejects handle churn when neither side has stable pane identity', () => {
db = new OrchestrationDb(':memory:')
const task = db.createTask({ spec: 'work' })
const dispatch = db.createDispatchContext(task.id, 'term_before_restart')
@@ -20,14 +20,13 @@ describe('lifecycle reconciliation', () => {
payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
})
- expect(reconcileLifecycleMessage(db, message, (line) => logs.push(line))).toEqual({
- action: 'completed',
- taskId: task.id,
- dispatchId: dispatch.id
+ expect(reconcileLifecycleMessage(db, message, (line) => logs.push(line))).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
})
- expect(db.getTask(task.id)?.status).toBe('completed')
- expect(db.getDispatchContextById(dispatch.id)?.status).toBe('completed')
- expect(logs.some((line) => line.includes('accepting payload provenance'))).toBe(true)
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ expect(db.getDispatchContextById(dispatch.id)?.status).toBe('dispatched')
+ expect(logs.some((line) => line.includes('expected handle'))).toBe(true)
})
// Real leaf UUIDs: pane keys are `${tabId}:${leafUuid}` and only the leaf
@@ -71,7 +70,7 @@ describe('lifecycle reconciliation', () => {
expect(db.getTask(task.id)?.status).toBe('completed')
})
- it('completes worker_done when a pane key is unparseable (legacy format)', () => {
+ it('rejects mismatched opaque pane keys instead of treating them as legacy', () => {
db = new OrchestrationDb(':memory:')
const task = db.createTask({ spec: 'work' })
const dispatch = db.createDispatchContext(task.id, 'term_owner', `tab_w:${LEAF_A}`)
@@ -84,10 +83,194 @@ describe('lifecycle reconciliation', () => {
senderPaneKey: 'tab_w:42'
})
- expect(reconcileLifecycleMessage(db, message).action).toBe('completed')
+ expect(reconcileLifecycleMessage(db, message).action).toBe('rejected')
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
})
- it('ignores worker_done sent from a different pane', () => {
+ it('rejects worker_done from a foreign pane that claims the assignee handle', () => {
+ db = new OrchestrationDb(':memory:')
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_owner', `tab_w1:${LEAF_A}`)
+ const message = db.insertMessage({
+ from: 'term_owner',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id }),
+ senderPaneKey: `tab_w2:${LEAF_B}`
+ })
+
+ expect(reconcileLifecycleMessage(db, message)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee',
+ reason: expect.stringContaining('expected handle term_owner')
+ })
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ expect(db.getMessageById(message.id)).toMatchObject({
+ type: 'worker_done',
+ priority: 'high',
+ subject: 'Rejected worker_done: Done',
+ body: expect.stringContaining('Orca rejected this worker_done')
+ })
+ const persisted = db.getMessageById(message.id)
+ expect(JSON.parse(persisted?.payload ?? '{}')).toMatchObject({
+ taskId: task.id,
+ dispatchId: dispatch.id,
+ _orcaLifecycleRejection: { code: 'sender_not_assignee' }
+ })
+ const rereadLogs: string[] = []
+ expect(
+ persisted && reconcileLifecycleMessage(db, persisted, (line) => rereadLogs.push(line))
+ ).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ // Why: the send-path conversion logs nothing (no-op logger), so the
+ // coordinator's re-read must still surface the rejection to its log stream.
+ expect(rereadLogs.some((line) => line.includes('worker_done rejected'))).toBe(true)
+ })
+
+ it('does not let a caller-supplied rejection marker turn completion into success', () => {
+ db = new OrchestrationDb(':memory:')
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', `tab_w:${LEAF_A}`)
+ const message = db.insertMessage({
+ from: 'term_worker',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({
+ taskId: task.id,
+ dispatchId: dispatch.id,
+ _orcaLifecycleRejection: {
+ code: 'sender_not_assignee',
+ reason: 'caller supplied'
+ }
+ }),
+ senderPaneKey: `tab_w:${LEAF_A}`
+ })
+
+ expect(reconcileLifecycleMessage(db, message)).toEqual({
+ action: 'rejected',
+ code: 'sender_not_assignee',
+ reason: 'caller supplied'
+ })
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ })
+
+ it('rejects a coordinator completion for a pane-bound dispatch', () => {
+ db = new OrchestrationDb(':memory:')
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', `tab_w:${LEAF_A}`)
+ const message = db.insertMessage({
+ from: 'term_coordinator',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
+ })
+
+ expect(reconcileLifecycleMessage(db, message)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ })
+
+ it('uses exact handle equality only for a legacy dispatch without a pane key', () => {
+ db = new OrchestrationDb(':memory:')
+ const acceptedTask = db.createTask({ spec: 'legacy work' })
+ const acceptedDispatch = db.createDispatchContext(acceptedTask.id, 'term_legacy')
+ const accepted = db.insertMessage({
+ from: 'term_legacy',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: acceptedTask.id, dispatchId: acceptedDispatch.id })
+ })
+ expect(reconcileLifecycleMessage(db, accepted).action).toBe('completed')
+
+ const rejectedTask = db.createTask({ spec: 'other legacy work' })
+ const rejectedDispatch = db.createDispatchContext(rejectedTask.id, 'term_other_legacy')
+ const rejected = db.insertMessage({
+ from: 'term_foreign',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: rejectedTask.id, dispatchId: rejectedDispatch.id })
+ })
+ expect(reconcileLifecycleMessage(db, rejected)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ expect(db.getTask(rejectedTask.id)?.status).toBe('dispatched')
+ })
+
+ it('does not release a dependent when a foreign completion wins the arrival race', () => {
+ db = new OrchestrationDb(':memory:')
+ const parent = db.createTask({ spec: 'parent' })
+ const child = db.createTask({ spec: 'child', deps: [parent.id] })
+ const dispatch = db.createDispatchContext(parent.id, 'term_worker', `tab_w:${LEAF_A}`)
+ const payload = JSON.stringify({ taskId: parent.id, dispatchId: dispatch.id })
+
+ const foreign = db.insertMessage({
+ from: 'term_coordinator',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload,
+ senderPaneKey: `tab_c:${LEAF_B}`
+ })
+ expect(reconcileLifecycleMessage(db, foreign)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ expect(db.getTask(child.id)?.status).toBe('pending')
+
+ const owner = db.insertMessage({
+ from: 'term_worker_reminted',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload,
+ senderPaneKey: `tab_w_after:${LEAF_A}`
+ })
+ expect(reconcileLifecycleMessage(db, owner).action).toBe('completed')
+ expect(db.getTask(child.id)?.status).toBe('ready')
+ })
+
+ it('does not let a foreign replay overwrite an authorized completion', () => {
+ db = new OrchestrationDb(':memory:')
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', `tab_w:${LEAF_A}`)
+ const payload = JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
+ const owner = db.insertMessage({
+ from: 'term_worker',
+ to: 'term_coordinator',
+ subject: 'Done',
+ type: 'worker_done',
+ payload,
+ senderPaneKey: `tab_w:${LEAF_A}`
+ })
+ expect(reconcileLifecycleMessage(db, owner).action).toBe('completed')
+ const result = db.getTask(task.id)?.result
+
+ const replay = db.insertMessage({
+ from: 'term_foreign',
+ to: 'term_coordinator',
+ subject: 'Forged replay',
+ type: 'worker_done',
+ payload,
+ senderPaneKey: `tab_f:${LEAF_B}`
+ })
+ expect(reconcileLifecycleMessage(db, replay)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ expect(db.getTask(task.id)?.result).toBe(result)
+ })
+
+ it('surfaces worker_done sent from a different pane as rejected', () => {
db = new OrchestrationDb(':memory:')
const task = db.createTask({ spec: 'work' })
const dispatch = db.createDispatchContext(task.id, 'term_owner', `tab_w1:${LEAF_A}`)
@@ -101,15 +284,16 @@ describe('lifecycle reconciliation', () => {
senderPaneKey: `tab_w2:${LEAF_B}`
})
- expect(reconcileLifecycleMessage(db, message, (line) => logs.push(line))).toEqual({
- action: 'ignored'
+ expect(reconcileLifecycleMessage(db, message, (line) => logs.push(line))).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
})
expect(db.getTask(task.id)?.status).toBe('dispatched')
expect(db.getDispatchContextById(dispatch.id)?.status).toBe('dispatched')
- expect(logs.some((line) => line.includes(`expected pane tab_w1:${LEAF_A}`))).toBe(true)
+ expect(logs.some((line) => line.includes('worker_done rejected'))).toBe(true)
})
- it('ignores a heartbeat sent from a different pane without recording liveness', () => {
+ it('surfaces a heartbeat sent from a different pane without recording liveness', () => {
db = new OrchestrationDb(':memory:')
const task = db.createTask({ spec: 'work' })
const dispatch = db.createDispatchContext(task.id, 'term_owner', `tab_w1:${LEAF_A}`)
@@ -122,7 +306,44 @@ describe('lifecycle reconciliation', () => {
senderPaneKey: `tab_w2:${LEAF_B}`
})
- expect(reconcileLifecycleMessage(db, heartbeat)).toEqual({ action: 'ignored' })
+ expect(reconcileLifecycleMessage(db, heartbeat)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
+ expect(db.getDispatchContextById(dispatch.id)?.last_heartbeat_at).toBeNull()
+ expect(db.getMessageById(heartbeat.id)).toMatchObject({
+ type: 'heartbeat',
+ subject: 'Rejected heartbeat: alive'
+ })
+ // Why: the coordinator's re-read of the already-converted heartbeat must
+ // still log the rejection, since the send-path conversion logged nothing.
+ const persisted = db.getMessageById(heartbeat.id)
+ const rereadLogs: string[] = []
+ expect(
+ persisted && reconcileLifecycleMessage(db, persisted, (line) => rereadLogs.push(line))
+ ).toMatchObject({
+ action: 'rejected'
+ })
+ expect(rereadLogs.some((line) => line.includes('Heartbeat rejected'))).toBe(true)
+ })
+
+ it('surfaces a foreign heartbeat that claims the assignee handle', () => {
+ db = new OrchestrationDb(':memory:')
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_owner', `tab_w1:${LEAF_A}`)
+ const heartbeat = db.insertMessage({
+ from: 'term_owner',
+ to: 'term_coordinator',
+ subject: 'alive',
+ type: 'heartbeat',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id }),
+ senderPaneKey: `tab_w2:${LEAF_B}`
+ })
+
+ expect(reconcileLifecycleMessage(db, heartbeat)).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee'
+ })
expect(db.getDispatchContextById(dispatch.id)?.last_heartbeat_at).toBeNull()
})
diff --git a/src/main/runtime/orchestration/lifecycle-reconciliation.ts b/src/main/runtime/orchestration/lifecycle-reconciliation.ts
index d784840a28c..96917babaf6 100644
--- a/src/main/runtime/orchestration/lifecycle-reconciliation.ts
+++ b/src/main/runtime/orchestration/lifecycle-reconciliation.ts
@@ -2,17 +2,29 @@ import type { OrchestrationDb } from './db'
import type { MessageRow } from './types'
import { parsePaneKey } from '../../../shared/stable-pane-id'
-// Why: the tab half of a pane key changes when a pane is broken out into its
-// own tab, so only the leaf UUID is identity. Reject only when both keys
-// parse and name different leaves; an unparseable (e.g. legacy numeric) key
-// degrades to payload authority rather than stranding a completion.
-function isForeignPane(assigneePaneKey: string, senderPaneKey: string): boolean {
+// Why: the tab half can change on pane break-out, while opaque legacy keys
+// have no safe equivalence beyond exact equality.
+function isSamePane(assigneePaneKey: string, senderPaneKey: string): boolean {
if (assigneePaneKey === senderPaneKey) {
- return false
+ return true
}
const assigneeLeaf = parsePaneKey(assigneePaneKey)?.leafId
const senderLeaf = parsePaneKey(senderPaneKey)?.leafId
- return Boolean(assigneeLeaf && senderLeaf && assigneeLeaf !== senderLeaf)
+ return Boolean(assigneeLeaf && senderLeaf && assigneeLeaf === senderLeaf)
+}
+
+function hasLifecycleAuthority(
+ dispatch: { assignee_handle: string | null; assignee_pane_key: string | null },
+ msg: MessageRow
+): boolean {
+ if (dispatch.assignee_pane_key) {
+ return Boolean(
+ msg.sender_pane_key && isSamePane(dispatch.assignee_pane_key, msg.sender_pane_key)
+ )
+ }
+ // Why: rows created before pane identity existed can only use the exact
+ // handle recorded at dispatch; payload knowledge alone is not authority.
+ return dispatch.assignee_handle === msg.from_handle
}
export type LifecycleReconciliationResult =
@@ -21,9 +33,16 @@ export type LifecycleReconciliationResult =
// read); senders must not wake waiters for it, unlike `ignored` rows that
// stay unread and still need delivery.
| { action: 'suppressed' }
+ | LifecycleRejectionResult
| { action: 'completed'; taskId: string; dispatchId: string }
| { action: 'heartbeat_recorded'; dispatchId: string }
+export type LifecycleRejectionResult = {
+ action: 'rejected'
+ code: 'sender_not_assignee'
+ reason: string
+}
+
type LogFn = (msg: string) => void
const noopLog: LogFn = () => {}
@@ -42,6 +61,27 @@ function parseObjectPayload(msg: MessageRow, onInvalidJson: () => void): Record<
}
}
+function getPersistedLifecycleRejection(
+ payload: Record
+): LifecycleRejectionResult | undefined {
+ const rejection = payload._orcaLifecycleRejection
+ if (
+ !rejection ||
+ typeof rejection !== 'object' ||
+ (rejection as { code?: unknown }).code !== 'sender_not_assignee' ||
+ typeof (rejection as { reason?: unknown }).reason !== 'string'
+ ) {
+ return undefined
+ }
+ // Why: the marker is reserved persistence state; treating it as a rejection
+ // also prevents caller-supplied markers from turning lifecycle sends into success.
+ return {
+ action: 'rejected',
+ code: 'sender_not_assignee',
+ reason: (rejection as { reason: string }).reason
+ }
+}
+
export function reconcileLifecycleMessage(
db: OrchestrationDb,
msg: MessageRow,
@@ -75,6 +115,13 @@ function reconcileHeartbeatMessage(
const payload = parseObjectPayload(msg, () => {
onLog(`Heartbeat from ${msg.from_handle} has invalid JSON payload; ignored`)
})
+ const persistedRejection = getPersistedLifecycleRejection(payload)
+ if (persistedRejection) {
+ // Why: the send-path reconcile converts with a no-op logger, so the
+ // coordinator's re-read is the only chance to surface the rejection.
+ onLog(`Heartbeat rejected: ${persistedRejection.reason}`)
+ return persistedRejection
+ }
const dispatchId = payload.dispatchId
if (typeof dispatchId !== 'string' || dispatchId.length === 0) {
onLog(`Heartbeat from ${msg.from_handle} missing dispatchId; ignored`)
@@ -90,17 +137,13 @@ function reconcileHeartbeatMessage(
return { action: 'suppressed' }
}
- if (
- dispatch.assignee_pane_key &&
- msg.sender_pane_key &&
- isForeignPane(dispatch.assignee_pane_key, msg.sender_pane_key)
- ) {
+ if (!hasLifecycleAuthority(dispatch, msg)) {
// Why: a wrong-pane heartbeat must not refresh liveness — it would mask
// a hung assignee behind another agent's timer.
- onLog(
- `Heartbeat for dispatch ${dispatchId} came from pane ${msg.sender_pane_key}, expected pane ${dispatch.assignee_pane_key}; ignored`
- )
- return { action: 'ignored' }
+ const reason = buildLifecycleAuthorityRejectionReason(dispatchId, dispatch, msg)
+ onLog(`Heartbeat rejected: ${reason}`)
+ db.convertLifecycleMessageToRejection(msg.id, reason)
+ return { action: 'rejected', code: 'sender_not_assignee', reason }
}
// Why: dispatchId-specific writes let the DB ignore late heartbeats for
@@ -119,6 +162,13 @@ function reconcileWorkerDoneMessage(
const payload = parseObjectPayload(msg, () => {
onLog(`Warning: invalid payload in worker_done from ${msg.from_handle}`)
})
+ const persistedRejection = getPersistedLifecycleRejection(payload)
+ if (persistedRejection) {
+ // Why: the send-path reconcile converts with a no-op logger, so the
+ // coordinator's re-read is the only chance to surface the rejection.
+ onLog(`Warning: worker_done rejected: ${persistedRejection.reason}`)
+ return persistedRejection
+ }
const taskId = payload.taskId
if (typeof taskId !== 'string' || taskId.length === 0) {
@@ -151,26 +201,11 @@ function reconcileWorkerDoneMessage(
)
return { action: 'ignored' }
}
- if (dispatch.assignee_handle !== msg.from_handle) {
- // Why: pane leaves are the remint-stable identity behind handles. When
- // both sides carry one, a foreign leaf is a different pane completing
- // someone else's task — reject it; the same leaf is the same pane after
- // a handle remint or tab break-out. Without pane data (older CLI,
- // sessions without ORCA_PANE_KEY) payload IDs stay the completion
- // authority.
- if (
- dispatch.assignee_pane_key &&
- msg.sender_pane_key &&
- isForeignPane(dispatch.assignee_pane_key, msg.sender_pane_key)
- ) {
- onLog(
- `Warning: worker_done for dispatch ${dispatchId} came from pane ${msg.sender_pane_key}, expected pane ${dispatch.assignee_pane_key}; ignored`
- )
- return { action: 'ignored' }
- }
- onLog(
- `Warning: worker_done for dispatch ${dispatchId} came from ${msg.from_handle}, expected ${dispatch.assignee_handle ?? ''}; accepting payload provenance`
- )
+ if (!hasLifecycleAuthority(dispatch, msg)) {
+ const reason = buildLifecycleAuthorityRejectionReason(dispatchId, dispatch, msg)
+ onLog(`Warning: worker_done rejected: ${reason}`)
+ db.convertLifecycleMessageToRejection(msg.id, reason)
+ return { action: 'rejected', code: 'sender_not_assignee', reason }
}
// Why: `orchestration.send` can release the DB lock before waking the
// coordinator; the later coordinator read still needs to observe completion.
@@ -204,6 +239,18 @@ function reconcileWorkerDoneMessage(
return { action: 'completed', taskId, dispatchId }
}
+function buildLifecycleAuthorityRejectionReason(
+ dispatchId: string,
+ dispatch: { assignee_handle: string | null; assignee_pane_key: string | null },
+ msg: MessageRow
+): string {
+ return (
+ `dispatch ${dispatchId} expected handle ${dispatch.assignee_handle ?? ''}, ` +
+ `pane ${dispatch.assignee_pane_key ?? ''}; received handle ${msg.from_handle}, ` +
+ `pane ${msg.sender_pane_key ?? ''}`
+ )
+}
+
function suppressEarlierHeartbeats(
db: OrchestrationDb,
workerDone: MessageRow,
diff --git a/src/main/runtime/orchestration/preamble.test.ts b/src/main/runtime/orchestration/preamble.test.ts
index 23fac4843ab..198437e4cd7 100644
--- a/src/main/runtime/orchestration/preamble.test.ts
+++ b/src/main/runtime/orchestration/preamble.test.ts
@@ -8,6 +8,7 @@ function baseParams(overrides: Partial[
dispatchId: 'ctx_def456',
taskSpec: 'Implement the login form',
coordinatorHandle: 'term_coord',
+ workerHandle: 'term_worker',
...overrides
}
}
@@ -46,6 +47,7 @@ describe('buildDispatchPreamble', () => {
expect(result).toContain('--dispatch-id ctx_def456')
expect(result).toContain('--files-modified "path/a,path/b"')
expect(result).toContain('--report-path ""')
+ expect(result).toMatch(/orchestration send --to term_coord --from term_worker/)
})
it(
@@ -83,11 +85,12 @@ describe('buildDispatchPreamble', () => {
expect(result).toContain('--task-id task_abc123')
expect(result).toContain('--dispatch-id ctx_def456')
expect(result).toContain('--phase ""')
+ expect(result).toMatch(/orchestration send --to term_coord --from term_worker/)
})
it('includes ask block with BEHAVIOR RULE #1 forbidding AskUserQuestion', () => {
const result = buildDispatchPreamble(baseParams())
- expect(result).toContain('orchestration ask')
+ expect(result).toMatch(/orchestration ask --to term_coord --from term_worker/)
expect(result).toContain('--question')
expect(result).toContain('--timeout-ms 600000')
// Why: the exact phrase is asserted so the rule can't be trimmed away by
@@ -103,6 +106,16 @@ describe('buildDispatchPreamble', () => {
expect(occurrences).toBe(3)
})
+ it('binds every injected worker command to the dispatched terminal', () => {
+ const result = buildDispatchPreamble(baseParams())
+
+ expect(result).toMatch(/orchestration ask --to term_coord --from term_worker/)
+ expect(result).toMatch(
+ /orchestration send --to term_coord --from term_worker \\\n --type escalation/
+ )
+ expect(result).toContain('orchestration check --terminal term_worker')
+ })
+
it('tells prompt-returning workers to idle without post-done polling', () => {
const result = buildDispatchPreamble(baseParams())
const section = afterWorkerDoneSection(result)
@@ -168,6 +181,7 @@ describe('buildDispatchPreamble', () => {
dispatchId: 'ctx_x',
taskSpec: 'do stuff',
coordinatorHandle: 'term_c',
+ workerHandle: 'term_w',
baseDrift: {
base: 'origin/main',
behind: 7,
@@ -190,6 +204,7 @@ describe('buildDispatchPreamble', () => {
dispatchId: 'ctx_x',
taskSpec: 'do stuff',
coordinatorHandle: 'term_c',
+ workerHandle: 'term_w',
baseDrift: {
base: 'origin/main',
behind: 0,
@@ -206,7 +221,8 @@ describe('buildDispatchPreamble', () => {
taskId: 'task_x',
dispatchId: 'ctx_x',
taskSpec: 'do stuff',
- coordinatorHandle: 'term_c'
+ coordinatorHandle: 'term_c',
+ workerHandle: 'term_w'
})
expect(result).not.toContain('--- BASE DRIFT ---')
@@ -219,6 +235,7 @@ describe('buildDispatchPreamble', () => {
dispatchId: 'ctx_x',
taskSpec: 'do stuff',
coordinatorHandle: 'term_c',
+ workerHandle: 'term_w',
baseDrift: {
base: 'origin/main',
behind: 3,
@@ -241,7 +258,8 @@ describe('buildDispatchPreamble', () => {
taskId: 'task_SNAP',
dispatchId: 'ctx_SNAP',
taskSpec: 'TASK_BODY',
- coordinatorHandle: 'term_COORD'
+ coordinatorHandle: 'term_COORD',
+ workerHandle: 'term_WORKER'
})
expect(result).toMatchSnapshot()
})
diff --git a/src/main/runtime/orchestration/preamble.ts b/src/main/runtime/orchestration/preamble.ts
index fdee65505e5..9aaa488318f 100644
--- a/src/main/runtime/orchestration/preamble.ts
+++ b/src/main/runtime/orchestration/preamble.ts
@@ -8,6 +8,7 @@ export type PreambleParams = {
dispatchId: string
taskSpec: string
coordinatorHandle: string
+ workerHandle: string
devMode?: boolean
// Why: populated by the coordinator's dispatch pre-flight (§3.1) only
// when the target worktree is behind its tracking remote. When absent
@@ -68,7 +69,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
# with subject like "Failed: " — never silently exit.
# Include BOTH taskId and dispatchId in the payload so a late completion
# from a failed retry cannot complete the current dispatch.
- ${cli} orchestration send --to ${params.coordinatorHandle} \\
+ ${cli} orchestration send --to ${params.coordinatorHandle} --from ${params.workerHandle} \\
--type worker_done --subject "" \\
--body "<3-sentence summary: what you did, what you found, what's left>" \\
--task-id ${params.taskId} --dispatch-id ${params.dispatchId} \\
@@ -85,7 +86,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
# attributes the heartbeat to the specific dispatch context, not just
# the task, so a straggler heartbeat from a previously-failed dispatch
# cannot mask a hung retry.
- ${cli} orchestration send --to ${params.coordinatorHandle} \\
+ ${cli} orchestration send --to ${params.coordinatorHandle} --from ${params.workerHandle} \\
--type heartbeat --subject "alive" \\
--task-id ${params.taskId} --dispatch-id ${params.dispatchId} \\
--phase ""
@@ -102,20 +103,20 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
# blocks on \`check --wait\` until the coordinator replies, then prints the
# reply body. Use it anywhere you would otherwise have reached for
# AskUserQuestion.
- ${cli} orchestration ask --to ${params.coordinatorHandle} \\
+ ${cli} orchestration ask --to ${params.coordinatorHandle} --from ${params.workerHandle} \\
--question "" \\
--options "" \\
--timeout-ms 600000
# Escalate a blocker or failure (pre-completion, when you need the
# coordinator to do something before you can continue):
- ${cli} orchestration send --to ${params.coordinatorHandle} \\
+ ${cli} orchestration send --to ${params.coordinatorHandle} --from ${params.workerHandle} \\
--type escalation --subject "Blocked: " \\
--body "
" \\
--task-id ${params.taskId}
# Check for messages from the coordinator:
- ${cli} orchestration check
+ ${cli} orchestration check --terminal ${params.workerHandle}
${postDoneInstructions}`
diff --git a/src/main/runtime/rpc/methods/orchestration.test.ts b/src/main/runtime/rpc/methods/orchestration.test.ts
index cf0c722c675..fc7536c2e4f 100644
--- a/src/main/runtime/rpc/methods/orchestration.test.ts
+++ b/src/main/runtime/rpc/methods/orchestration.test.ts
@@ -105,6 +105,100 @@ describe('orchestration RPC methods', () => {
expect(db.getMessageById(result.message.id)?.sender_pane_key).toBe('tab_a:leaf_a')
})
+ it('recovers missing sender pane identity from the resolved handle', async () => {
+ setup()
+ vi.spyOn(runtime, 'getTerminalPaneKey').mockReturnValue('tab_worker:leaf_worker')
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+
+ const result = (await call('orchestration.send', {
+ from: 'term_worker',
+ to: 'term_coord',
+ subject: 'hello'
+ })) as { message: { id: string } }
+
+ expect(runtime.getTerminalPaneKey).toHaveBeenCalledWith('term_worker')
+ expect(db.getMessageById(result.message.id)?.sender_pane_key).toBe('tab_worker:leaf_worker')
+ })
+
+ it('completes an identity-less injected send through its explicit worker handle', async () => {
+ setup()
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', 'tab_worker:leaf_worker')
+ vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) =>
+ handle === 'term_worker' ? 'tab_worker:leaf_worker' : null
+ )
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+
+ await call('orchestration.send', {
+ from: 'term_worker',
+ to: 'term_coord',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
+ })
+
+ expect(db.getTask(task.id)?.status).toBe('completed')
+ expect(db.getDispatchContextById(dispatch.id)?.status).toBe('completed')
+ })
+
+ it('rejects an identity-less lifecycle send resolved through the coordinator handle', async () => {
+ setup()
+ const task = db.createTask({ spec: 'work' })
+ const dependent = db.createTask({ spec: 'dependent', deps: [task.id] })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', 'tab_worker:leaf_worker')
+ vi.spyOn(runtime, 'getTerminalPaneKey').mockImplementation((handle) =>
+ handle === 'term_coord' ? 'tab_coord:leaf_coord' : null
+ )
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+
+ await call('orchestration.send', {
+ from: 'term_coord',
+ to: 'term_coord',
+ subject: 'Done',
+ type: 'worker_done',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
+ })
+
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ expect(db.getTask(dependent.id)?.status).toBe('pending')
+ })
+
+ it('does not replace a foreign sender pane with its claimed assignee handle pane', async () => {
+ setup()
+ const task = db.createTask({ spec: 'work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_worker', 'tab_worker:leaf_worker')
+ vi.spyOn(runtime, 'getTerminalPaneKey').mockReturnValue('tab_worker:leaf_worker')
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+ vi.spyOn(runtime, 'notifyMessageArrived').mockImplementation(() => {})
+
+ const result = (await call('orchestration.send', {
+ from: 'term_worker',
+ to: 'term_coord',
+ subject: 'Done',
+ type: 'worker_done',
+ senderPaneKey: 'tab_foreign:leaf_foreign',
+ payload: JSON.stringify({ taskId: task.id, dispatchId: dispatch.id })
+ })) as {
+ message: { id: string; type: string; subject: string }
+ lifecycle: { action: string; code: string; reason: string }
+ }
+
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ expect(result.lifecycle).toMatchObject({
+ action: 'rejected',
+ code: 'sender_not_assignee',
+ reason: expect.stringContaining('expected handle term_worker')
+ })
+ expect(result.message).toMatchObject({
+ type: 'worker_done',
+ subject: 'Rejected worker_done: Done'
+ })
+ expect(db.getUnreadMessages('term_coord')).toEqual([
+ expect.objectContaining({ id: result.message.id, type: 'worker_done' })
+ ])
+ expect(runtime.notifyMessageArrived).toHaveBeenCalledWith('term_coord', 'worker_done')
+ })
+
it('does not wake waiters for a heartbeat suppressed at send time', async () => {
setup()
const task = db.createTask({ spec: 'work' })
@@ -512,9 +606,9 @@ describe('orchestration RPC methods', () => {
})
describe('orchestration.check', () => {
- function createDispatchedTask(assigneeHandle = 'term_worker') {
+ function createDispatchedTask(assigneeHandle = 'term_worker', assigneePaneKey?: string) {
const task = db.createTask({ spec: 'manual check work' })
- const dispatch = db.createDispatchContext(task.id, assigneeHandle)
+ const dispatch = db.createDispatchContext(task.id, assigneeHandle, assigneePaneKey)
return { task, dispatch }
}
@@ -524,6 +618,7 @@ describe('orchestration RPC methods', () => {
taskId?: string
dispatchId?: string
filesModified?: string[]
+ senderPaneKey?: string
}): void {
const payload: Record = {}
if (params.taskId !== undefined) {
@@ -541,7 +636,8 @@ describe('orchestration RPC methods', () => {
to: params.to ?? 'term_coord',
subject: 'Done',
type: 'worker_done',
- payload: JSON.stringify(payload)
+ payload: JSON.stringify(payload),
+ senderPaneKey: params.senderPaneKey
})
}
@@ -670,11 +766,13 @@ describe('orchestration RPC methods', () => {
it('completes worker_done by payload IDs when the sender handle changed', async () => {
setup()
- const { task, dispatch } = createDispatchedTask('term_owner')
+ const leafId = '11111111-1111-4111-8111-111111111111'
+ const { task, dispatch } = createDispatchedTask('term_owner', `tab_before:${leafId}`)
insertWorkerDone({
from: 'term_reminted',
taskId: task.id,
- dispatchId: dispatch.id
+ dispatchId: dispatch.id,
+ senderPaneKey: `tab_after:${leafId}`
})
const result = (await call('orchestration.check', {
@@ -710,6 +808,34 @@ describe('orchestration RPC methods', () => {
expect(db.getDispatchContextById(activeDispatch.id)?.status).toBe('dispatched')
})
+ it('returns a persisted foreign completion as a rejection diagnostic', async () => {
+ setup()
+ const { task, dispatch } = createDispatchedTask('term_worker', 'tab_worker:leaf_worker')
+ insertWorkerDone({
+ from: 'term_foreign',
+ taskId: task.id,
+ dispatchId: dispatch.id,
+ senderPaneKey: 'tab_foreign:leaf_foreign'
+ })
+
+ const result = (await call('orchestration.check', {
+ terminal: 'term_coord',
+ types: 'worker_done'
+ })) as { count: number; messages: { type: string; subject: string; body: string }[] }
+
+ expect(result).toMatchObject({
+ count: 1,
+ messages: [
+ {
+ type: 'worker_done',
+ subject: 'Rejected worker_done: Done',
+ body: expect.stringContaining('expected handle term_worker')
+ }
+ ]
+ })
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ })
+
it('records heartbeat returned by unread manual check', async () => {
setup()
const { task, dispatch } = createDispatchedTask()
diff --git a/src/main/runtime/rpc/methods/orchestration.ts b/src/main/runtime/rpc/methods/orchestration.ts
index 597ae99b7fb..9caaf1ac57a 100644
--- a/src/main/runtime/rpc/methods/orchestration.ts
+++ b/src/main/runtime/rpc/methods/orchestration.ts
@@ -209,6 +209,9 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
handler: async (params, { runtime }) => {
const db = runtime.getOrchestrationDb()
const from = params.from ?? 'unknown'
+ // Why: older live shells may lack ORCA_PANE_KEY, but the runtime still
+ // knows the pane behind their resolved handle; persist that authority.
+ const senderPaneKey = params.senderPaneKey ?? runtime.getTerminalPaneKey(from) ?? undefined
if (!isGroupAddress(params.to)) {
// Point-to-point — existing single-recipient behavior
@@ -221,7 +224,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
priority: params.priority as MessagePriority,
threadId: params.threadId,
payload: params.payload,
- senderPaneKey: params.senderPaneKey
+ senderPaneKey
})
// Why: worker_done/heartbeat sent via `send` must release the dispatch
// lock before waking recipients — a coordinator woken by delivery may
@@ -234,6 +237,12 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
if (reconciled.action === 'suppressed') {
return { message: msg }
}
+ if (reconciled.action === 'rejected') {
+ const rejection = db.getMessageById(msg.id) ?? msg
+ runtime.deliverPendingMessagesForHandle(params.to)
+ runtime.notifyMessageArrived(params.to, rejection.type)
+ return { message: rejection, lifecycle: reconciled }
+ }
}
runtime.deliverPendingMessagesForHandle(params.to)
runtime.notifyMessageArrived(params.to, msg.type)
@@ -263,7 +272,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
priority: params.priority as MessagePriority,
threadId,
payload: params.payload,
- senderPaneKey: params.senderPaneKey
+ senderPaneKey
})
)
for (const message of messages) {
@@ -304,22 +313,26 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
? db.getAllMessagesForHandle(handle, undefined, typeFilter)
: db.getUnreadMessages(handle, typeFilter)
+ let visibleMessages = messages
if (consumeUnread && messages.length > 0) {
// Why: manual coordinators can consume lifecycle messages before
// the coordinator loop sees them, but unread `check` is still an
// authoritative read path for worker_done/heartbeat.
- for (const message of messages) {
- reconcileLifecycleMessage(db, message)
- }
+ visibleMessages = messages.map((message) => {
+ const reconciled = reconcileLifecycleMessage(db, message)
+ return reconciled.action === 'rejected'
+ ? (db.getMessageById(message.id) ?? message)
+ : message
+ })
db.markAsRead(messages.map((m) => m.id))
}
if (params.inject) {
- const formatted = messages.map(formatMessageBanner).join('\n\n')
- return { messages, formatted, count: messages.length }
+ const formatted = visibleMessages.map(formatMessageBanner).join('\n\n')
+ return { messages: visibleMessages, formatted, count: visibleMessages.length }
}
- return { messages, count: messages.length }
+ return { messages: visibleMessages, count: visibleMessages.length }
}
if (signal?.aborted) {
@@ -481,6 +494,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
dispatchId: 'ctx_dryrun',
taskSpec: task.spec,
coordinatorHandle: params.from ?? 'coordinator',
+ workerHandle: params.to ?? 'worker',
devMode: params.devMode
})
return { dispatch: null, injected: false, dryRun: true, preamble }
@@ -525,6 +539,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
dispatchId: ctx.id,
taskSpec: task.spec,
coordinatorHandle: params.from ?? 'coordinator',
+ workerHandle: to,
devMode: params.devMode
})
@@ -576,6 +591,7 @@ export const ORCHESTRATION_METHODS: RpcMethod[] = [
dispatchId: ctx?.id ?? 'ctx_preview',
taskSpec: task.spec,
coordinatorHandle: params.from ?? 'coordinator',
+ workerHandle: ctx?.assignee_handle ?? 'worker',
devMode: params.devMode
})
return { dispatch: ctx ?? null, preamble }
diff --git a/src/main/ssh/ssh-relay-versioned-install.test.ts b/src/main/ssh/ssh-relay-versioned-install.test.ts
index 8cc46e8b151..244ae80a48c 100644
--- a/src/main/ssh/ssh-relay-versioned-install.test.ts
+++ b/src/main/ssh/ssh-relay-versioned-install.test.ts
@@ -108,11 +108,12 @@ describe('isRelayAlreadyInstalled', () => {
).rejects.toBe(sessionLimitError)
})
- it('checks for relay.js AND .install-complete in addition to the dir', async () => {
+ it('checks for both relay process artifacts and .install-complete', async () => {
mockExec.mockResolvedValueOnce('OK')
await isRelayAlreadyInstalled(conn, '/r')
const cmd = mockExec.mock.calls.at(-1)?.[1] ?? ''
expect(cmd).toContain('relay.js')
+ expect(cmd).toContain('relay-watcher.js')
expect(cmd).toContain('.install-complete')
})
})
diff --git a/src/main/ssh/ssh-relay-versioned-install.ts b/src/main/ssh/ssh-relay-versioned-install.ts
index 5ebac3a07fc..a669f0b7875 100644
--- a/src/main/ssh/ssh-relay-versioned-install.ts
+++ b/src/main/ssh/ssh-relay-versioned-install.ts
@@ -126,10 +126,9 @@ export function computeRemoteRelayDir(
/**
* Probe whether a fully-installed relay already exists at remoteRelayDir.
*
- * "Fully installed" means: the directory exists, contains relay.js, AND
- * contains the .install-complete sentinel written at the end of a successful
- * install. A directory missing .install-complete is either mid-install (lock
- * held) or a crashed-install partial — either way we re-run the deploy.
+ * "Fully installed" means: the directory contains relay.js, its isolated
+ * relay-watcher.js child, and the .install-complete sentinel written at the
+ * end of a successful install. Missing artifacts force a complete re-deploy.
*/
export async function isRelayAlreadyInstalled(
conn: SshConnection,
diff --git a/src/main/ssh/ssh-remote-linear-argument-error.ts b/src/main/ssh/ssh-remote-cli-argument-error.ts
similarity index 100%
rename from src/main/ssh/ssh-remote-linear-argument-error.ts
rename to src/main/ssh/ssh-remote-cli-argument-error.ts
diff --git a/src/main/ssh/ssh-remote-commands.ts b/src/main/ssh/ssh-remote-commands.ts
index 01ab8b266a7..339f4aef594 100644
--- a/src/main/ssh/ssh-remote-commands.ts
+++ b/src/main/ssh/ssh-remote-commands.ts
@@ -59,11 +59,13 @@ export function probeRelayInstalledCommand(
remoteRelayDir: string
): string {
const relayJs = joinRemotePath(host, remoteRelayDir, 'relay.js')
+ const relayWatcherJs = joinRemotePath(host, remoteRelayDir, 'relay-watcher.js')
const installComplete = joinRemotePath(host, remoteRelayDir, '.install-complete')
if (!isWindowsRemoteHost(host)) {
return (
`test -d ${shellEscape(remoteRelayDir)} ` +
`&& test -f ${shellEscape(relayJs)} ` +
+ `&& test -f ${shellEscape(relayWatcherJs)} ` +
`&& test -f ${shellEscape(installComplete)} ` +
`&& echo OK || echo MISSING`
)
@@ -72,8 +74,9 @@ export function probeRelayInstalledCommand(
[
`$dir = ${powerShellLiteral(remoteRelayDir)}`,
`$relay = ${powerShellLiteral(relayJs)}`,
+ `$watcher = ${powerShellLiteral(relayWatcherJs)}`,
`$complete = ${powerShellLiteral(installComplete)}`,
- "if ((Test-Path -LiteralPath $dir -PathType Container) -and (Test-Path -LiteralPath $relay -PathType Leaf) -and (Test-Path -LiteralPath $complete -PathType Leaf)) { 'OK' } else { 'MISSING' }"
+ "if ((Test-Path -LiteralPath $dir -PathType Container) -and (Test-Path -LiteralPath $relay -PathType Leaf) -and (Test-Path -LiteralPath $watcher -PathType Leaf) -and (Test-Path -LiteralPath $complete -PathType Leaf)) { 'OK' } else { 'MISSING' }"
].join('; ')
)
}
diff --git a/src/main/ssh/ssh-remote-linear-cli.ts b/src/main/ssh/ssh-remote-linear-cli.ts
index 3367c217256..4a5c5c4b416 100644
--- a/src/main/ssh/ssh-remote-linear-cli.ts
+++ b/src/main/ssh/ssh-remote-linear-cli.ts
@@ -2,14 +2,12 @@ import type { RpcDispatcher } from '../runtime/rpc/dispatcher'
import type { RpcResponse } from '../runtime/rpc/core'
import { getRemoteLinearReadHelp } from './ssh-remote-linear-read-help'
import { tryDispatchRemoteLinearReadCli } from './ssh-remote-linear-read-cli'
-import { RemoteCliArgumentError, type ParsedRemoteCli } from './ssh-remote-linear-argument-error'
+import type { ParsedRemoteCli } from './ssh-remote-cli-argument-error'
import {
getRemoteLinearWriteHelp,
tryDispatchRemoteLinearWriteCli
} from './ssh-remote-linear-write-cli'
-export { RemoteCliArgumentError }
-
export function getRemoteLinearHelp(parsed: ParsedRemoteCli): string | null {
const helpPath = remoteLinearHelpPath(parsed)
if (!helpPath) {
diff --git a/src/main/ssh/ssh-remote-linear-read-cli.ts b/src/main/ssh/ssh-remote-linear-read-cli.ts
index 82a6fedb2ad..7e64081c5c0 100644
--- a/src/main/ssh/ssh-remote-linear-read-cli.ts
+++ b/src/main/ssh/ssh-remote-linear-read-cli.ts
@@ -6,7 +6,7 @@ import {
} from '../../shared/linear-agent-access'
import type { RpcDispatcher } from '../runtime/rpc/dispatcher'
import type { RpcResponse } from '../runtime/rpc/core'
-import { RemoteCliArgumentError, type ParsedRemoteCli } from './ssh-remote-linear-argument-error'
+import { RemoteCliArgumentError, type ParsedRemoteCli } from './ssh-remote-cli-argument-error'
import {
LINEAR_ISSUE_FLAGS,
diff --git a/src/main/ssh/ssh-remote-orca-cli.test.ts b/src/main/ssh/ssh-remote-orca-cli.test.ts
index f54c2157c55..1741772d789 100644
--- a/src/main/ssh/ssh-remote-orca-cli.test.ts
+++ b/src/main/ssh/ssh-remote-orca-cli.test.ts
@@ -11,7 +11,8 @@ vi.mock('../persistence', () => ({
getCanonicalUserDataPath: () => '/host/user-data'
}))
-import type { OrcaRuntimeService } from '../runtime/orca-runtime'
+import { OrchestrationDb } from '../runtime/orchestration/db'
+import { OrcaRuntimeService } from '../runtime/orca-runtime'
import type { HostCliPassthroughOptions } from './ssh-remote-cli-host-passthrough'
import { runRemoteOrcaCli } from './ssh-remote-orca-cli'
@@ -91,6 +92,7 @@ describe('runRemoteOrcaCli', () => {
liveLeafCount: 1
}),
getOrchestrationDb: () => db,
+ getTerminalPaneKey: () => null,
deliverPendingMessagesForHandle: vi.fn(),
notifyMessageArrived: vi.fn(),
linearIssueContext: vi.fn(async (request: unknown) => ({
@@ -147,6 +149,191 @@ describe('runRemoteOrcaCli', () => {
expect(db.getUnreadMessages('term_windows')[0]?.from_handle).toBe('term_ssh')
})
+ it('forwards remote pane identity through the legacy orchestration fallback', async () => {
+ const { runtime, db } = createRuntime()
+
+ const result = await runRemoteOrcaCli(
+ runtime,
+ {
+ argv: ['orchestration', 'send', '--to', 'term_windows', '--subject', 'ping', '--json'],
+ cwd: '/home/alice/repo',
+ env: {
+ ORCA_TERMINAL_HANDLE: 'term_ssh',
+ ORCA_PANE_KEY: 'tab_ssh:leaf_ssh'
+ }
+ },
+ LEGACY_FALLBACK_OPTIONS
+ )
+
+ expect(result.exitCode).toBe(0)
+ expect(db.insertMessage).toHaveBeenCalledWith(
+ expect.objectContaining({ senderPaneKey: 'tab_ssh:leaf_ssh' })
+ )
+ })
+
+ it('returns a non-zero status for lifecycle rejection through the legacy fallback', async () => {
+ const db = new OrchestrationDb(':memory:')
+ const runtime = new OrcaRuntimeService()
+ runtime.setOrchestrationDb(db)
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+ vi.spyOn(runtime, 'notifyMessageArrived').mockImplementation(() => {})
+ const task = db.createTask({ spec: 'remote work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_ssh', 'tab_owner:leaf_owner')
+
+ try {
+ const result = await runRemoteOrcaCli(
+ runtime,
+ {
+ argv: [
+ 'orchestration',
+ 'send',
+ '--from',
+ 'term_ssh',
+ '--to',
+ 'term_coord',
+ '--subject',
+ 'Done',
+ '--type',
+ 'worker_done',
+ '--payload',
+ JSON.stringify({ taskId: task.id, dispatchId: dispatch.id }),
+ '--json'
+ ],
+ cwd: '/home/alice/repo',
+ env: { ORCA_PANE_KEY: 'tab_foreign:leaf_foreign' }
+ },
+ LEGACY_FALLBACK_OPTIONS
+ )
+
+ expect(result.exitCode).toBe(1)
+ expect(JSON.parse(result.stdout)).toMatchObject({
+ ok: true,
+ result: {
+ message: { type: 'worker_done', subject: 'Rejected worker_done: Done' },
+ lifecycle: { action: 'rejected', code: 'sender_not_assignee' }
+ }
+ })
+ expect(db.getTask(task.id)?.status).toBe('dispatched')
+ } finally {
+ db.close()
+ }
+ })
+
+ it('preserves structured lifecycle payload flags through the legacy fallback', async () => {
+ const db = new OrchestrationDb(':memory:')
+ const runtime = new OrcaRuntimeService()
+ runtime.setOrchestrationDb(db)
+ vi.spyOn(runtime, 'deliverPendingMessagesForHandle').mockImplementation(() => {})
+ vi.spyOn(runtime, 'notifyMessageArrived').mockImplementation(() => {})
+ const task = db.createTask({ spec: 'remote work' })
+ const dispatch = db.createDispatchContext(task.id, 'term_ssh', 'tab_owner:leaf_owner')
+
+ try {
+ const result = await runRemoteOrcaCli(
+ runtime,
+ {
+ argv: [
+ 'orchestration',
+ 'send',
+ '--to',
+ 'term_coord',
+ '--subject',
+ 'Done',
+ '--type',
+ 'worker_done',
+ '--task-id',
+ task.id,
+ '--dispatch-id',
+ dispatch.id,
+ '--files-modified',
+ 'src/a.ts, src/b.ts',
+ '--json'
+ ],
+ cwd: '/home/alice/repo',
+ env: {
+ ORCA_TERMINAL_HANDLE: 'term_ssh',
+ ORCA_PANE_KEY: 'tab_owner:leaf_owner'
+ }
+ },
+ LEGACY_FALLBACK_OPTIONS
+ )
+
+ expect(result.exitCode).toBe(0)
+ expect(db.getTask(task.id)).toMatchObject({
+ status: 'completed',
+ result: expect.stringContaining('src/a.ts')
+ })
+ } finally {
+ db.close()
+ }
+ })
+
+ it('rejects identity-less lifecycle sends in the legacy fallback', async () => {
+ const { runtime, db } = createRuntime()
+
+ const result = await runRemoteOrcaCli(
+ runtime,
+ {
+ argv: [
+ 'orchestration',
+ 'send',
+ '--to',
+ 'term_coord',
+ '--subject',
+ 'Done',
+ '--type',
+ 'worker_done',
+ '--json'
+ ],
+ cwd: '/home/alice/repo',
+ env: {}
+ },
+ LEGACY_FALLBACK_OPTIONS
+ )
+
+ expect(result.exitCode).toBe(1)
+ expect(JSON.parse(result.stdout)).toMatchObject({
+ ok: false,
+ error: { code: 'no_active_sender_terminal' }
+ })
+ expect(db.insertMessage).not.toHaveBeenCalled()
+ })
+
+ it('rejects mixed raw and structured payload flags in the legacy fallback', async () => {
+ const { runtime, db } = createRuntime()
+
+ const result = await runRemoteOrcaCli(
+ runtime,
+ {
+ argv: [
+ 'orchestration',
+ 'send',
+ '--from',
+ 'term_ssh',
+ '--to',
+ 'term_coord',
+ '--subject',
+ 'Done',
+ '--payload',
+ '{"taskId":"task_1"}',
+ '--task-id',
+ 'task_1',
+ '--json'
+ ],
+ cwd: '/home/alice/repo',
+ env: {}
+ },
+ LEGACY_FALLBACK_OPTIONS
+ )
+
+ expect(result.exitCode).toBe(1)
+ expect(JSON.parse(result.stdout)).toMatchObject({
+ ok: false,
+ error: { code: 'invalid_argument', message: expect.stringContaining('structured payload') }
+ })
+ expect(db.insertMessage).not.toHaveBeenCalled()
+ })
+
it('accepts equals-style orchestration flags in the remote shim', async () => {
const { runtime, db } = createRuntime()
diff --git a/src/main/ssh/ssh-remote-orca-cli.ts b/src/main/ssh/ssh-remote-orca-cli.ts
index d555b5c2707..205723321da 100644
--- a/src/main/ssh/ssh-remote-orca-cli.ts
+++ b/src/main/ssh/ssh-remote-orca-cli.ts
@@ -10,19 +10,16 @@ import {
type RemoteOrcaCliRequest,
type RemoteOrcaCliResult
} from './ssh-remote-cli-host-passthrough'
+import { RemoteCliArgumentError, type ParsedRemoteCli } from './ssh-remote-cli-argument-error'
+import { getRemoteLinearHelp, tryDispatchRemoteLinearCli } from './ssh-remote-linear-cli'
import {
- RemoteCliArgumentError,
- getRemoteLinearHelp,
- tryDispatchRemoteLinearCli
-} from './ssh-remote-linear-cli'
+ getRemoteOrchestrationPayload,
+ hasRemoteLifecycleRejection,
+ resolveRemoteOrchestrationSender
+} from './ssh-remote-orchestration-send'
export type { RemoteOrcaCliRequest, RemoteOrcaCliResult } from './ssh-remote-cli-host-passthrough'
-type ParsedRemoteCli = {
- commandPath: string[]
- flags: Map
-}
-
// Why: these commands run a foreground/interactive process attached to the
// caller's TTY (or a local tmux pane), which a buffered one-shot relay bridge
// cannot host. Everything else routes through the full host CLI.
@@ -116,7 +113,9 @@ async function runLegacyRemoteOrcaCli(
return {
stdout: formatted.stdout,
stderr: formatted.stderr,
- exitCode: response.ok ? 0 : 1
+ // Why: the legacy SSH bridge bypasses the local CLI handler that turns
+ // a persisted lifecycle rejection into an unsuccessful command.
+ exitCode: response.ok && !hasRemoteLifecycleRejection(response.result) ? 0 : 1
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
@@ -174,17 +173,22 @@ async function dispatchRemoteCli(
worktree: optionalString(parsed.flags, 'worktree'),
limit: optionalNumber(parsed.flags, 'limit')
})
- case 'orchestration send':
+ case 'orchestration send': {
+ const type = optionalString(parsed.flags, 'type')
return await call(dispatcher, 'orchestration.send', {
- from: resolveHandle(parsed.flags, env, 'from'),
+ from: resolveRemoteOrchestrationSender(parsed.flags, env, type),
to: requiredString(parsed.flags, 'to'),
subject: requiredString(parsed.flags, 'subject'),
body: optionalString(parsed.flags, 'body'),
- type: optionalString(parsed.flags, 'type'),
+ type,
priority: optionalString(parsed.flags, 'priority'),
threadId: optionalString(parsed.flags, 'thread-id'),
- payload: optionalString(parsed.flags, 'payload')
+ payload: getRemoteOrchestrationPayload(parsed.flags),
+ // Why: the legacy in-process bridge must preserve the same pane
+ // authority as the full host CLI passthrough.
+ senderPaneKey: env.ORCA_PANE_KEY || undefined
})
+ }
case 'orchestration check':
return await call(dispatcher, 'orchestration.check', {
terminal: resolveHandle(parsed.flags, env, 'terminal'),
diff --git a/src/main/ssh/ssh-remote-orchestration-send.test.ts b/src/main/ssh/ssh-remote-orchestration-send.test.ts
new file mode 100644
index 00000000000..6efd9a18891
--- /dev/null
+++ b/src/main/ssh/ssh-remote-orchestration-send.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import {
+ getRemoteOrchestrationPayload,
+ hasRemoteLifecycleRejection,
+ resolveRemoteOrchestrationSender
+} from './ssh-remote-orchestration-send'
+
+describe('remote orchestration send compatibility', () => {
+ it('recognizes only structured lifecycle rejections', () => {
+ expect(hasRemoteLifecycleRejection({ lifecycle: { action: 'rejected' } })).toBe(true)
+ expect(hasRemoteLifecycleRejection({ lifecycle: null })).toBe(false)
+ expect(hasRemoteLifecycleRejection({ lifecycle: { action: 'completed' } })).toBe(false)
+ expect(hasRemoteLifecycleRejection(null)).toBe(false)
+ })
+
+ it('prefers an explicit sender over the remote terminal environment', () => {
+ expect(
+ resolveRemoteOrchestrationSender(
+ new Map([['from', 'term_explicit']]),
+ { ORCA_TERMINAL_HANDLE: 'term_env' },
+ 'worker_done'
+ )
+ ).toBe('term_explicit')
+ })
+
+ it.each(['worker_done', 'heartbeat'])('fails closed for an identity-less %s', (type) => {
+ expect(() => resolveRemoteOrchestrationSender(new Map(), {}, type)).toThrowError(
+ expect.objectContaining({ code: 'no_active_sender_terminal' })
+ )
+ })
+
+ it('preserves the legacy unknown sender for non-lifecycle messages', () => {
+ expect(resolveRemoteOrchestrationSender(new Map(), {}, 'status')).toBe('unknown')
+ })
+
+ it('serializes every structured payload field with local CLI semantics', () => {
+ const payload = getRemoteOrchestrationPayload(
+ new Map([
+ ['task-id', 'task_1'],
+ ['dispatch-id', 'ctx_1'],
+ ['files-modified', 'src/a.ts, src/b.ts,'],
+ ['report-path', 'report.md'],
+ ['phase', 'reviewing']
+ ])
+ )
+
+ expect(JSON.parse(payload ?? '{}')).toEqual({
+ taskId: 'task_1',
+ dispatchId: 'ctx_1',
+ filesModified: ['src/a.ts', 'src/b.ts'],
+ reportPath: 'report.md',
+ phase: 'reviewing'
+ })
+ })
+
+ it('passes through a raw payload when no structured fields are present', () => {
+ expect(getRemoteOrchestrationPayload(new Map([['payload', '{"ok":true}']]))).toBe('{"ok":true}')
+ })
+
+ it('rejects mixed raw and structured payloads', () => {
+ expect(() =>
+ getRemoteOrchestrationPayload(
+ new Map([
+ ['payload', '{"taskId":"task_1"}'],
+ ['task-id', 'task_1']
+ ])
+ )
+ ).toThrowError(expect.objectContaining({ code: 'invalid_argument' }))
+ })
+})
diff --git a/src/main/ssh/ssh-remote-orchestration-send.ts b/src/main/ssh/ssh-remote-orchestration-send.ts
new file mode 100644
index 00000000000..5e844a9c586
--- /dev/null
+++ b/src/main/ssh/ssh-remote-orchestration-send.ts
@@ -0,0 +1,83 @@
+import { RemoteCliArgumentError } from './ssh-remote-cli-argument-error'
+
+type RemoteFlags = Map
+
+export function hasRemoteLifecycleRejection(result: unknown): boolean {
+ if (!result || typeof result !== 'object') {
+ return false
+ }
+ const lifecycle = (result as { lifecycle?: unknown }).lifecycle
+ return (
+ lifecycle !== null &&
+ typeof lifecycle === 'object' &&
+ (lifecycle as { action?: unknown }).action === 'rejected'
+ )
+}
+
+export function resolveRemoteOrchestrationSender(
+ flags: RemoteFlags,
+ env: Record,
+ type: string | undefined
+): string {
+ const explicit = optionalString(flags, 'from')
+ const envHandle = env.ORCA_TERMINAL_HANDLE || undefined
+ if ((type === 'worker_done' || type === 'heartbeat') && !explicit && !envHandle) {
+ // Why: the fallback must not turn missing remote identity into the
+ // synthetic "unknown" handle for lifecycle authority decisions.
+ throw new RemoteCliArgumentError(
+ 'no_active_sender_terminal',
+ 'Could not determine the sender terminal for this orchestration command. ' +
+ 'Pass --from or run the command inside a live Orca terminal with ORCA_TERMINAL_HANDLE set.'
+ )
+ }
+ return explicit ?? envHandle ?? 'unknown'
+}
+
+export function getRemoteOrchestrationPayload(flags: RemoteFlags): string | undefined {
+ const rawPayload = optionalString(flags, 'payload')
+ const taskId = optionalString(flags, 'task-id')
+ const dispatchId = optionalString(flags, 'dispatch-id')
+ const filesModified = optionalString(flags, 'files-modified')
+ const reportPath = optionalString(flags, 'report-path')
+ const phase = optionalString(flags, 'phase')
+ const hasStructuredPayload = [taskId, dispatchId, filesModified, reportPath, phase].some(
+ (value) => value !== undefined
+ )
+ if (!hasStructuredPayload) {
+ return rawPayload
+ }
+ if (rawPayload !== undefined) {
+ throw new RemoteCliArgumentError(
+ 'invalid_argument',
+ 'Use either --payload or structured payload flags, not both.'
+ )
+ }
+
+ // Why: the fallback receives the same preamble commands as the full CLI;
+ // preserving these flags keeps lifecycle payloads valid over broken installs.
+ const payload: Record = {}
+ if (taskId) {
+ payload.taskId = taskId
+ }
+ if (dispatchId) {
+ payload.dispatchId = dispatchId
+ }
+ if (filesModified) {
+ payload.filesModified = filesModified
+ .split(',')
+ .map((file) => file.trim())
+ .filter(Boolean)
+ }
+ if (reportPath) {
+ payload.reportPath = reportPath
+ }
+ if (phase) {
+ payload.phase = phase
+ }
+ return JSON.stringify(payload)
+}
+
+function optionalString(flags: RemoteFlags, name: string): string | undefined {
+ const value = flags.get(name)
+ return typeof value === 'string' && value.length > 0 ? value : undefined
+}
diff --git a/src/main/startup/desktop-startup-ordering.test.ts b/src/main/startup/desktop-startup-ordering.test.ts
index 7939af31aae..d99177285af 100644
--- a/src/main/startup/desktop-startup-ordering.test.ts
+++ b/src/main/startup/desktop-startup-ordering.test.ts
@@ -24,6 +24,31 @@ describe('desktop startup ordering', () => {
expect(Math.max(rpcStartIndex, legacyRpcStartIndex)).toBeGreaterThanOrEqual(0)
})
+ it('shows the desktop window without waiting for WSL registration reconciliation', () => {
+ const source = readFileSync(join(process.cwd(), 'src/main/index.ts'), 'utf8')
+ const barrierStart = source.indexOf("ipcMain.handle('app:awaitFirstWindowStartupServices'")
+ const barrierEnd = source.indexOf("ipcMain.handle(\n 'app:startupDiagnostic'", barrierStart)
+ const barrier = source.slice(barrierStart, barrierEnd)
+ const reconciliationStart = source.indexOf(
+ 'managedWslCliReconciliationReady = reconcileManagedWslCliRegistrations('
+ )
+ const serveStart = source.indexOf('if (serveOptions) {', reconciliationStart)
+ const serveReady = source.indexOf('await printServeReady(serveOptions)', serveStart)
+ const serveEnd = source.indexOf('return', serveReady)
+ const desktopWindowStart = source.indexOf('Promise.resolve(openMainWindow())')
+ const serveStartup = source.slice(serveStart, serveEnd)
+ const desktopStartup = source.slice(serveEnd, desktopWindowStart)
+
+ expect(reconciliationStart).toBeGreaterThanOrEqual(0)
+ expect(serveStart).toBeGreaterThan(reconciliationStart)
+ expect(serveEnd).toBeGreaterThan(serveStart)
+ expect(desktopWindowStart).toBeGreaterThan(reconciliationStart)
+ expect(serveStartup).toContain('await managedWslCliReconciliationReady')
+ expect(desktopStartup).not.toContain('await managedWslCliReconciliationReady')
+ expect(barrier).toContain('managedWslCliStartupBarrierReady')
+ expect(barrier).not.toContain('managedWslCliReconciliationReady')
+ })
+
it('does not run the rate-limit quota fetch before the first window can show results', () => {
const source = readFileSync(join(process.cwd(), 'src/main/index.ts'), 'utf8')
const attachIndex = source.indexOf('rateLimits.attach(window)')
diff --git a/src/main/startup/wsl-cli-reconciliation-startup-barrier.test.ts b/src/main/startup/wsl-cli-reconciliation-startup-barrier.test.ts
new file mode 100644
index 00000000000..e59201e6a02
--- /dev/null
+++ b/src/main/startup/wsl-cli-reconciliation-startup-barrier.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+ WSL_CLI_RECONCILIATION_STARTUP_BUDGET_MS,
+ createWslCliReconciliationStartupBarrier
+} from './wsl-cli-reconciliation-startup-barrier'
+
+describe('createWslCliReconciliationStartupBarrier', () => {
+ it('resolves as soon as reconciliation finishes', async () => {
+ vi.useFakeTimers()
+ let resolveReconciliation!: () => void
+
+ try {
+ const reconciliation = new Promise((resolve) => {
+ resolveReconciliation = resolve
+ })
+ const barrier = createWslCliReconciliationStartupBarrier(reconciliation)
+ let barrierSettled = false
+ void barrier.then(() => {
+ barrierSettled = true
+ })
+
+ await vi.advanceTimersByTimeAsync(1)
+ expect(barrierSettled).toBe(false)
+
+ resolveReconciliation()
+ await expect(barrier).resolves.toBeUndefined()
+ expect(vi.getTimerCount()).toBe(0)
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('fails open when reconciliation exceeds the startup budget', async () => {
+ vi.useFakeTimers()
+ let resolveReconciliation!: () => void
+
+ try {
+ const reconciliation = new Promise((resolve) => {
+ resolveReconciliation = resolve
+ })
+ const barrier = createWslCliReconciliationStartupBarrier(reconciliation)
+ let barrierSettled = false
+ void barrier.then(() => {
+ barrierSettled = true
+ })
+
+ await vi.advanceTimersByTimeAsync(WSL_CLI_RECONCILIATION_STARTUP_BUDGET_MS - 1)
+ expect(barrierSettled).toBe(false)
+
+ await vi.advanceTimersByTimeAsync(1)
+ await expect(barrier).resolves.toBeUndefined()
+ resolveReconciliation()
+ await reconciliation
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('leaves reconciliation running after the startup budget expires', async () => {
+ vi.useFakeTimers()
+ let resolveWork!: () => void
+ let completed = false
+
+ try {
+ const work = new Promise((resolve) => {
+ resolveWork = resolve
+ }).then(() => {
+ completed = true
+ })
+ const barrier = createWslCliReconciliationStartupBarrier(work, { timeoutMs: 10 })
+
+ await vi.advanceTimersByTimeAsync(10)
+ await expect(barrier).resolves.toBeUndefined()
+ expect(completed).toBe(false)
+
+ resolveWork()
+ await work
+ expect(completed).toBe(true)
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+})
diff --git a/src/main/startup/wsl-cli-reconciliation-startup-barrier.ts b/src/main/startup/wsl-cli-reconciliation-startup-barrier.ts
new file mode 100644
index 00000000000..5f70ad7eeb0
--- /dev/null
+++ b/src/main/startup/wsl-cli-reconciliation-startup-barrier.ts
@@ -0,0 +1,33 @@
+export const WSL_CLI_RECONCILIATION_STARTUP_BUDGET_MS = 2_000
+
+type WslCliReconciliationStartupBarrierOptions = {
+ timeoutMs?: number
+}
+
+/**
+ * Briefly gates restored terminals while managed WSL registrations reconcile.
+ */
+export function createWslCliReconciliationStartupBarrier(
+ reconciliation: Promise,
+ options: WslCliReconciliationStartupBarrierOptions = {}
+): Promise {
+ const timeoutMs = options.timeoutMs ?? WSL_CLI_RECONCILIATION_STARTUP_BUDGET_MS
+ let timeout: ReturnType | null = null
+ const settled = reconciliation
+ .then(() => undefined)
+ .catch(() => undefined)
+ .finally(() => {
+ if (timeout) {
+ clearTimeout(timeout)
+ }
+ })
+
+ // Why: reconciliation may outlive a slow or unavailable WSL distro; restored
+ // terminals should wait briefly without turning WSL discovery into an app hang.
+ return Promise.race([
+ settled,
+ new Promise((resolve) => {
+ timeout = setTimeout(resolve, timeoutMs)
+ })
+ ])
+}
diff --git a/src/main/wsl.test.ts b/src/main/wsl.test.ts
index fdb5d01a22c..597b1e795f4 100644
--- a/src/main/wsl.test.ts
+++ b/src/main/wsl.test.ts
@@ -1,7 +1,8 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import type * as childProcess from 'node:child_process'
-const { execFileSyncMock } = vi.hoisted(() => ({
+const { execFileMock, execFileSyncMock } = vi.hoisted(() => ({
+ execFileMock: vi.fn(),
execFileSyncMock: vi.fn()
}))
@@ -9,11 +10,21 @@ vi.mock('child_process', async (importOriginal) => {
const actual = await importOriginal()
return {
...actual,
+ execFile: execFileMock,
execFileSync: execFileSyncMock
}
})
-import { toLinuxPath, toWindowsWslPath, parseWslPath, wslUncDirectoryExists } from './wsl'
+import {
+ _resetWslCachesForTests,
+ getCachedWslDistros,
+ listWslDistros,
+ listWslDistrosAsync,
+ parseWslPath,
+ toLinuxPath,
+ toWindowsWslPath,
+ wslUncDirectoryExists
+} from './wsl'
function withPlatform(value: NodeJS.Platform, fn: () => T): T {
const original = process.platform
@@ -25,6 +36,70 @@ function withPlatform(value: NodeJS.Platform, fn: () => T): T {
}
}
+async function withPlatformAsync(value: NodeJS.Platform, fn: () => Promise): Promise {
+ const original = process.platform
+ Object.defineProperty(process, 'platform', { configurable: true, value })
+ try {
+ return await fn()
+ } finally {
+ Object.defineProperty(process, 'platform', { configurable: true, value: original })
+ }
+}
+
+describe('WSL distro discovery cache', () => {
+ afterEach(() => {
+ execFileMock.mockReset()
+ execFileSyncMock.mockReset()
+ _resetWslCachesForTests()
+ })
+
+ it('retries asynchronous discovery after a transient wsl.exe failure', async () => {
+ vi.useFakeTimers()
+ execFileMock
+ .mockImplementationOnce((_command, _args, _options, callback) => {
+ callback(new Error('transient failure'), '')
+ })
+ .mockImplementationOnce((_command, _args, _options, callback) => {
+ callback(null, 'Ubuntu\n')
+ })
+
+ try {
+ await withPlatformAsync('win32', async () => {
+ await expect(listWslDistrosAsync()).resolves.toEqual([])
+ expect(getCachedWslDistros()).toBeNull()
+ // Brief negative caching bounds the wsl.exe spawn rate between retries.
+ await expect(listWslDistrosAsync()).resolves.toEqual([])
+ expect(execFileMock).toHaveBeenCalledTimes(1)
+ vi.advanceTimersByTime(15_000)
+ await expect(listWslDistrosAsync()).resolves.toEqual(['Ubuntu'])
+ })
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('retries synchronous discovery after a transient wsl.exe failure', () => {
+ vi.useFakeTimers()
+ execFileSyncMock.mockImplementationOnce(() => {
+ throw new Error('transient failure')
+ })
+ execFileSyncMock.mockReturnValueOnce('Ubuntu\n')
+
+ try {
+ withPlatform('win32', () => {
+ expect(listWslDistros()).toEqual([])
+ expect(getCachedWslDistros()).toBeNull()
+ expect(listWslDistros()).toEqual([])
+ expect(execFileSyncMock).toHaveBeenCalledTimes(1)
+ vi.advanceTimersByTime(15_000)
+ expect(listWslDistros()).toEqual(['Ubuntu'])
+ })
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+})
+
describe('wsl path helpers', () => {
it('parses WSL UNC paths on Windows', () => {
const originalPlatform = process.platform
diff --git a/src/main/wsl.ts b/src/main/wsl.ts
index d668a064f66..1d27b694d2c 100644
--- a/src/main/wsl.ts
+++ b/src/main/wsl.ts
@@ -113,6 +113,12 @@ export function toWindowsWslPath(linuxPath: string, distro: string): string {
const wslHomeCache = new Map()
let wslDistroCache: string[] | null = null
+// Why: a wsl.exe failure must stay retryable (a transient error would
+// otherwise hide every distro until restart), but repeated failures cannot
+// re-spawn a blocking wsl.exe on every caller; brief negative caching bounds
+// the spawn rate on machines where WSL is absent or persistently broken.
+const WSL_DISTRO_LIST_FAILURE_TTL_MS = 15_000
+let wslDistroListFailedUntilMs = 0
function normalizeWslListOutput(output: string): string[] {
// Why: wsl.exe can emit UTF-16-looking NUL bytes when inherited through
@@ -138,6 +144,10 @@ export function listWslDistros(): string[] {
return wslDistroCache
}
+ if (Date.now() < wslDistroListFailedUntilMs) {
+ return []
+ }
+
try {
const output = execFileSync('wsl.exe', ['--list', '--quiet'], {
encoding: 'utf-8',
@@ -147,8 +157,8 @@ export function listWslDistros(): string[] {
wslDistroCache = normalizeWslListOutput(output).filter(isUserWslDistro)
return wslDistroCache
} catch {
- wslDistroCache = []
- return wslDistroCache
+ wslDistroListFailedUntilMs = Date.now() + WSL_DISTRO_LIST_FAILURE_TTL_MS
+ return []
}
}
@@ -162,13 +172,17 @@ export async function listWslDistrosAsync(): Promise {
return wslDistroCache
}
+ if (Date.now() < wslDistroListFailedUntilMs) {
+ return []
+ }
+
try {
const output = await execFileUtf8('wsl.exe', ['--list', '--quiet'])
wslDistroCache = normalizeWslListOutput(output).filter(isUserWslDistro)
return wslDistroCache
} catch {
- wslDistroCache = []
- return wslDistroCache
+ wslDistroListFailedUntilMs = Date.now() + WSL_DISTRO_LIST_FAILURE_TTL_MS
+ return []
}
}
@@ -279,6 +293,7 @@ export function getCachedWslAvailability(): boolean | null {
export function _resetWslCachesForTests(): void {
wslHomeCache.clear()
wslDistroCache = null
+ wslDistroListFailedUntilMs = 0
wslAvailableCache = null
}
diff --git a/src/relay/fs-handler.test.ts b/src/relay/fs-handler.test.ts
index 7d5354cf47a..63e399072e9 100644
--- a/src/relay/fs-handler.test.ts
+++ b/src/relay/fs-handler.test.ts
@@ -7,6 +7,7 @@ import * as fs from 'node:fs/promises'
import * as path from 'node:path'
import { mkdtempSync, writeFileSync, mkdirSync, symlinkSync } from 'node:fs'
import { tmpdir } from 'node:os'
+import { subscribeWithInProcessWatcher } from '../main/ipc/parcel-watcher-in-process-fallback'
const { mockSubscribe } = vi.hoisted(() => ({
mockSubscribe: vi.fn()
@@ -121,7 +122,11 @@ describe('FsHandler', () => {
tmpDir = mkdtempSync(path.join(tmpdir(), 'relay-fs-'))
dispatcher = createMockDispatcher()
const ctx = new RelayContext()
- handler = new FsHandler(dispatcher as unknown as RelayDispatcher, ctx)
+ handler = new FsHandler(dispatcher as unknown as RelayDispatcher, ctx, {
+ dispose: vi.fn(),
+ forgetRoot: vi.fn(),
+ subscribe: subscribeWithInProcessWatcher
+ })
})
afterEach(async () => {
diff --git a/src/relay/fs-handler.ts b/src/relay/fs-handler.ts
index 6074fad2e2b..38f0dec9b5d 100644
--- a/src/relay/fs-handler.ts
+++ b/src/relay/fs-handler.ts
@@ -1,5 +1,5 @@
/* eslint-disable max-lines -- Why: relay filesystem request handling shares
- path expansion, file IO, search, streaming reads, Space scans, and watch lifecycle state. */
+ path expansion, file IO, search, streaming reads, and Space scans. */
import { readdir, writeFile, stat, lstat, mkdir, rename, cp, rm, realpath } from 'node:fs/promises'
import { execFile } from 'node:child_process'
import { tmpdir } from 'node:os'
@@ -34,17 +34,8 @@ import { RelayStreamRegistry } from './fs-stream-registry'
import { scanWorkspaceSpaceDirectory } from './workspace-space-scan'
import { buildRelayCommandEnv } from './relay-command-env'
import { assertNoClobberRenameDestinationAvailable } from '../shared/filesystem-rename-collision'
-import {
- WATCHER_IGNORE_DIRS,
- buildParcelWatcherIgnoreOptions
-} from '../main/ipc/filesystem-watcher-ignore'
-
-type WatchState = {
- rootPath: string
- unwatchFn: (() => void) | null
- setupPromise: Promise | null
- clients: Map boolean>
-}
+import { RelayFilesystemWatchRegistry } from './relay-filesystem-watch-registry'
+import type { RelayWatcherProcessPool } from './relay-watcher-process-pool'
async function isDirectoryEntry(
dirPath: string,
@@ -85,15 +76,19 @@ function fileStatFromLstat(stats: Awaited>) {
export class FsHandler {
private dispatcher: RelayDispatcher
- private watches = new Map()
+ private watchRegistry: RelayFilesystemWatchRegistry
private streamRegistry = new RelayStreamRegistry()
private listFilesScans = new ListFilesScanCoordinator()
- constructor(dispatcher: RelayDispatcher, _context: RelayContext) {
+ constructor(
+ dispatcher: RelayDispatcher,
+ _context: RelayContext,
+ watcherPool?: RelayWatcherProcessPool
+ ) {
this.dispatcher = dispatcher
+ this.watchRegistry = new RelayFilesystemWatchRegistry(dispatcher, watcherPool)
this.registerHandlers()
- this.dispatcher.onClientDetached?.((clientId) => {
- this.releaseClientWatches(clientId)
+ this.dispatcher.onClientDetached?.(() => {
// Why: a detached client's fs.streamAck frames will never arrive; wake
// any pump parked on the ack window so it re-checks staleness and exits
// instead of stranding its open file handle.
@@ -122,8 +117,12 @@ export class FsHandler {
this.dispatcher.onRequest('fs.search', (p) => this.search(p))
this.dispatcher.onRequest('fs.listFiles', (p, c) => this.listFiles(p, c))
this.dispatcher.onRequest('fs.workspaceSpaceScan', (p, c) => this.workspaceSpaceScan(p, c))
- this.dispatcher.onRequest('fs.watch', (p, context) => this.watch(p, context))
- this.dispatcher.onNotification('fs.unwatch', (p, context) => this.unwatch(p, context))
+ this.dispatcher.onRequest('fs.watch', (p, context) =>
+ this.watchRegistry.watch(expandTilde(p.rootPath as string), context)
+ )
+ this.dispatcher.onNotification('fs.unwatch', (p, context) =>
+ this.watchRegistry.unwatch(expandTilde(p.rootPath as string), context)
+ )
this.dispatcher.onNotification('fs.cancelStream', (p) => this.cancelStream(p))
this.dispatcher.onNotification('fs.streamAck', (p) => this.streamAck(p))
}
@@ -414,125 +413,8 @@ export class FsHandler {
return scanWorkspaceSpaceDirectory(rootPath, context)
}
- private async watch(params: Record, context?: RequestContext) {
- const rootPath = expandTilde(params.rootPath as string)
-
- this.releaseStaleWatches()
-
- const existing = this.watches.get(rootPath)
- if (existing) {
- if ([...existing.clients.values()].some((isStale) => !isStale())) {
- existing.clients.set(context?.clientId ?? 0, context?.isStale ?? (() => false))
- if (existing.setupPromise) {
- await existing.setupPromise
- }
- return
- }
- existing.unwatchFn?.()
- this.watches.delete(rootPath)
- }
-
- if (this.watches.size >= 20) {
- throw new Error('Maximum number of file watchers reached')
- }
-
- const watchState: WatchState = {
- rootPath,
- unwatchFn: null,
- setupPromise: null,
- clients: new Map([[context?.clientId ?? 0, context?.isStale ?? (() => false)]])
- }
- this.watches.set(rootPath, watchState)
-
- const setupPromise = (async () => {
- const watcher = await import('@parcel/watcher')
- const subscription = await watcher.subscribe(
- rootPath,
- (err, events) => {
- if (err) {
- this.dispatcher.notify('fs.changed', {
- events: [{ kind: 'overflow', absolutePath: rootPath }]
- })
- return
- }
- const mapped = events.map((evt) => ({
- kind: evt.type,
- absolutePath: evt.path
- }))
- this.dispatcher.notify('fs.changed', { events: mapped })
- },
- // Why: align remote watchers with the shared nested exclusion so
- // generated trees neither exhaust inotify nor trigger slow glob regexes.
- buildParcelWatcherIgnoreOptions(WATCHER_IGNORE_DIRS)
- )
- watchState.unwatchFn = () => {
- void subscription.unsubscribe()
- }
- if (
- [...watchState.clients.values()].every((isStale) => isStale()) ||
- this.watches.get(rootPath) !== watchState
- ) {
- // Why: if the only requesting client reconnects while watcher setup is
- // in flight, no client can later balance it with fs.unwatch. Tear down
- // only this request's subscription so a newer replacement watch for the
- // same root is not removed.
- void subscription.unsubscribe()
- if (this.watches.get(rootPath) === watchState) {
- this.watches.delete(rootPath)
- }
- }
- })()
- watchState.setupPromise = setupPromise
-
- try {
- await setupPromise
- } catch {
- if (this.watches.get(rootPath) === watchState) {
- this.watches.delete(rootPath)
- }
- // @parcel/watcher not available -- polling fallback would go here
- process.stderr.write('[relay] File watcher not available, fs.changed events disabled\n')
- }
- }
-
- private unwatch(params: Record, context?: RequestContext): void {
- const rootPath = expandTilde(params.rootPath as string)
- const state = this.watches.get(rootPath)
- if (state) {
- this.releaseWatchClient(rootPath, state, context?.clientId ?? 0)
- }
- }
-
- private releaseClientWatches(clientId: number): void {
- for (const [rootPath, state] of this.watches) {
- this.releaseWatchClient(rootPath, state, clientId)
- }
- }
-
- private releaseStaleWatches(): void {
- for (const [rootPath, state] of this.watches) {
- if ([...state.clients.values()].some((isStale) => !isStale())) {
- continue
- }
- state.unwatchFn?.()
- this.watches.delete(rootPath)
- }
- }
-
- private releaseWatchClient(rootPath: string, state: WatchState, clientId: number): void {
- state.clients.delete(clientId)
- if (state.clients.size > 0) {
- return
- }
- state.unwatchFn?.()
- this.watches.delete(rootPath)
- }
-
dispose(): void {
- for (const [, state] of this.watches) {
- state.unwatchFn?.()
- }
- this.watches.clear()
+ this.watchRegistry.dispose()
void this.streamRegistry.disposeAll()
}
}
diff --git a/src/relay/git-handler-staging.test.ts b/src/relay/git-handler-staging.test.ts
index d4469f37cda..b113afd30c4 100644
--- a/src/relay/git-handler-staging.test.ts
+++ b/src/relay/git-handler-staging.test.ts
@@ -1,5 +1,5 @@
/**
- * Tests for GitHandler commit and bulk-staging operations.
+ * Tests for GitHandler commit and staging operations.
*
* Why: split from git-handler.test.ts to stay under the oxlint max-lines (300) limit.
*/
@@ -19,6 +19,32 @@ import {
type RelayDispatcher
} from './git-handler-test-setup'
+const PATHSPEC_SELECTED_FILE = '[k]eep.log'
+const PATHSPEC_MATCHING_FILE = 'keep.log'
+const PATHSPEC_MUTATION_CASES = [
+ {
+ mode: 'single-file',
+ stageMethod: 'git.stage',
+ unstageMethod: 'git.unstage',
+ selection: { filePath: PATHSPEC_SELECTED_FILE }
+ },
+ {
+ mode: 'bulk',
+ stageMethod: 'git.bulkStage',
+ unstageMethod: 'git.bulkUnstage',
+ selection: { filePaths: [PATHSPEC_SELECTED_FILE] }
+ }
+] as const
+
+function createPathspecCollisionChanges(dir: string): void {
+ gitInit(dir)
+ writeFileSync(path.join(dir, PATHSPEC_SELECTED_FILE), 'selected')
+ writeFileSync(path.join(dir, PATHSPEC_MATCHING_FILE), 'matching')
+ gitCommit(dir, 'initial')
+ writeFileSync(path.join(dir, PATHSPEC_SELECTED_FILE), 'selected modified')
+ writeFileSync(path.join(dir, PATHSPEC_MATCHING_FILE), 'matching modified')
+}
+
describe('GitHandler — commit & staging', () => {
let dispatcher: MockDispatcher
let tmpDir: string
@@ -77,7 +103,38 @@ describe('GitHandler — commit & staging', () => {
})
})
- describe('bulkStage and bulkUnstage', () => {
+ describe('stage and unstage', () => {
+ it.each(PATHSPEC_MUTATION_CASES)(
+ 'treats $mode stage paths with Git glob characters as literals',
+ async ({ stageMethod, selection }) => {
+ createPathspecCollisionChanges(tmpDir)
+
+ await dispatcher.callRequest(stageMethod, { worktreePath: tmpDir, ...selection })
+
+ const output = execFileSync('git', ['diff', '--cached', '--name-only'], {
+ cwd: tmpDir,
+ encoding: 'utf-8'
+ })
+ expect(output.trim()).toBe(PATHSPEC_SELECTED_FILE)
+ }
+ )
+
+ it.each(PATHSPEC_MUTATION_CASES)(
+ 'treats $mode unstage paths with Git glob characters as literals',
+ async ({ unstageMethod, selection }) => {
+ createPathspecCollisionChanges(tmpDir)
+ execFileSync('git', ['add', '.'], { cwd: tmpDir, stdio: 'pipe' })
+
+ await dispatcher.callRequest(unstageMethod, { worktreePath: tmpDir, ...selection })
+
+ const output = execFileSync('git', ['diff', '--cached', '--name-only'], {
+ cwd: tmpDir,
+ encoding: 'utf-8'
+ })
+ expect(output.trim()).toBe(PATHSPEC_MATCHING_FILE)
+ }
+ )
+
it('stages multiple files', async () => {
gitInit(tmpDir)
writeFileSync(path.join(tmpDir, 'a.txt'), 'a')
diff --git a/src/relay/git-handler.test.ts b/src/relay/git-handler.test.ts
index 1ae68d3ce88..d674af9949e 100644
--- a/src/relay/git-handler.test.ts
+++ b/src/relay/git-handler.test.ts
@@ -1192,7 +1192,7 @@ describe('GitHandler', () => {
await Promise.all([first, second])
expect(gitBufferSpy).toHaveBeenCalledTimes(2)
- expect(gitSpy).toHaveBeenCalledWith(['add', '--', 'src/file.ts'], tmpDir)
+ expect(gitSpy).toHaveBeenCalledWith(['add', '--', ':(literal)src/file.ts'], tmpDir)
const submodulePathReads = gitSpy.mock.calls.filter(
([args]) => args[0] === 'config' && args.includes('.gitmodules')
)
diff --git a/src/relay/git-handler.ts b/src/relay/git-handler.ts
index d21dcf3cce9..c6709cd3f2a 100644
--- a/src/relay/git-handler.ts
+++ b/src/relay/git-handler.ts
@@ -488,7 +488,7 @@ export class GitHandler {
const worktreePath = params.worktreePath as string
const filePath = params.filePath as string
try {
- await this.git(['add', '--', filePath], worktreePath)
+ await this.git(['add', '--', this.literalPathspec(filePath)], worktreePath)
} finally {
this.clearGitMutationReadCaches()
}
@@ -512,7 +512,7 @@ export class GitHandler {
const worktreePath = params.worktreePath as string
const filePath = params.filePath as string
try {
- await this.git(['restore', '--staged', '--', filePath], worktreePath)
+ await this.git(['restore', '--staged', '--', this.literalPathspec(filePath)], worktreePath)
} finally {
this.clearGitMutationReadCaches()
}
@@ -525,7 +525,10 @@ export class GitHandler {
try {
for (let i = 0; i < filePaths.length; i += BULK_CHUNK_SIZE) {
const chunk = filePaths.slice(i, i + BULK_CHUNK_SIZE)
- await this.git(['add', '--', ...chunk], worktreePath)
+ await this.git(
+ ['add', '--', ...chunk.map((filePath) => this.literalPathspec(filePath))],
+ worktreePath
+ )
}
} finally {
this.clearGitMutationReadCaches()
@@ -539,7 +542,10 @@ export class GitHandler {
try {
for (let i = 0; i < filePaths.length; i += BULK_CHUNK_SIZE) {
const chunk = filePaths.slice(i, i + BULK_CHUNK_SIZE)
- await this.git(['restore', '--staged', '--', ...chunk], worktreePath)
+ await this.git(
+ ['restore', '--staged', '--', ...chunk.map((filePath) => this.literalPathspec(filePath))],
+ worktreePath
+ )
}
} finally {
this.clearGitMutationReadCaches()
diff --git a/src/relay/relay-filesystem-watch-registry.test.ts b/src/relay/relay-filesystem-watch-registry.test.ts
new file mode 100644
index 00000000000..5f1e46eecdd
--- /dev/null
+++ b/src/relay/relay-filesystem-watch-registry.test.ts
@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { WatcherProcessFailure } from '../main/ipc/parcel-watcher-process-failure'
+import type {
+ WatcherProcessCallback,
+ WatcherProcessHooks,
+ WatcherProcessSubscription
+} from '../main/ipc/parcel-watcher-process-subscription'
+import type { RelayDispatcher, RequestContext } from './dispatcher'
+import { RelayFilesystemWatchRegistry } from './relay-filesystem-watch-registry'
+import { createRelayWatcherProcessPool } from './relay-watcher-process-pool'
+
+type InstalledWatch = {
+ callback: WatcherProcessCallback
+ hooks: WatcherProcessHooks
+ unsubscribe: ReturnType Promise>>
+}
+
+class FakeWatcherPool {
+ readonly installed: InstalledWatch[] = []
+ readonly dispose = vi.fn()
+ readonly forgetRoot = vi.fn()
+
+ async subscribe(
+ _rootPath: string,
+ callback: WatcherProcessCallback,
+ _options: object,
+ hooks: WatcherProcessHooks
+ ): Promise {
+ const unsubscribe = vi.fn(async () => undefined)
+ this.installed.push({ callback, hooks, unsubscribe })
+ return { unsubscribe }
+ }
+}
+
+function createDispatcher() {
+ const detached = new Set<(clientId: number) => void>()
+ return {
+ notify: vi.fn(),
+ onClientDetached: vi.fn((listener: (clientId: number) => void) => {
+ detached.add(listener)
+ return () => detached.delete(listener)
+ })
+ }
+}
+
+function context(clientId: number): RequestContext {
+ return { clientId, isStale: () => false }
+}
+
+describe('RelayFilesystemWatchRegistry', () => {
+ let dispatcher: ReturnType
+ let pool: FakeWatcherPool
+ let registry: RelayFilesystemWatchRegistry
+
+ beforeEach(() => {
+ dispatcher = createDispatcher()
+ pool = new FakeWatcherPool()
+ registry = new RelayFilesystemWatchRegistry(dispatcher as unknown as RelayDispatcher, pool)
+ })
+
+ it('emits overflow around child replacement and resumes ordered event delivery', async () => {
+ await registry.watch('/repo', context(1))
+ const first = pool.installed[0]
+
+ first.callback(null, [{ type: 'create', path: '/repo/before.txt' }])
+ first.hooks.onInterruption?.()
+ first.callback(null, [{ type: 'update', path: '/repo/after-resubscribe.txt' }])
+
+ expect(dispatcher.notify.mock.calls).toEqual([
+ ['fs.changed', { events: [{ kind: 'create', absolutePath: '/repo/before.txt' }] }],
+ ['fs.changed', { events: [{ kind: 'overflow', absolutePath: '/repo' }] }],
+ ['fs.changed', { events: [{ kind: 'update', absolutePath: '/repo/after-resubscribe.txt' }] }]
+ ])
+ })
+
+ it('moves a terminal shard failure into recovery without dropping shared clients', async () => {
+ await registry.watch('/repo', context(1))
+ await registry.watch('/repo', context(2))
+ const first = pool.installed[0]
+ first.hooks.onTerminalError?.(
+ new WatcherProcessFailure(
+ 'file watcher process crashed repeatedly',
+ 'supervisor',
+ 'supervisor_crash_fuse'
+ )
+ )
+ await Promise.resolve()
+
+ expect(pool.installed).toHaveLength(2)
+ pool.installed[1].callback(null, [{ type: 'create', path: '/repo/recovered.txt' }])
+ expect(dispatcher.notify).toHaveBeenNthCalledWith(1, 'fs.changed', {
+ events: [{ kind: 'overflow', absolutePath: '/repo' }]
+ })
+ expect(dispatcher.notify).toHaveBeenNthCalledWith(2, 'fs.changed', {
+ events: [{ kind: 'create', absolutePath: '/repo/recovered.txt' }]
+ })
+
+ registry.unwatch('/repo', context(1))
+ expect(pool.installed[1].unsubscribe).not.toHaveBeenCalled()
+ registry.unwatch('/repo', context(2))
+ expect(pool.installed[1].unsubscribe).toHaveBeenCalledTimes(1)
+ })
+
+ it('aborts a pending crawl only after the last same-root client leaves', async () => {
+ let sharedSignal: AbortSignal | undefined
+ let rejectSubscribe: ((error: Error) => void) | undefined
+ vi.spyOn(pool, 'subscribe').mockImplementation(
+ (_rootPath, _callback, _options, hooks): Promise =>
+ new Promise((_resolve, reject) => {
+ sharedSignal = hooks.signal
+ rejectSubscribe = reject
+ hooks.signal?.addEventListener(
+ 'abort',
+ () =>
+ reject(
+ new WatcherProcessFailure(
+ 'file watcher subscription aborted',
+ 'subscription',
+ 'subscribe_aborted'
+ )
+ ),
+ { once: true }
+ )
+ })
+ )
+ const firstAbort = new AbortController()
+ const secondAbort = new AbortController()
+ const first = registry.watch('/repo', {
+ ...context(1),
+ signal: firstAbort.signal
+ })
+ const second = registry.watch('/repo', {
+ ...context(2),
+ signal: secondAbort.signal
+ })
+
+ firstAbort.abort()
+ await first
+ expect(sharedSignal?.aborted).toBe(false)
+
+ secondAbort.abort()
+ await second
+ expect(sharedSignal?.aborted).toBe(true)
+ expect(rejectSubscribe).toBeDefined()
+ })
+})
+
+describe('createRelayWatcherProcessPool', () => {
+ it('fails closed instead of loading the native watcher in the relay process', async () => {
+ const previousVitest = process.env.VITEST
+ process.env.VITEST = 'true'
+ const pool = createRelayWatcherProcessPool(
+ join(tmpdir(), `missing-relay-watcher-${process.pid}.js`)
+ )
+ try {
+ await expect(pool.subscribe('/repo', vi.fn(), {}, {})).rejects.toMatchObject({
+ code: 'entry_missing'
+ })
+ } finally {
+ pool.dispose()
+ if (previousVitest === undefined) {
+ delete process.env.VITEST
+ } else {
+ process.env.VITEST = previousVitest
+ }
+ }
+ })
+})
diff --git a/src/relay/relay-filesystem-watch-registry.ts b/src/relay/relay-filesystem-watch-registry.ts
new file mode 100644
index 00000000000..a1ccda05826
--- /dev/null
+++ b/src/relay/relay-filesystem-watch-registry.ts
@@ -0,0 +1,312 @@
+import type { RelayDispatcher, RequestContext } from './dispatcher'
+import { MAX_BATCHED_WATCHER_EVENTS } from '../main/ipc/filesystem-watcher-event-batch'
+import { isWatcherProcessFailure } from '../main/ipc/parcel-watcher-process-failure'
+import type {
+ WatcherProcessEvent,
+ WatcherProcessSubscription
+} from '../main/ipc/parcel-watcher-process'
+import {
+ WATCHER_IGNORE_DIRS,
+ buildParcelWatcherIgnoreOptions
+} from '../main/ipc/filesystem-watcher-ignore'
+import {
+ createRelayWatcherProcessPool,
+ type RelayWatcherProcessPool
+} from './relay-watcher-process-pool'
+
+const MAX_RELAY_WATCH_ROOTS = 20
+const RELAY_WATCH_CRAWL_TIMEOUT_MS = 60_000
+const RELAY_WATCH_OPTIONS = buildParcelWatcherIgnoreOptions(WATCHER_IGNORE_DIRS)
+
+type RelayWatchState = {
+ rootPath: string
+ clients: Map boolean>
+ setupPromise: Promise
+ subscription: WatcherProcessSubscription | null
+ abortController: AbortController
+ generation: number
+ closed: boolean
+}
+
+function overflowEvent(rootPath: string): Record {
+ return { events: [{ kind: 'overflow', absolutePath: rootPath }] }
+}
+
+function createWatchAbortError(): Error {
+ const error = new Error('Request "fs.watch" was cancelled')
+ error.name = 'AbortError'
+ return error
+}
+
+function shouldRetryInitialWatch(error: unknown): boolean {
+ return (
+ isWatcherProcessFailure(error) &&
+ error.code !== 'entry_missing' &&
+ error.code !== 'subscribe_aborted' &&
+ error.code !== 'supervisor_disposed' &&
+ (error.scope === 'supervisor' || error.code === 'subscribe_timeout')
+ )
+}
+
+export class RelayFilesystemWatchRegistry {
+ private readonly watches = new Map()
+
+ constructor(
+ private readonly dispatcher: RelayDispatcher,
+ private readonly watcherPool: RelayWatcherProcessPool = createRelayWatcherProcessPool()
+ ) {
+ this.dispatcher.onClientDetached?.((clientId) => this.releaseClientWatches(clientId))
+ }
+
+ async watch(rootPath: string, context?: RequestContext): Promise {
+ this.releaseStaleWatches()
+ const clientId = context?.clientId ?? 0
+ const isStale = context?.isStale ?? (() => false)
+ const existing = this.watches.get(rootPath)
+ if (existing) {
+ existing.clients.set(clientId, isStale)
+ await this.awaitSetupForClient(existing, clientId, context)
+ return
+ }
+
+ if (this.watches.size >= MAX_RELAY_WATCH_ROOTS) {
+ throw new Error('Maximum number of file watchers reached')
+ }
+
+ const state: RelayWatchState = {
+ rootPath,
+ clients: new Map([[clientId, isStale]]),
+ setupPromise: Promise.resolve(),
+ subscription: null,
+ abortController: new AbortController(),
+ generation: 0,
+ closed: false
+ }
+ this.watches.set(rootPath, state)
+ state.setupPromise = this.startInitialWatch(state)
+ await this.awaitSetupForClient(state, clientId, context)
+ }
+
+ unwatch(rootPath: string, context?: RequestContext): void {
+ const state = this.watches.get(rootPath)
+ if (state) {
+ this.releaseWatchClient(state, context?.clientId ?? 0)
+ }
+ }
+
+ dispose(): void {
+ for (const state of Array.from(this.watches.values())) {
+ this.closeWatch(state)
+ }
+ this.watcherPool.dispose()
+ }
+
+ private async startInitialWatch(state: RelayWatchState): Promise {
+ try {
+ await this.subscribeState(state)
+ } catch (firstError) {
+ if (!state.closed && shouldRetryInitialWatch(firstError)) {
+ try {
+ await this.subscribeState(state)
+ this.emitOverflow(state)
+ return
+ } catch (quarantineError) {
+ this.closeWatch(state)
+ throw quarantineError
+ }
+ }
+ this.closeWatch(state)
+ throw firstError
+ }
+ }
+
+ private subscribeState(state: RelayWatchState): Promise {
+ const generation = ++state.generation
+ const emitOverflow = (): void => {
+ if (state.generation === generation) {
+ this.emitOverflow(state)
+ }
+ }
+ return this.watcherPool
+ .subscribe(
+ state.rootPath,
+ (error, events) => {
+ if (state.closed || state.generation !== generation) {
+ return
+ }
+ if (error) {
+ process.stderr.write(
+ `[relay] File watcher error for ${state.rootPath}: ${error.message}\n`
+ )
+ emitOverflow()
+ return
+ }
+ this.emitEvents(state, events)
+ },
+ RELAY_WATCH_OPTIONS,
+ {
+ delivery: { maxEventsPerBatch: MAX_BATCHED_WATCHER_EVENTS },
+ onInterruption: emitOverflow,
+ onOverflow: emitOverflow,
+ onTerminalError: (error) => this.recoverWatch(state, generation, error),
+ signal: state.abortController.signal,
+ subscribeTimeoutMs: RELAY_WATCH_CRAWL_TIMEOUT_MS
+ }
+ )
+ .then(async (subscription) => {
+ if (
+ state.closed ||
+ state.generation !== generation ||
+ this.watches.get(state.rootPath) !== state
+ ) {
+ await subscription.unsubscribe()
+ return
+ }
+ state.subscription = subscription
+ })
+ }
+
+ private recoverWatch(state: RelayWatchState, failedGeneration: number, error: Error): void {
+ if (state.closed || state.generation !== failedGeneration) {
+ return
+ }
+ state.subscription = null
+ this.emitOverflow(state)
+ const recovery = this.subscribeState(state)
+ state.setupPromise = recovery
+ void recovery.catch((recoveryError: unknown) => {
+ if (!state.closed) {
+ const message = recoveryError instanceof Error ? recoveryError.message : error.message
+ process.stderr.write(
+ `[relay] File watcher disabled after bounded recovery for ${state.rootPath}: ${message}\n`
+ )
+ this.closeWatch(state)
+ }
+ })
+ }
+
+ private emitEvents(state: RelayWatchState, events: readonly WatcherProcessEvent[]): void {
+ if (state.closed || events.length === 0) {
+ return
+ }
+ this.dispatcher.notify('fs.changed', {
+ events: events.map((event) => ({
+ kind: event.type,
+ absolutePath: event.path,
+ ...(event.isDirectory === undefined ? {} : { isDirectory: event.isDirectory })
+ }))
+ })
+ }
+
+ private emitOverflow(state: RelayWatchState): void {
+ if (!state.closed) {
+ this.dispatcher.notify('fs.changed', overflowEvent(state.rootPath))
+ }
+ }
+
+ private async awaitSetupForClient(
+ state: RelayWatchState,
+ clientId: number,
+ context?: RequestContext
+ ): Promise {
+ try {
+ await this.awaitSetupWithAbort(state.setupPromise, context?.signal)
+ } catch (error) {
+ this.releaseWatchClient(state, clientId)
+ const expectedAbort =
+ (error instanceof Error && error.name === 'AbortError') ||
+ (isWatcherProcessFailure(error) && error.code === 'subscribe_aborted')
+ if (!expectedAbort && error instanceof Error) {
+ process.stderr.write(
+ `[relay] File watcher not available for ${state.rootPath}: ${error.message}\n`
+ )
+ throw error
+ }
+ return
+ }
+ if (context?.isStale()) {
+ this.releaseWatchClient(state, clientId)
+ }
+ }
+
+ private awaitSetupWithAbort(setupPromise: Promise, signal?: AbortSignal): Promise {
+ if (!signal) {
+ return setupPromise
+ }
+ if (signal.aborted) {
+ return Promise.reject(createWatchAbortError())
+ }
+ return new Promise((resolve, reject) => {
+ const onAbort = (): void => {
+ cleanup()
+ reject(createWatchAbortError())
+ }
+ const cleanup = (): void => signal.removeEventListener('abort', onAbort)
+ signal.addEventListener('abort', onAbort, { once: true })
+ setupPromise.then(
+ () => {
+ cleanup()
+ resolve()
+ },
+ (error) => {
+ cleanup()
+ reject(error)
+ }
+ )
+ })
+ }
+
+ private releaseClientWatches(clientId: number): void {
+ for (const state of Array.from(this.watches.values())) {
+ this.releaseWatchClient(state, clientId)
+ }
+ }
+
+ private releaseStaleWatches(): void {
+ for (const state of Array.from(this.watches.values())) {
+ for (const [clientId, isStale] of state.clients) {
+ if (isStale()) {
+ state.clients.delete(clientId)
+ }
+ }
+ if (state.clients.size === 0) {
+ this.closeWatch(state)
+ }
+ }
+ }
+
+ private releaseWatchClient(state: RelayWatchState, clientId: number): void {
+ state.clients.delete(clientId)
+ if (!state.closed && state.clients.size === 0) {
+ this.closeWatch(state)
+ }
+ }
+
+ private closeWatch(state: RelayWatchState): void {
+ if (state.closed) {
+ return
+ }
+ state.closed = true
+ state.generation++
+ state.abortController.abort()
+ state.clients.clear()
+ if (this.watches.get(state.rootPath) === state) {
+ this.watches.delete(state.rootPath)
+ }
+ const subscription = state.subscription
+ state.subscription = null
+ if (subscription) {
+ // Why: a child can die during unwatch; release quarantine history even
+ // when physical teardown reports that already-contained failure.
+ void subscription.unsubscribe().then(
+ () => this.watcherPool.forgetRoot(state.rootPath),
+ () => this.watcherPool.forgetRoot(state.rootPath)
+ )
+ return
+ }
+ void state.setupPromise.then(
+ () => this.watcherPool.forgetRoot(state.rootPath),
+ () => this.watcherPool.forgetRoot(state.rootPath)
+ )
+ }
+}
diff --git a/src/relay/relay-watcher-process-pool.ts b/src/relay/relay-watcher-process-pool.ts
new file mode 100644
index 00000000000..af6cb8285e2
--- /dev/null
+++ b/src/relay/relay-watcher-process-pool.ts
@@ -0,0 +1,26 @@
+import { join } from 'node:path'
+import { RuntimeWatcherProcessPool } from '../main/ipc/runtime-watcher-process-pool'
+import { WatcherProcessSupervisor } from '../main/ipc/parcel-watcher-process-supervisor'
+
+export type RelayWatcherProcessPool = Pick<
+ RuntimeWatcherProcessPool,
+ 'dispose' | 'forgetRoot' | 'subscribe'
+>
+
+export function getRelayWatcherProcessEntryPath(): string {
+ return join(__dirname, 'relay-watcher.js')
+}
+
+export function createRelayWatcherProcessPool(
+ entryPath = getRelayWatcherProcessEntryPath()
+): RelayWatcherProcessPool {
+ return new RuntimeWatcherProcessPool({
+ createSupervisor: () =>
+ new WatcherProcessSupervisor({
+ entryPath,
+ // Why: a leaked VITEST environment must never move the native addon
+ // back into the relay when its crash-isolation child is missing.
+ useInProcessVitestFallback: false
+ })
+ })
+}
diff --git a/src/relay/subprocess.test.ts b/src/relay/subprocess.test.ts
index 4d19542b91c..219addc02a9 100644
--- a/src/relay/subprocess.test.ts
+++ b/src/relay/subprocess.test.ts
@@ -10,6 +10,7 @@ import { getEndpointFileName } from '../shared/agent-hook-listener'
import { relayTestSocketPath } from './relay-test-socket-path'
const RELAY_TS_ENTRY = path.resolve(__dirname, 'relay.ts')
+const WATCHER_TS_ENTRY = path.resolve(__dirname, '../main/ipc/parcel-watcher-process-entry.ts')
let bundleDir: string
let relayEntry: string
const spawnedSocketDirs: string[] = []
@@ -24,7 +25,17 @@ beforeAll(async () => {
target: 'node18',
format: 'cjs',
outfile: relayEntry,
- external: ['node-pty', '@parcel/watcher'],
+ external: ['node-pty', '@parcel/watcher', 'electron'],
+ sourcemap: false
+ })
+ await build({
+ entryPoints: [WATCHER_TS_ENTRY],
+ bundle: true,
+ platform: 'node',
+ target: 'node18',
+ format: 'cjs',
+ outfile: path.join(bundleDir, 'relay-watcher.js'),
+ external: ['@parcel/watcher'],
sourcemap: false
})
}, 30_000)
diff --git a/src/renderer/src/components/TaskPage.tsx b/src/renderer/src/components/TaskPage.tsx
index c42be0d7bac..3b538d44335 100644
--- a/src/renderer/src/components/TaskPage.tsx
+++ b/src/renderer/src/components/TaskPage.tsx
@@ -9736,13 +9736,21 @@ export default function TaskPage(): React.JSX.Element {
) : (
-
+
)}
{item.type !== 'pr' ? (
diff --git a/src/renderer/src/components/agent/AgentCombobox.test.tsx b/src/renderer/src/components/agent/AgentCombobox.test.tsx
index 6547c3704bd..d6fe7590f49 100644
--- a/src/renderer/src/components/agent/AgentCombobox.test.tsx
+++ b/src/renderer/src/components/agent/AgentCombobox.test.tsx
@@ -1,6 +1,8 @@
import { renderToStaticMarkup } from 'react-dom/server'
import { describe, expect, it, vi } from 'vitest'
+import type { TuiAgent } from '../../../../shared/types'
import { AGENT_CATALOG, AgentIcon } from '@/lib/agent-catalog'
+import { AGENT_FAVICON_ASSETS } from '@/lib/agent-favicon-assets'
import AgentCombobox from './AgentCombobox'
describe('AgentCombobox', () => {
@@ -37,4 +39,14 @@ describe('AgentCombobox', () => {
expect(markup).not.toContain('https://www.google.com/s2/favicons')
expect(markup).not.toContain(' {
+ // Why: previously loaded from Google's favicon service (#8451). Iterate the
+ // full asset map so missing files/key mismatches fail the test.
+ for (const agent of Object.keys(AGENT_FAVICON_ASSETS) as TuiAgent[]) {
+ const markup = renderToStaticMarkup(
+
+function buildCandidateFromStart(
+ buffer: { getLine(y: number): IBufferLine | undefined },
+ startY: number,
+ currentY: number,
+ translatedLines: Map
+): WrappedLogicalLine | null {
+ const startLine = buffer.getLine(startY)
+ if (!startLine) {
+ return null
+ }
+ const cachedStart = translatedLines.get(startY)
+ const startText = cachedStart?.text ?? startLine.translateToString(false)
+ const schemeIndex = startText.search(HTTP_SCHEME_PATTERN)
+ if (schemeIndex === -1 || !VERTICAL_LAYOUT_FRAME_PATTERN.test(startText.slice(0, schemeIndex))) {
+ return null
+ }
+ const translatedStart = cachedStart ?? translateLineWithColumns(startLine)
+ translatedLines.set(startY, translatedStart)
+ const schemeColumn = translatedStart.columns[schemeIndex]
+ if (schemeColumn === undefined) {
+ return null
+ }
+
+ const continuationPrefix = translatedStart.text.slice(0, schemeIndex)
+ let text = ''
+ let rightFrameColumn: number | null = null
+ let previousRowCanContinue = true
+ let startRowFilled = false
+ const rows: WrappedLogicalLine['rows'] = []
+
+ for (let rowY = startY; rowY < startY + TERMINAL_HTTP_URL_MAX_HARD_WRAPPED_ROWS; rowY++) {
+ if (rowY > startY && !previousRowCanContinue) {
+ break
+ }
+ const line = buffer.getLine(rowY)
+ if (!line) {
+ break
+ }
+ const translated =
+ rowY === startY
+ ? translatedStart
+ : (translatedLines.get(rowY) ?? translateLineWithColumns(line))
+ translatedLines.set(rowY, translated)
+ if (rowY > startY && translated.text.slice(0, schemeIndex) !== continuationPrefix) {
+ break
+ }
+
+ const fragment = translated.text.slice(schemeIndex).match(HTTP_FRAGMENT_PATTERN)?.[0] ?? ''
+ if (!fragment || (rowY > startY && HTTP_SCHEME_START_PATTERN.test(fragment))) {
+ break
+ }
+ const fragmentEnd = schemeIndex + fragment.length
+ const layoutSuffix = translated.text.slice(fragmentEnd)
+ const rightFrameOffset = layoutSuffix.search(VERTICAL_LAYOUT_FRAME_PATTERN)
+ const currentRightFrameIndex = rightFrameOffset === -1 ? -1 : fragmentEnd + rightFrameOffset
+ const currentRightFrameColumn = translated.columns[currentRightFrameIndex]
+ if (
+ currentRightFrameIndex === -1 ||
+ currentRightFrameColumn === undefined ||
+ (rightFrameColumn !== null && currentRightFrameColumn !== rightFrameColumn) ||
+ NON_LAYOUT_SUFFIX_PATTERN.test(layoutSuffix)
+ ) {
+ break
+ }
+ rightFrameColumn ??= currentRightFrameColumn
+
+ if (text.length + fragment.length > TERMINAL_HTTP_URL_MAX_LENGTH) {
+ return null
+ }
+
+ rows.push({
+ y: rowY,
+ text: fragment,
+ sourceText: translated.text,
+ columns: translated.columns.slice(schemeIndex, fragmentEnd + 1),
+ startIndex: text.length,
+ isWrapped: line.isWrapped,
+ lineLength: line.length
+ })
+ text += fragment
+
+ const contentWidth = currentRightFrameColumn - schemeColumn
+ const fragmentWidth = translated.columns[fragmentEnd]! - schemeColumn
+ const fillsRow = contentWidth > 0 && fragmentWidth / contentWidth >= MIN_HARD_WRAP_FILL_RATIO
+ if (rowY === startY) {
+ startRowFilled = fillsRow
+ }
+ previousRowCanContinue = HARD_WRAP_CONTINUATION_SUFFIX_PATTERN.test(fragment) || fillsRow
+ }
+
+ if (rows.length > 1 && (rows.length < MIN_HARD_WRAPPED_HTTP_ROWS || !startRowFilled)) {
+ // Why: a short complete URL can legitimately end in `/`; one adjacent
+ // framed token is not enough evidence that the URL continued onto it.
+ rows.splice(1)
+ text = rows[0]?.text ?? ''
+ }
+ if (rows.at(-1)?.y === undefined || rows.at(-1)!.y < currentY) {
+ return null
+ }
+ return {
+ text,
+ rows,
+ fingerprint: `hard-http:${rows.map((row) => `${row.y}:${row.sourceText}`).join('\0')}`
+ }
+}
+
+export function buildHardWrappedHttpLogicalLineCandidates(
+ buffer: { getLine(y: number): IBufferLine | undefined },
+ bufferLineNumber: number
+): WrappedLogicalLine[] {
+ const currentY = bufferLineNumber - 1
+ const currentLine = buffer.getLine(currentY)
+ if (!currentLine || !VERTICAL_LAYOUT_FRAME_PATTERN.test(currentLine.translateToString(false))) {
+ // Why: cursor-positioned hard wraps require a stable vertical frame; most
+ // terminal clicks can avoid the bounded backward scan entirely.
+ return []
+ }
+ const candidates: WrappedLogicalLine[] = []
+ const translatedLines = new Map()
+ const minY = Math.max(0, currentY - TERMINAL_HTTP_URL_MAX_HARD_WRAPPED_ROWS + 1)
+ for (let startY = currentY; startY >= minY; startY--) {
+ const candidate = buildCandidateFromStart(buffer, startY, currentY, translatedLines)
+ if (candidate) {
+ candidates.push(candidate)
+ }
+ }
+ return candidates.sort(
+ (left, right) => right.rows.length - left.rows.length || right.text.length - left.text.length
+ )
+}
diff --git a/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.test.ts b/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.test.ts
index efdac51caef..185cc6460e6 100644
--- a/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.test.ts
+++ b/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.test.ts
@@ -1,4 +1,9 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
+import en from '@/i18n/locales/en.json'
+import es from '@/i18n/locales/es.json'
+import ja from '@/i18n/locales/ja.json'
+import ko from '@/i18n/locales/ko.json'
+import zh from '@/i18n/locales/zh.json'
import { OSC52_CLIPBOARD_SETTING_ID } from './osc52-clipboard-setting-anchor'
import type * as Osc52ClipboardBlockedToastModule from './osc52-clipboard-blocked-toast'
@@ -41,6 +46,7 @@ describe('showOsc52ClipboardBlockedToast', () => {
showOsc52ClipboardBlockedToast()
+ expect(toastInfoMock.mock.calls[0]?.[1]?.description).toContain('Grok')
const options = toastInfoMock.mock.calls[0]?.[1]
expect(options).toMatchObject({
action: {
@@ -67,4 +73,14 @@ describe('showOsc52ClipboardBlockedToast', () => {
expect(toastInfoMock).toHaveBeenCalledTimes(1)
})
+
+ it('mentions Grok in every supported locale', () => {
+ const locales = [en, es, ja, ko, zh]
+
+ for (const locale of locales) {
+ expect(
+ locale.auto.components.terminal.pane.osc52.clipboard.blocked.toast['7cf51f74fd']
+ ).toContain('Grok')
+ }
+ })
})
diff --git a/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.ts b/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.ts
index 127f40f7a99..fb0b5d73a60 100644
--- a/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.ts
+++ b/src/renderer/src/components/terminal-pane/osc52-clipboard-blocked-toast.ts
@@ -19,7 +19,7 @@ export function showOsc52ClipboardBlockedToast(): void {
{
description: translate(
'auto.components.terminal.pane.osc52.clipboard.blocked.toast.7cf51f74fd',
- 'Enable TUI clipboard writes in Terminal settings to copy from SSH, tmux, Neovim, or fzf.'
+ 'Enable TUI clipboard writes in Terminal settings to copy from SSH, tmux, Neovim, fzf, or Grok.'
),
duration: 12_000,
action: {
diff --git a/src/renderer/src/components/terminal-pane/terminal-http-link-activation.test.ts b/src/renderer/src/components/terminal-pane/terminal-http-link-activation.test.ts
new file mode 100644
index 00000000000..ca11b713450
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-http-link-activation.test.ts
@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { isTerminalHttpLinkActivation } from './terminal-http-link-activation'
+
+afterEach(() => {
+ vi.unstubAllGlobals()
+})
+
+describe('isTerminalHttpLinkActivation', () => {
+ it('leaves Alt+Cmd gestures to the child TUI on macOS', () => {
+ vi.stubGlobal('navigator', { userAgent: 'Macintosh' })
+
+ expect(
+ isTerminalHttpLinkActivation({ metaKey: true, ctrlKey: false, altKey: false } as MouseEvent)
+ ).toBe(true)
+ expect(
+ isTerminalHttpLinkActivation({ metaKey: true, ctrlKey: false, altKey: true } as MouseEvent)
+ ).toBe(false)
+ })
+
+ it('leaves Alt+Ctrl gestures to the child TUI on other platforms', () => {
+ vi.stubGlobal('navigator', { userAgent: 'Windows' })
+
+ expect(
+ isTerminalHttpLinkActivation({ metaKey: false, ctrlKey: true, altKey: false } as MouseEvent)
+ ).toBe(true)
+ expect(
+ isTerminalHttpLinkActivation({ metaKey: false, ctrlKey: true, altKey: true } as MouseEvent)
+ ).toBe(false)
+ })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-http-link-activation.ts b/src/renderer/src/components/terminal-pane/terminal-http-link-activation.ts
new file mode 100644
index 00000000000..c9e941c874d
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-http-link-activation.ts
@@ -0,0 +1,7 @@
+import { isTerminalLinkActivation } from './terminal-link-activation'
+
+export function isTerminalHttpLinkActivation(event: MouseEvent | undefined): boolean {
+ // Why: xterm deliberately forwards Alt-modified mouse gestures to the PTY,
+ // so plain HTTP link handling must leave those gestures to the child TUI.
+ return Boolean(event && !event.altKey && isTerminalLinkActivation(event))
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-http-link-limits.ts b/src/renderer/src/components/terminal-pane/terminal-http-link-limits.ts
new file mode 100644
index 00000000000..52cc2cf1e93
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-http-link-limits.ts
@@ -0,0 +1,5 @@
+export const TERMINAL_HTTP_URL_MAX_LENGTH = 2048
+
+// Why: punctuation can form a valid one-character continuation row, so the
+// URL length limit is also the only complete finite bound on framed rows.
+export const TERMINAL_HTTP_URL_MAX_HARD_WRAPPED_ROWS = TERMINAL_HTTP_URL_MAX_LENGTH
diff --git a/src/renderer/src/components/terminal-pane/terminal-link-pty-mouse-suppression.ts b/src/renderer/src/components/terminal-pane/terminal-link-pty-mouse-suppression.ts
new file mode 100644
index 00000000000..e595974bc18
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-link-pty-mouse-suppression.ts
@@ -0,0 +1,59 @@
+import type { IDisposable, Terminal } from '@xterm/xterm'
+import { isTerminalHttpLinkActivation } from './terminal-http-link-activation'
+
+const CAPTURE_LISTENER_OPTIONS = { capture: true } as const
+
+export function installTerminalLinkPtyMouseSuppression(
+ terminal: Terminal,
+ shouldSuppressMouseEvent: (event: MouseEvent) => boolean
+): IDisposable {
+ const terminalElement = terminal.element
+ const ownerDocument = terminalElement?.ownerDocument
+ const ownerWindow = ownerDocument?.defaultView
+ let previousMouseEventsRequireAlt: boolean | null = null
+ let restoreQueued = false
+
+ const restore = (): void => {
+ restoreQueued = false
+ if (previousMouseEventsRequireAlt === null) {
+ return
+ }
+ terminal.options.mouseEventsRequireAlt = previousMouseEventsRequireAlt
+ previousMouseEventsRequireAlt = null
+ ownerDocument?.removeEventListener('mouseup', queueRestore)
+ ownerWindow?.removeEventListener('blur', restore)
+ }
+ const queueRestore = (): void => {
+ if (restoreQueued || previousMouseEventsRequireAlt === null) {
+ return
+ }
+ restoreQueued = true
+ queueMicrotask(restore)
+ }
+ const handleMouseDown = (event: MouseEvent): void => {
+ if (
+ event.button !== 0 ||
+ !isTerminalHttpLinkActivation(event) ||
+ !shouldSuppressMouseEvent(event)
+ ) {
+ return
+ }
+ restore()
+ previousMouseEventsRequireAlt = Boolean(terminal.options.mouseEventsRequireAlt)
+ // Why: xterm otherwise forwards the same Cmd/Ctrl link gesture to a mouse-aware
+ // TUI, letting the terminal and the child process both open the URL.
+ terminal.options.mouseEventsRequireAlt = true
+ ownerDocument?.addEventListener('mouseup', queueRestore)
+ ownerWindow?.addEventListener('blur', restore)
+ }
+
+ terminalElement?.addEventListener('mousedown', handleMouseDown, CAPTURE_LISTENER_OPTIONS)
+ terminalElement?.addEventListener('mouseup', queueRestore, CAPTURE_LISTENER_OPTIONS)
+ return {
+ dispose: () => {
+ restore()
+ terminalElement?.removeEventListener('mousedown', handleMouseDown, CAPTURE_LISTENER_OPTIONS)
+ terminalElement?.removeEventListener('mouseup', queueRestore, CAPTURE_LISTENER_OPTIONS)
+ }
+ }
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-mouse-buffer-position.ts b/src/renderer/src/components/terminal-pane/terminal-mouse-buffer-position.ts
new file mode 100644
index 00000000000..ee741dbbc4f
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-mouse-buffer-position.ts
@@ -0,0 +1,29 @@
+import type { Terminal } from '@xterm/xterm'
+
+export function getTerminalBufferPositionForMouseEvent(
+ terminal: Terminal,
+ event: MouseEvent
+): { x: number; y: number } | null {
+ const screenElement = terminal.element?.querySelector('.xterm-screen')
+ if (!screenElement || terminal.cols <= 0 || terminal.rows <= 0) {
+ return null
+ }
+
+ const rect = screenElement.getBoundingClientRect()
+ const relativeX = event.clientX - rect.left
+ const relativeY = event.clientY - rect.top
+ if (relativeX < 0 || relativeY < 0 || relativeX >= rect.width || relativeY >= rect.height) {
+ return null
+ }
+
+ const cellWidth = rect.width / terminal.cols
+ const cellHeight = rect.height / terminal.rows
+ if (cellWidth <= 0 || cellHeight <= 0) {
+ return null
+ }
+
+ return {
+ x: Math.floor(relativeX / cellWidth) + 1,
+ y: Math.floor(relativeY / cellHeight) + terminal.buffer.active.viewportY + 1
+ }
+}
diff --git a/src/renderer/src/components/terminal-pane/terminal-url-link-click.test.ts b/src/renderer/src/components/terminal-pane/terminal-url-link-click.test.ts
new file mode 100644
index 00000000000..c8e85950da3
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-url-link-click.test.ts
@@ -0,0 +1,429 @@
+import type { IBufferLine, Terminal } from '@xterm/xterm'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerHttpLinkStoreAccessor } from '@/lib/http-link-routing'
+import { handleTerminalWebLinkClick } from './terminal-web-link-click'
+import { installHttpLinkClickFallback } from './terminal-url-link-hit-testing'
+
+const COLS = 157
+const ROWS = 59
+const INDENT = ''
+const FULL_URL = [
+ 'http://127.0.0.1:8765/orca-double-open-repro-wrapped/',
+ Array.from({ length: 79 }, (_value, index) => `seg${String(index + 1).padStart(4, '0')}`).join(
+ '/'
+ ),
+ '?marker=wrap-test&n=001&pad=',
+ 'x'.repeat(120)
+].join('')
+const URL_ROWS = Array.from({ length: Math.ceil(FULL_URL.length / COLS) }, (_value, index) =>
+ FULL_URL.slice(index * COLS, (index + 1) * COLS)
+)
+const FRAMED_ROW_STARTS = [
+ 0,
+ FULL_URL.indexOf('seg0008/'),
+ FULL_URL.indexOf('seg0022/'),
+ FULL_URL.indexOf('seg0036/'),
+ FULL_URL.indexOf('seg0050/'),
+ FULL_URL.indexOf('seg0064/'),
+ FULL_URL.indexOf('seg0078/'),
+ FULL_URL.indexOf('test&n=001'),
+ FULL_URL.length - 19
+]
+const FRAMED_URL_ROWS = FRAMED_ROW_STARTS.map((start, index) =>
+ FULL_URL.slice(start, FRAMED_ROW_STARTS[index + 1])
+)
+
+const openUrlMock = vi.fn()
+
+type ListenerRegistration = [string, EventListener, AddEventListenerOptions | boolean | undefined]
+
+function makeBufferLine(
+ fragment: string,
+ options: { cols?: number; prefix?: string; suffix?: string; isWrapped?: boolean } = {}
+): IBufferLine {
+ const cols = options.cols ?? COLS
+ const prefix = options.prefix ?? INDENT
+ const suffix = options.suffix ?? ''
+ const text = `${prefix}${fragment}`.padEnd(cols - suffix.length) + suffix
+ return {
+ isWrapped: options.isWrapped ?? false,
+ length: cols,
+ translateToString: (
+ _trimRight?: boolean,
+ startColumn = 0,
+ endColumn = text.length,
+ outColumns?: number[]
+ ) => {
+ if (outColumns) {
+ outColumns.splice(
+ 0,
+ outColumns.length,
+ ...Array.from(
+ { length: endColumn - startColumn + 1 },
+ (_value, index) => index + startColumn
+ )
+ )
+ }
+ return text.slice(startColumn, endColumn)
+ }
+ } as IBufferLine
+}
+
+function makeTerminal(options?: {
+ cols?: number
+ rows?: number
+ urlRows?: string[]
+ linePrefix?: string
+ lineSuffix?: string
+ softWrapped?: boolean
+}): {
+ terminal: Terminal
+ registrations: ListenerRegistration[]
+ clearSelection: ReturnType
+} {
+ const cols = options?.cols ?? COLS
+ const rows = options?.rows ?? ROWS
+ const urlRows = options?.urlRows ?? URL_ROWS
+ const registrations: ListenerRegistration[] = []
+ const ownerWindow = {
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn()
+ }
+ const ownerDocument = {
+ defaultView: ownerWindow,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn()
+ }
+ const screen = {
+ getBoundingClientRect: () => ({ left: 0, top: 0, width: cols * 10, height: rows * 10 })
+ }
+ const element = {
+ ownerDocument,
+ querySelector: vi.fn(() => screen),
+ addEventListener: vi.fn(
+ (name: string, listener: EventListener, options?: AddEventListenerOptions | boolean) => {
+ registrations.push([name, listener, options])
+ }
+ ),
+ removeEventListener: vi.fn()
+ }
+ const clearSelection = vi.fn()
+ return {
+ terminal: {
+ cols,
+ rows,
+ options: { mouseEventsRequireAlt: false },
+ element,
+ buffer: {
+ active: {
+ viewportY: 0,
+ getLine: (y: number) =>
+ urlRows[y] &&
+ makeBufferLine(urlRows[y], {
+ cols,
+ prefix: options?.linePrefix,
+ suffix: options?.lineSuffix,
+ isWrapped: (options?.softWrapped ?? true) && y > 0
+ })
+ }
+ },
+ clearSelection
+ } as unknown as Terminal,
+ registrations,
+ clearSelection
+ }
+}
+
+function mouseEventForRow(row: number, options: { altKey?: boolean } = {}): MouseEvent {
+ let defaultPrevented = false
+ return {
+ button: 0,
+ metaKey: true,
+ ctrlKey: false,
+ altKey: options.altKey ?? false,
+ shiftKey: true,
+ get defaultPrevented() {
+ return defaultPrevented
+ },
+ clientX: 150,
+ clientY: row * 10 + 5,
+ preventDefault: vi.fn(() => {
+ defaultPrevented = true
+ })
+ } as unknown as MouseEvent
+}
+
+describe('hard-wrapped terminal HTTP clicks', () => {
+ beforeEach(() => {
+ vi.stubGlobal('navigator', { userAgent: 'Macintosh' })
+ vi.stubGlobal('window', { api: { shell: { openUrl: openUrlMock } } })
+ registerHttpLinkStoreAccessor(() => ({
+ settings: { openLinksInApp: false },
+ setActiveWorktree: vi.fn(),
+ createBrowserTab: vi.fn()
+ }))
+ openUrlMock.mockReset()
+ })
+
+ afterEach(() => {
+ vi.unstubAllGlobals()
+ })
+
+ it('opens the full logical URL once when WebLinksAddon reports only the first row', () => {
+ const { terminal, registrations, clearSelection } = makeTerminal()
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+ const event = mouseEventForRow(0)
+
+ expect(
+ handleTerminalWebLinkClick(URL_ROWS[0], event, {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+
+ const fallback = registrations.find(
+ ([name, _listener, options]) => name === 'mouseup' && options === undefined
+ )?.[1]
+ expect(fallback).toBeDefined()
+ fallback!(event)
+
+ expect(openUrlMock).toHaveBeenCalledTimes(1)
+ expect(openUrlMock).toHaveBeenCalledWith(FULL_URL)
+ expect(new URL(URL_ROWS[0]).pathname).toHaveLength(136)
+ expect(`${new URL(FULL_URL).pathname}${new URL(FULL_URL).search}`).toHaveLength(811)
+ expect(event.preventDefault).toHaveBeenCalled()
+ expect(clearSelection).toHaveBeenCalled()
+ disposable.dispose()
+ })
+
+ it('opens the same full URL from a continuation-row fallback click', () => {
+ const { terminal, registrations } = makeTerminal()
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+ const event = mouseEventForRow(3)
+ const fallback = registrations.find(
+ ([name, _listener, options]) => name === 'mouseup' && options === undefined
+ )?.[1]
+
+ fallback!(event)
+
+ expect(openUrlMock).toHaveBeenCalledTimes(1)
+ expect(openUrlMock).toHaveBeenCalledWith(FULL_URL)
+ disposable.dispose()
+ })
+
+ it('reconstructs a URL split across cursor-positioned rows inside a TUI frame', () => {
+ const { terminal } = makeTerminal({
+ cols: 135,
+ urlRows: FRAMED_URL_ROWS,
+ linePrefix: ' │ ',
+ lineSuffix: '│ ',
+ softWrapped: false
+ })
+ const event = mouseEventForRow(0)
+
+ expect(
+ handleTerminalWebLinkClick(FRAMED_URL_ROWS[0], event, {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+
+ expect(openUrlMock).toHaveBeenCalledTimes(1)
+ expect(openUrlMock).toHaveBeenCalledWith(FULL_URL)
+ expect(new URL(FRAMED_URL_ROWS[0]).pathname).toHaveLength(88)
+ })
+
+ it('reconstructs a URL that fills each cursor-positioned TUI row up to its frame', () => {
+ const cols = 135
+ const linePrefix = ' │ '
+ const lineSuffix = '│ '
+ const contentWidth = cols - linePrefix.length - lineSuffix.length
+ const fullWidthRows = Array.from(
+ { length: Math.ceil(FULL_URL.length / contentWidth) },
+ (_value, index) => FULL_URL.slice(index * contentWidth, (index + 1) * contentWidth)
+ )
+ const { terminal } = makeTerminal({
+ cols,
+ urlRows: fullWidthRows,
+ linePrefix,
+ lineSuffix,
+ softWrapped: false
+ })
+
+ expect(
+ handleTerminalWebLinkClick(fullWidthRows[0], mouseEventForRow(0), {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+
+ expect(openUrlMock).toHaveBeenCalledTimes(1)
+ expect(openUrlMock).toHaveBeenCalledWith(FULL_URL)
+ })
+
+ it('reconstructs supported URLs spanning more than twenty framed rows', () => {
+ const cols = 80
+ const linePrefix = ' │ '
+ const lineSuffix = '│ '
+ const contentWidth = cols - linePrefix.length - lineSuffix.length
+ const longUrl = `http://example.com/${'a'.repeat(contentWidth * 20)}`
+ const urlRows = Array.from(
+ { length: Math.ceil(longUrl.length / contentWidth) },
+ (_value, index) => longUrl.slice(index * contentWidth, (index + 1) * contentWidth)
+ )
+ const { terminal } = makeTerminal({
+ cols,
+ urlRows,
+ linePrefix,
+ lineSuffix,
+ softWrapped: false
+ })
+
+ expect(urlRows).toHaveLength(21)
+ expect(
+ handleTerminalWebLinkClick(urlRows[0], mouseEventForRow(0), {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+ expect(openUrlMock).toHaveBeenCalledWith(longUrl)
+ })
+
+ it('keeps nested HTTP URLs inside a wrapped query parameter', () => {
+ const cols = 80
+ const linePrefix = ' │ '
+ const lineSuffix = '│ '
+ const contentWidth = cols - linePrefix.length - lineSuffix.length
+ const firstRow = `http://example.com/${'a'.repeat(contentWidth - 'http://example.com/'.length)}`
+ const nestedQuery = 'segment?redirect=https://nested.example/path'
+ const secondRow = `${nestedQuery}${'b'.repeat(contentWidth - nestedQuery.length)}`
+ const urlRows = [firstRow, secondRow, 'tail']
+ const fullUrl = urlRows.join('')
+ const { terminal } = makeTerminal({
+ cols,
+ urlRows,
+ linePrefix,
+ lineSuffix,
+ softWrapped: false
+ })
+
+ expect(
+ handleTerminalWebLinkClick(firstRow, mouseEventForRow(0), {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+ expect(openUrlMock).toHaveBeenCalledWith(fullUrl)
+ })
+
+ it('does not append an unrelated aligned TUI row to a complete URL', () => {
+ const { terminal, registrations } = makeTerminal({
+ cols: 135,
+ urlRows: ['http://example.com/', 'next-token'],
+ linePrefix: ' │ ',
+ lineSuffix: '│ ',
+ softWrapped: false
+ })
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+
+ expect(
+ handleTerminalWebLinkClick('http://example.com/', mouseEventForRow(0), {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+ expect(openUrlMock).toHaveBeenCalledOnce()
+ expect(openUrlMock).toHaveBeenCalledWith('http://example.com/')
+
+ openUrlMock.mockReset()
+ const fallback = registrations.find(
+ ([name, _listener, options]) => name === 'mouseup' && options === undefined
+ )?.[1]
+ fallback!(mouseEventForRow(1))
+ expect(openUrlMock).not.toHaveBeenCalled()
+ disposable.dispose()
+ })
+
+ it('does not join a complete URL to multiple unrelated framed rows', () => {
+ const unrelatedFilledRow = 'a'.repeat(103)
+ const { terminal } = makeTerminal({
+ cols: 110,
+ urlRows: ['http://example.com/', unrelatedFilledRow, 'unrelated'],
+ linePrefix: ' │ ',
+ lineSuffix: '│ ',
+ softWrapped: false
+ })
+
+ expect(
+ handleTerminalWebLinkClick('http://example.com/', mouseEventForRow(0), {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(true)
+
+ expect(openUrlMock).toHaveBeenCalledOnce()
+ expect(openUrlMock).toHaveBeenCalledWith('http://example.com/')
+ })
+
+ it('does not suppress a modifier-click when the buffer position is not an HTTP link', () => {
+ const { terminal, registrations } = makeTerminal({ urlRows: ['not-a-link'] })
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+ const mouseDown = registrations.find(([name]) => name === 'mousedown')?.[1]
+
+ mouseDown!(mouseEventForRow(0))
+
+ expect(terminal.options.mouseEventsRequireAlt).toBe(false)
+ disposable.dispose()
+ })
+
+ it('leaves Alt-modified link gestures to the child TUI', () => {
+ const { terminal, registrations } = makeTerminal()
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+ const mouseDown = registrations.find(([name]) => name === 'mousedown')?.[1]
+ const event = mouseEventForRow(0, { altKey: true })
+
+ mouseDown!(event)
+ expect(terminal.options.mouseEventsRequireAlt).toBe(false)
+ expect(
+ handleTerminalWebLinkClick(URL_ROWS[0], event, {
+ terminal,
+ worktreeId: 'wt-1',
+ worktreePath: '/tmp',
+ startupCwd: '/tmp'
+ })
+ ).toBe(false)
+ expect(openUrlMock).not.toHaveBeenCalled()
+ disposable.dispose()
+ })
+
+ it('temporarily suppresses PTY mouse reporting at an HTTP link position', async () => {
+ const { terminal, registrations } = makeTerminal()
+ const disposable = installHttpLinkClickFallback(terminal, { worktreeId: 'wt-1' })
+ const mouseDown = registrations.find(([name]) => name === 'mousedown')?.[1]
+ const mouseUp = registrations.find(
+ ([name, _listener, options]) => name === 'mouseup' && options !== undefined
+ )?.[1]
+
+ mouseDown!(mouseEventForRow(0))
+ expect(terminal.options.mouseEventsRequireAlt).toBe(true)
+
+ mouseUp!(mouseEventForRow(0))
+ await Promise.resolve()
+ expect(terminal.options.mouseEventsRequireAlt).toBe(false)
+ disposable.dispose()
+ })
+})
diff --git a/src/renderer/src/components/terminal-pane/terminal-url-link-hit-testing.ts b/src/renderer/src/components/terminal-pane/terminal-url-link-hit-testing.ts
index 67505d5f622..bfbbe29f723 100644
--- a/src/renderer/src/components/terminal-pane/terminal-url-link-hit-testing.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-url-link-hit-testing.ts
@@ -1,8 +1,15 @@
import type { IBufferLine, IBufferRange, IDisposable, Terminal } from '@xterm/xterm'
import { openHttpLink } from '@/lib/http-link-routing'
-import { buildCandidateLogicalLinesForBufferPosition } from './terminal-file-link-hit-testing'
-import { isTerminalLinkActivation } from './terminal-link-activation'
-import { rangeForParsedFileLink } from './wrapped-terminal-link-ranges'
+import {
+ buildCandidateLogicalLinesForBufferPosition,
+ dedupeLogicalLines
+} from './terminal-file-link-hit-testing'
+import { buildHardWrappedHttpLogicalLineCandidates } from './hard-wrapped-terminal-http-links'
+import { isTerminalHttpLinkActivation } from './terminal-http-link-activation'
+import { installTerminalLinkPtyMouseSuppression } from './terminal-link-pty-mouse-suppression'
+import { getTerminalBufferPositionForMouseEvent } from './terminal-mouse-buffer-position'
+import { TERMINAL_HTTP_URL_MAX_LENGTH } from './terminal-http-link-limits'
+import { buildWrappedLogicalLine, rangeForParsedFileLink } from './wrapped-terminal-link-ranges'
type UrlLinkHitTestDeps = {
worktreeId: string
@@ -26,7 +33,7 @@ type ParsedTerminalHttpLink = {
}
const HTTP_SCHEME_PREFIXES = ['https://', 'http://'] as const
-export const TERMINAL_HTTP_URL_MAX_LENGTH = 2048
+export { TERMINAL_HTTP_URL_MAX_LENGTH } from './terminal-http-link-limits'
export function extractTerminalHttpLinks(lineText: string): ParsedTerminalHttpLink[] {
const links: ParsedTerminalHttpLink[] = []
@@ -56,7 +63,7 @@ function isDesktopHttpLinkFallbackActivation(event: MouseEvent): boolean {
// Why: desktop terminal links require an intentional Cmd/Ctrl gesture so
// plain clicks remain available for cursor placement and selection. Mobile
// tap routing is handled separately under mobile/src/terminal.
- return isTerminalLinkActivation(event)
+ return isTerminalHttpLinkActivation(event)
}
function* iterateTerminalHttpUrlCandidates(
@@ -185,56 +192,40 @@ function isAsciiWordCode(code: number): boolean {
)
}
-function getTerminalScreenElement(terminal: Terminal): HTMLElement | null {
- return terminal.element?.querySelector('.xterm-screen') ?? null
-}
-
-function getBufferPositionForTerminalMouseEvent(
+export function openHttpLinkAtTerminalMouseEvent(
terminal: Terminal,
- event: MouseEvent
-): { x: number; y: number } | null {
- const screenElement = getTerminalScreenElement(terminal)
- if (!screenElement || terminal.cols <= 0 || terminal.rows <= 0) {
- return null
+ event: MouseEvent,
+ deps: UrlLinkHitTestDeps
+): boolean {
+ if (event.button !== 0 || !isTerminalHttpLinkActivation(event)) {
+ return false
}
-
- const rect = screenElement.getBoundingClientRect()
- const relativeX = event.clientX - rect.left
- const relativeY = event.clientY - rect.top
- if (relativeX < 0 || relativeY < 0 || relativeX >= rect.width || relativeY >= rect.height) {
- return null
- }
-
- const cellWidth = rect.width / terminal.cols
- const cellHeight = rect.height / terminal.rows
- if (cellWidth <= 0 || cellHeight <= 0) {
- return null
- }
-
- return {
- x: Math.floor(relativeX / cellWidth) + 1,
- y: Math.floor(relativeY / cellHeight) + terminal.buffer.active.viewportY + 1
+ const position = getTerminalBufferPositionForMouseEvent(terminal, event)
+ if (!position) {
+ return false
}
+ return openHttpLinkAtBufferPosition(terminal.buffer.active, position, terminal.cols, deps)
}
export function installHttpLinkClickFallback(
terminal: Terminal,
deps: UrlLinkClickFallbackDeps
): IDisposable {
+ const ptyMouseSuppression = installTerminalLinkPtyMouseSuppression(terminal, (event) => {
+ const position = getTerminalBufferPositionForMouseEvent(terminal, event)
+ return Boolean(
+ position && findHttpLinkAtBufferPosition(terminal.buffer.active, position, terminal.cols)
+ )
+ })
const handleMouseUp = (event: MouseEvent): void => {
if (!isDesktopHttpLinkFallbackActivation(event)) {
return
}
- const position = getBufferPositionForTerminalMouseEvent(terminal, event)
- if (!position) {
- return
- }
-
// Why: xterm's WebLinksAddon only activates after hover state exists. This
// direct mouseup fallback preserves modifier-clicks when the hover link was
// never established, while defaultPrevented avoids duplicate opens.
- const opened = openHttpLinkAtBufferPosition(terminal.buffer.active, position, terminal.cols, {
+ const opened = openHttpLinkAtTerminalMouseEvent(terminal, event, {
worktreeId: deps.worktreeId,
forceSystemBrowser: event.shiftKey,
requestOpenLinksInAppPreference: deps.requestOpenLinksInAppPreference
@@ -249,6 +240,7 @@ export function installHttpLinkClickFallback(
terminalElement?.addEventListener('mouseup', handleMouseUp)
return {
dispose: () => {
+ ptyMouseSuppression.dispose()
terminalElement?.removeEventListener('mouseup', handleMouseUp)
}
}
@@ -260,10 +252,30 @@ export function openHttpLinkAtBufferPosition(
terminalColumns: number,
deps: UrlLinkHitTestDeps
): boolean {
- const logicalLines = buildCandidateLogicalLinesForBufferPosition(buffer, position.y)
- if (logicalLines.length === 0) {
+ const url = findHttpLinkAtBufferPosition(buffer, position, terminalColumns)
+ if (!url) {
return false
}
+ openTerminalHttpLink(url, deps)
+ return true
+}
+
+function findHttpLinkAtBufferPosition(
+ buffer: { getLine(y: number): IBufferLine | undefined },
+ position: { x: number; y: number },
+ terminalColumns: number
+): string | null {
+ const nativeWrappedLogicalLine = buildWrappedLogicalLine(buffer, position.y)
+ const logicalLines = dedupeLogicalLines([
+ ...(nativeWrappedLogicalLine && nativeWrappedLogicalLine.rows.length > 1
+ ? [nativeWrappedLogicalLine]
+ : []),
+ ...buildHardWrappedHttpLogicalLineCandidates(buffer, position.y),
+ ...buildCandidateLogicalLinesForBufferPosition(buffer, position.y)
+ ])
+ if (logicalLines.length === 0) {
+ return null
+ }
for (const logicalLine of logicalLines) {
for (const parsed of extractTerminalHttpLinks(logicalLine.text)) {
@@ -271,12 +283,11 @@ export function openHttpLinkAtBufferPosition(
if (!range || !rangeContainsBufferPosition(range, position, terminalColumns)) {
continue
}
- openTerminalHttpLink(parsed.url, deps)
- return true
+ return parsed.url
}
}
- return false
+ return null
}
export function openTerminalHttpLink(url: string, deps: UrlLinkHitTestDeps): void {
diff --git a/src/renderer/src/components/terminal-pane/terminal-web-link-click.ts b/src/renderer/src/components/terminal-pane/terminal-web-link-click.ts
new file mode 100644
index 00000000000..c512cc84126
--- /dev/null
+++ b/src/renderer/src/components/terminal-pane/terminal-web-link-click.ts
@@ -0,0 +1,50 @@
+import type { Terminal } from '@xterm/xterm'
+import type { LinkHandlerDeps } from './terminal-link-handlers'
+import { isTerminalHttpLinkActivation } from './terminal-http-link-activation'
+import { handleOscLink } from './terminal-osc-link-routing'
+import {
+ openHttpLinkAtTerminalMouseEvent,
+ type TerminalLinkRoutingPreferenceRequester
+} from './terminal-url-link-hit-testing'
+
+type TerminalWebLinkClickDeps = Pick<
+ LinkHandlerDeps,
+ 'worktreeId' | 'worktreePath' | 'startupCwd' | 'runtimeEnvironmentId' | 'terminalHomePath'
+> & {
+ terminal: Terminal | null
+ requestOpenLinksInAppPreference?: TerminalLinkRoutingPreferenceRequester
+}
+
+export function handleTerminalWebLinkClick(
+ url: string,
+ event: MouseEvent | undefined,
+ deps: TerminalWebLinkClickDeps
+): boolean {
+ if (!event || !isTerminalHttpLinkActivation(event)) {
+ return false
+ }
+
+ let handled: boolean
+ if (
+ deps.terminal &&
+ openHttpLinkAtTerminalMouseEvent(deps.terminal, event, {
+ worktreeId: deps.worktreeId,
+ forceSystemBrowser: Boolean(event.shiftKey),
+ requestOpenLinksInAppPreference: deps.requestOpenLinksInAppPreference
+ })
+ ) {
+ // Why: WebLinksAddon only knows the physical row; Orca's logical hit-test
+ // preserves the complete URL rendered across hard-wrapped TUI rows.
+ event.preventDefault()
+ handled = true
+ } else {
+ handled = handleOscLink(url, event, deps)
+ }
+
+ if (handled) {
+ // Why: link navigation can steal focus before xterm's mouseup cleanup;
+ // clearing selection also detaches its pending drag-selection listeners.
+ deps.terminal?.clearSelection()
+ }
+ return handled
+}
diff --git a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
index 5f68494ba15..5a64694000e 100644
--- a/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
+++ b/src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
@@ -31,6 +31,7 @@ import {
import { createTerminalHandleLinkProvider } from './terminal-handle-links'
import type { LinkHandlerDeps } from './terminal-link-handlers'
import { handleOscLink } from './terminal-osc-link-routing'
+import { handleTerminalWebLinkClick } from './terminal-web-link-click'
import {
installHttpLinkClickFallback,
type TerminalLinkRoutingPreferenceRequester
@@ -1480,28 +1481,16 @@ export function useTerminalPaneLifecycle({
terminalTuiScrollSensitivity: () =>
normalizeTerminalTuiMouseWheelMultiplier(settingsRef.current?.terminalTuiScrollSensitivity),
onLinkClick: (event, url) => {
- if (!event) {
- return
- }
const activePane = managerRef.current?.getActivePane()
- const handled = handleOscLink(url, event, {
+ handleTerminalWebLinkClick(url, event, {
...linkDeps,
+ terminal: activePane?.terminal ?? null,
startupCwd: activePane ? getPaneLinkCwd(activePane.id) : startupCwd,
runtimeEnvironmentId: activePane
? (linkDeps.getRuntimeEnvironmentIdForPane?.(activePane.id) ?? null)
: null,
requestOpenLinksInAppPreference
})
- // Why: Cmd/Ctrl+click on a plain-text URL (WebLinksAddon) takes focus
- // away from the terminal before the click's mouseup reaches
- // ownerDocument. That leaves xterm's SelectionService drag-select
- // mousemove listener attached, so subsequent mouse motion extends a
- // phantom selection until the next click/Esc. Explicitly clearing the
- // selection also detaches those listeners (see
- // SelectionService._removeMouseDownListeners).
- if (handled) {
- managerRef.current?.getActivePane()?.terminal.clearSelection()
- }
},
formatLinkTooltip: (url, openLinkHint) => formatTerminalUrlTooltip(url, openLinkHint),
// Why: TerminalPane instances stay mounted for hidden visited worktrees
diff --git a/src/renderer/src/components/terminal-pane/wrapped-terminal-link-ranges.ts b/src/renderer/src/components/terminal-pane/wrapped-terminal-link-ranges.ts
index b648950bcd0..b94affd030b 100644
--- a/src/renderer/src/components/terminal-pane/wrapped-terminal-link-ranges.ts
+++ b/src/renderer/src/components/terminal-pane/wrapped-terminal-link-ranges.ts
@@ -65,7 +65,7 @@ function translateLineWithCells(line: IBufferLine): { text: string; columns: num
return { text, columns }
}
-function translateLineWithColumns(line: IBufferLine): { text: string; columns: number[] } {
+export function translateLineWithColumns(line: IBufferLine): { text: string; columns: number[] } {
const columns: number[] = []
const text = (line as TerminalBufferLineWithColumns).translateToString(
false,
diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json
index 2434660b84a..40492be7b71 100644
--- a/src/renderer/src/i18n/locales/en.json
+++ b/src/renderer/src/i18n/locales/en.json
@@ -2588,7 +2588,7 @@
"blocked": {
"toast": {
"97c98f1afe": "Open Setting",
- "7cf51f74fd": "Enable TUI clipboard writes in Terminal settings to copy from SSH, tmux, Neovim, or fzf.",
+ "7cf51f74fd": "Enable TUI clipboard writes in Terminal settings to copy from SSH, tmux, Neovim, fzf, or Grok.",
"89eaa3e80b": "Terminal clipboard write blocked"
}
}
diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json
index a216c3dfe1c..f909b7687b9 100644
--- a/src/renderer/src/i18n/locales/es.json
+++ b/src/renderer/src/i18n/locales/es.json
@@ -2588,7 +2588,7 @@
"blocked": {
"toast": {
"97c98f1afe": "Abrir ajustes",
- "7cf51f74fd": "Habilita las escrituras al portapapeles TUI en los ajustes de Terminal para copiar desde SSH, tmux, Neovim o fzf.",
+ "7cf51f74fd": "Habilita las escrituras al portapapeles TUI en los ajustes de Terminal para copiar desde SSH, tmux, Neovim, fzf o Grok.",
"89eaa3e80b": "Escritura al portapapeles del terminal bloqueada"
}
}
diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json
index 641d28e1489..33bc07fbfd1 100644
--- a/src/renderer/src/i18n/locales/ja.json
+++ b/src/renderer/src/i18n/locales/ja.json
@@ -2588,7 +2588,7 @@
"blocked": {
"toast": {
"97c98f1afe": "設定を開く",
- "7cf51f74fd": "SSH、tmux、Neovim、または fzf からコピーするには、Terminal 設定で TUI クリップボードへの書き込みを有効にします。",
+ "7cf51f74fd": "SSH、tmux、Neovim、fzf、または Grok からコピーするには、Terminal 設定で TUI クリップボードへの書き込みを有効にします。",
"89eaa3e80b": "Terminal のクリップボードへの書き込みがブロックされました"
}
}
diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json
index c159ed4759b..67187a4b21c 100644
--- a/src/renderer/src/i18n/locales/ko.json
+++ b/src/renderer/src/i18n/locales/ko.json
@@ -2588,7 +2588,7 @@
"blocked": {
"toast": {
"97c98f1afe": "설정 열기",
- "7cf51f74fd": "SSH, tmux, Neovim 또는 fzf에서 복사하려면 Terminal 설정에서 TUI 클립보드 쓰기를 활성화하세요.",
+ "7cf51f74fd": "SSH, tmux, Neovim, fzf 또는 Grok에서 복사하려면 Terminal 설정에서 TUI 클립보드 쓰기를 활성화하세요.",
"89eaa3e80b": "Terminal 클립보드 쓰기가 차단되었습니다."
}
}
diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json
index 3b1c79a3428..dbf29920404 100644
--- a/src/renderer/src/i18n/locales/zh.json
+++ b/src/renderer/src/i18n/locales/zh.json
@@ -2588,7 +2588,7 @@
"blocked": {
"toast": {
"97c98f1afe": "打开设置",
- "7cf51f74fd": "在终端设置中启用 TUI 剪贴板写入，以从 SSH、tmux、Neovim 或 fzf 进行复制。",
+ "7cf51f74fd": "在终端设置中启用 TUI 剪贴板写入，以从 SSH、tmux、Neovim、fzf 或 Grok 进行复制。",
"89eaa3e80b": "终端剪贴板写入被阻止"
}
}
diff --git a/src/renderer/src/lib/agent-catalog.tsx b/src/renderer/src/lib/agent-catalog.tsx
index d43401e502f..f9536dc1c34 100644
--- a/src/renderer/src/lib/agent-catalog.tsx
+++ b/src/renderer/src/lib/agent-catalog.tsx
@@ -14,6 +14,7 @@ import {
} from './agent-icon-glyphs'
import { translate } from '@/i18n/i18n'
import { createLocalizedCatalog } from '@/i18n/localized-catalog'
+import { AGENT_FAVICON_ASSETS } from './agent-favicon-assets'
export type AgentCatalogEntry = {
id: TuiAgent
@@ -113,7 +114,8 @@ export const getAgentCatalog = createLocalizedCatalog((): AgentCatalogEntry[] =>
id: 'omp',
label: translate('auto.lib.agent.catalog.09973b4d84', 'OMP'),
cmd: 'omp',
- faviconDomain: 'omp.sh',
+ // Why: no faviconDomain — omp renders the hand-authored OmpIcon glyph, so a
+ // favicon fallback would never be reached.
homepageUrl: 'https://omp.sh'
},
{
@@ -340,20 +342,29 @@ export function AgentIcon({
return ![]()
`.
+ const iconSrc = catalogEntry?.iconUrl ?? bundledFaviconUrl
+ if (iconSrc) {
return (
)
}
if (catalogEntry?.faviconDomain) {
- // Why: agents without a published SVG icon use their site favicon via
- // Google's favicon service — same source the README uses for the agent badge list.
+ // Why: agents without a published SVG icon or bundled favicon fall back to
+ // their site favicon via Google's favicon service — same source the README
+ // uses for the agent badge list.
return (
> = {
+ grok: grokUrl,
+ 'mimo-code': mimoCodeUrl,
+ ante: anteUrl,
+ gemini: geminiUrl,
+ antigravity: antigravityUrl,
+ goose: gooseUrl,
+ amp: ampUrl,
+ kiro: kiroUrl,
+ crush: crushUrl,
+ aug: augUrl,
+ autohand: autohandUrl,
+ cline: clineUrl,
+ codebuff: codebuffUrl,
+ 'command-code': commandCodeUrl,
+ continue: continueUrl,
+ cursor: cursorUrl,
+ kimi: kimiUrl,
+ 'mistral-vibe': mistralVibeUrl,
+ 'qwen-code': qwenCodeUrl,
+ rovo: rovoUrl,
+ hermes: hermesUrl,
+ devin: devinUrl,
+ openclaw: openclawUrl
+}
diff --git a/src/shared/agent-hook-listener.test.ts b/src/shared/agent-hook-listener.test.ts
index 083783328d3..a593d3bcae9 100644
--- a/src/shared/agent-hook-listener.test.ts
+++ b/src/shared/agent-hook-listener.test.ts
@@ -1639,6 +1639,44 @@ describe('shared agent-hook-listener', () => {
expect(event?.payload.interactivePrompt).toBeUndefined()
})
+ it('surfaces the Grok tool-failure error and clears stale tool fields', () => {
+ normalizeHookPayload(
+ state,
+ 'grok',
+ {
+ paneKey: PANE_KEY,
+ payload: {
+ hookEventName: 'pre_tool_use',
+ toolName: 'run_terminal_command',
+ toolInput: { command: 'pnpm build' }
+ }
+ },
+ 'production'
+ )
+ const failed = normalizeHookPayload(
+ state,
+ 'grok',
+ {
+ paneKey: PANE_KEY,
+ payload: {
+ hookEventName: 'post_tool_use_failure',
+ toolName: 'run_terminal_command',
+ toolInput: { command: 'pnpm build' },
+ error: 'command exited with code 1'
+ }
+ },
+ 'production'
+ )
+ // Why: keeping toolName set would let the compact sidebar show the tool
+ // instead of the failure text, hiding the error from the user.
+ expect(failed?.payload).toMatchObject({
+ state: 'working',
+ lastAssistantMessage: 'command exited with code 1'
+ })
+ expect(failed?.payload.toolName).toBeUndefined()
+ expect(failed?.payload.toolInput).toBeUndefined()
+ })
+
it('maps Grok StopFailure to done', () => {
normalizeHookPayload(
state,
diff --git a/src/shared/agent-hook-listener.ts b/src/shared/agent-hook-listener.ts
index 59724b64322..ce3e2f720a4 100644
--- a/src/shared/agent-hook-listener.ts
+++ b/src/shared/agent-hook-listener.ts
@@ -692,6 +692,17 @@ function toolUpdate(
}
}
+/** Clear the active-tool metadata (name/input/prompt) so a just-failed tool
+ * stops looking in-flight. Why: the compact sidebar prioritizes current-tool
+ * metadata over the failure message, so a completed failed tool must no
+ * longer look active or the error text stays hidden behind the tool name. */
+function clearActiveToolFieldsUpdate(): ToolSnapshot {
+ return toolUpdate(
+ { toolName: undefined, toolInput: undefined, interactivePrompt: undefined },
+ { hasToolInputField: true }
+ )
+}
+
/** True for the AskUserQuestion tool across the casing variants different
* agents emit (`AskUserQuestion` / `ask_user_question` / `askUserQuestion`).
* Why: this is the structured "pick an option" prompt whose full input the
@@ -1375,10 +1386,11 @@ function extractClaudeToolFields(
hookPayload: Record
): ToolSnapshot {
const update: ToolSnapshot = {}
- if (
+ if (eventName === 'PostToolUseFailure') {
+ Object.assign(update, clearActiveToolFieldsUpdate())
+ } else if (
eventName === 'PreToolUse' ||
eventName === 'PostToolUse' ||
- eventName === 'PostToolUseFailure' ||
eventName === 'PermissionRequest'
) {
const toolName = readString(hookPayload, 'tool_name')
@@ -1600,12 +1612,20 @@ function extractCursorToolFields(
eventName === 'postToolUse' ||
eventName === 'postToolUseFailure'
) {
- const toolName = readString(hookPayload, 'tool_name')
- const toolInput = deriveToolInputPreview(toolName, hookPayload.tool_input)
- const update: ToolSnapshot = toolUpdate(
- { toolName, toolInput },
- { hasToolInputField: hasOwnField(hookPayload, 'tool_input') }
- )
+ const update: ToolSnapshot = {}
+ if (eventName === 'postToolUseFailure') {
+ Object.assign(update, clearActiveToolFieldsUpdate())
+ } else {
+ const toolName = readString(hookPayload, 'tool_name')
+ const toolInput = deriveToolInputPreview(toolName, hookPayload.tool_input)
+ Object.assign(
+ update,
+ toolUpdate(
+ { toolName, toolInput },
+ { hasToolInputField: hasOwnField(hookPayload, 'tool_input') }
+ )
+ )
+ }
if (eventName === 'postToolUse') {
const responseText = extractToolResponseText(hookPayload.tool_output)
if (responseText) {
@@ -1750,10 +1770,11 @@ function extractCopilotToolFields(
hookPayload: Record
): ToolSnapshot {
const update: ToolSnapshot = {}
- if (
+ if (eventName === 'PostToolUseFailure' || eventName === 'ErrorOccurred') {
+ Object.assign(update, clearActiveToolFieldsUpdate())
+ } else if (
eventName === 'PreToolUse' ||
eventName === 'PostToolUse' ||
- eventName === 'PostToolUseFailure' ||
eventName === 'PermissionRequest'
) {
const copilotToolCall = readCopilotToolCall(hookPayload)
@@ -2016,29 +2037,40 @@ function extractGrokToolFields(
grokHome?: string
): ToolSnapshot {
if (isGrokEvent(eventName, 'pre_tool_use', 'post_tool_use', 'post_tool_use_failure')) {
- const toolName =
- readString(hookPayload, 'toolName') ??
- readString(hookPayload, 'tool_name') ??
- readString(hookPayload, 'name')
- const rawInput =
- hookPayload.toolInput ?? hookPayload.tool_input ?? hookPayload.input ?? hookPayload.arguments
- const toolInput =
- deriveToolInputPreview(toolName, rawInput) ?? deriveFallbackToolInputPreview(rawInput)
- // Why: Grok's ask_user_question is auto-allowed and arrives as PreToolUse
- // (not PermissionRequest). Capture the full question payload so the live
- // card path can render options instead of only a waiting Notification.
- const interactivePrompt = deriveInteractivePrompt(toolName, rawInput, eventName)
- const update: ToolSnapshot = toolUpdate(
- { toolName, toolInput, interactivePrompt },
- {
- hasToolInputField: hasAnyOwnField(hookPayload, [
- 'toolInput',
- 'tool_input',
- 'input',
- 'arguments'
- ])
- }
- )
+ const update: ToolSnapshot = {}
+ if (isGrokEvent(eventName, 'post_tool_use_failure')) {
+ Object.assign(update, clearActiveToolFieldsUpdate())
+ } else {
+ const toolName =
+ readString(hookPayload, 'toolName') ??
+ readString(hookPayload, 'tool_name') ??
+ readString(hookPayload, 'name')
+ const rawInput =
+ hookPayload.toolInput ??
+ hookPayload.tool_input ??
+ hookPayload.input ??
+ hookPayload.arguments
+ const toolInput =
+ deriveToolInputPreview(toolName, rawInput) ?? deriveFallbackToolInputPreview(rawInput)
+ // Why: Grok's ask_user_question is auto-allowed and arrives as PreToolUse
+ // (not PermissionRequest). Capture the full question payload so the live
+ // card path can render options instead of only a waiting Notification.
+ const interactivePrompt = deriveInteractivePrompt(toolName, rawInput, eventName)
+ Object.assign(
+ update,
+ toolUpdate(
+ { toolName, toolInput, interactivePrompt },
+ {
+ hasToolInputField: hasAnyOwnField(hookPayload, [
+ 'toolInput',
+ 'tool_input',
+ 'input',
+ 'arguments'
+ ])
+ }
+ )
+ )
+ }
if (isGrokEvent(eventName, 'post_tool_use', 'post_tool_use_failure')) {
const responseText =
extractToolResponseText(hookPayload.toolResponse) ??
diff --git a/src/shared/agent-icons/amp.png b/src/shared/agent-icons/amp.png
new file mode 100644
index 00000000000..9b57e20ff0f
Binary files /dev/null and b/src/shared/agent-icons/amp.png differ
diff --git a/src/shared/agent-icons/ante.png b/src/shared/agent-icons/ante.png
new file mode 100644
index 00000000000..c3dadcc2cec
Binary files /dev/null and b/src/shared/agent-icons/ante.png differ
diff --git a/src/shared/agent-icons/antigravity.png b/src/shared/agent-icons/antigravity.png
new file mode 100644
index 00000000000..be2992716b5
Binary files /dev/null and b/src/shared/agent-icons/antigravity.png differ
diff --git a/src/shared/agent-icons/aug.png b/src/shared/agent-icons/aug.png
new file mode 100644
index 00000000000..1664844ad7f
Binary files /dev/null and b/src/shared/agent-icons/aug.png differ
diff --git a/src/shared/agent-icons/autohand.png b/src/shared/agent-icons/autohand.png
new file mode 100644
index 00000000000..0c3326a5705
Binary files /dev/null and b/src/shared/agent-icons/autohand.png differ
diff --git a/src/shared/agent-icons/cline.png b/src/shared/agent-icons/cline.png
new file mode 100644
index 00000000000..f4bd762dfee
Binary files /dev/null and b/src/shared/agent-icons/cline.png differ
diff --git a/src/shared/agent-icons/codebuff.png b/src/shared/agent-icons/codebuff.png
new file mode 100644
index 00000000000..b81a6fa9c21
Binary files /dev/null and b/src/shared/agent-icons/codebuff.png differ
diff --git a/src/shared/agent-icons/command-code.png b/src/shared/agent-icons/command-code.png
new file mode 100644
index 00000000000..2066461b996
Binary files /dev/null and b/src/shared/agent-icons/command-code.png differ
diff --git a/src/shared/agent-icons/continue.png b/src/shared/agent-icons/continue.png
new file mode 100644
index 00000000000..cd2599d6e63
Binary files /dev/null and b/src/shared/agent-icons/continue.png differ
diff --git a/src/shared/agent-icons/copilot.png b/src/shared/agent-icons/copilot.png
new file mode 100644
index 00000000000..52126e047d0
Binary files /dev/null and b/src/shared/agent-icons/copilot.png differ
diff --git a/src/shared/agent-icons/crush.png b/src/shared/agent-icons/crush.png
new file mode 100644
index 00000000000..6d880c1305d
Binary files /dev/null and b/src/shared/agent-icons/crush.png differ
diff --git a/src/shared/agent-icons/cursor.png b/src/shared/agent-icons/cursor.png
new file mode 100644
index 00000000000..426cbfa4d0d
Binary files /dev/null and b/src/shared/agent-icons/cursor.png differ
diff --git a/src/shared/agent-icons/devin.png b/src/shared/agent-icons/devin.png
new file mode 100644
index 00000000000..3eee8d0d8d0
Binary files /dev/null and b/src/shared/agent-icons/devin.png differ
diff --git a/src/shared/agent-icons/droid.png b/src/shared/agent-icons/droid.png
new file mode 100644
index 00000000000..014b63332be
Binary files /dev/null and b/src/shared/agent-icons/droid.png differ
diff --git a/src/shared/agent-icons/gemini.png b/src/shared/agent-icons/gemini.png
new file mode 100644
index 00000000000..84976ebc7fd
Binary files /dev/null and b/src/shared/agent-icons/gemini.png differ
diff --git a/src/shared/agent-icons/goose.png b/src/shared/agent-icons/goose.png
new file mode 100644
index 00000000000..2da26f064ce
Binary files /dev/null and b/src/shared/agent-icons/goose.png differ
diff --git a/src/shared/agent-icons/grok.png b/src/shared/agent-icons/grok.png
new file mode 100644
index 00000000000..954e5b40da2
Binary files /dev/null and b/src/shared/agent-icons/grok.png differ
diff --git a/src/shared/agent-icons/hermes.png b/src/shared/agent-icons/hermes.png
new file mode 100644
index 00000000000..7d5ba85e54e
Binary files /dev/null and b/src/shared/agent-icons/hermes.png differ
diff --git a/src/shared/agent-icons/kilo.png b/src/shared/agent-icons/kilo.png
new file mode 100644
index 00000000000..053dba3fd76
Binary files /dev/null and b/src/shared/agent-icons/kilo.png differ
diff --git a/src/shared/agent-icons/kimi.png b/src/shared/agent-icons/kimi.png
new file mode 100644
index 00000000000..3640a259f8d
Binary files /dev/null and b/src/shared/agent-icons/kimi.png differ
diff --git a/src/shared/agent-icons/kiro.png b/src/shared/agent-icons/kiro.png
new file mode 100644
index 00000000000..4a6cc6bbf8c
Binary files /dev/null and b/src/shared/agent-icons/kiro.png differ
diff --git a/src/shared/agent-icons/mimo-code.png b/src/shared/agent-icons/mimo-code.png
new file mode 100644
index 00000000000..45cb84ff516
Binary files /dev/null and b/src/shared/agent-icons/mimo-code.png differ
diff --git a/src/shared/agent-icons/mistral-vibe.png b/src/shared/agent-icons/mistral-vibe.png
new file mode 100644
index 00000000000..f0f799cf546
Binary files /dev/null and b/src/shared/agent-icons/mistral-vibe.png differ
diff --git a/src/shared/agent-icons/openclaude.png b/src/shared/agent-icons/openclaude.png
new file mode 100644
index 00000000000..1e660b74090
Binary files /dev/null and b/src/shared/agent-icons/openclaude.png differ
diff --git a/src/shared/agent-icons/openclaw.png b/src/shared/agent-icons/openclaw.png
new file mode 100644
index 00000000000..03feb5b7638
Binary files /dev/null and b/src/shared/agent-icons/openclaw.png differ
diff --git a/src/shared/agent-icons/opencode.png b/src/shared/agent-icons/opencode.png
new file mode 100644
index 00000000000..1f45b1faee0
Binary files /dev/null and b/src/shared/agent-icons/opencode.png differ
diff --git a/src/shared/agent-icons/qwen-code.png b/src/shared/agent-icons/qwen-code.png
new file mode 100644
index 00000000000..9a6346691d4
Binary files /dev/null and b/src/shared/agent-icons/qwen-code.png differ
diff --git a/src/shared/agent-icons/rovo.png b/src/shared/agent-icons/rovo.png
new file mode 100644
index 00000000000..08a2af624f8
Binary files /dev/null and b/src/shared/agent-icons/rovo.png differ
diff --git a/tests/e2e/agent-session-live-force-exit-resume.spec.ts b/tests/e2e/agent-session-live-force-exit-resume.spec.ts
index a66f60604f5..adc5ee2d579 100644
--- a/tests/e2e/agent-session-live-force-exit-resume.spec.ts
+++ b/tests/e2e/agent-session-live-force-exit-resume.spec.ts
@@ -16,6 +16,7 @@ import {
import { ensureTerminalVisible, waitForActiveWorktree, waitForSessionReady } from './helpers/store'
import { attachRepoAndOpenTerminal, createRestartSession } from './helpers/orca-restart'
import { PROTOCOL_VERSION } from '../../src/main/daemon/types'
+import { DEFAULT_LOCAL_ORCA_PROFILE_ID } from '../../src/shared/orca-profiles'
const PROVIDER_SESSION_ID = 'e2e-live-force-exit-session'
@@ -41,7 +42,8 @@ type PersistedData = {
}
function dataFilePath(userDataDir: string): string {
- return path.join(userDataDir, 'orca-data.json')
+ // Fresh sessions migrate the seeded legacy file, then persist only here.
+ return path.join(userDataDir, 'profiles', DEFAULT_LOCAL_ORCA_PROFILE_ID, 'orca-data.json')
}
function readPersistedData(userDataDir: string): PersistedData {
@@ -205,9 +207,8 @@ test('resumes a live agent record after force-exit restart when pane PTY ownersh
}
)
- // Drive the product's own quit-capture path (what the 60s timer / beforeunload
- // run). Its origin:'quit' record differs from the live one, forcing a store
- // change that triggers the (now hydration-gated) writer before the poll below.
+ // Exercise quit capture: origin:'quit' changes the live record, triggering the
+ // hydration-gated writer before polling persisted state.
await page.evaluate(() => window.__store?.getState().captureAllSleepingAgentSessions())
await expect
diff --git a/tests/e2e/terminal-shortcuts.spec.ts b/tests/e2e/terminal-shortcuts.spec.ts
index 52680b1bd76..f120d53ffe4 100644
--- a/tests/e2e/terminal-shortcuts.spec.ts
+++ b/tests/e2e/terminal-shortcuts.spec.ts
@@ -534,10 +534,8 @@ test.describe('Terminal Shortcuts', () => {
await expect.poll(() => getKittyKeyboardFlags(orcaPage)).toBe(1)
await pressAndExpectWrite(orcaPage, electronApp, 'Shift+Enter', '\x1b[13;2u')
- // The shell is only standing in for a KKP-aware TUI and does not consume the
- // CSI-u input above. Clear it deterministically (Ctrl-U kill-line + Ctrl-C)
- // first, then send the idempotent "set flags to 0" reset as its own settled
- // command so the reset byte can't be swallowed mid line-edit.
+ // Clear the shell's unconsumed CSI-u line before resetting flags in a settled
+ // command; otherwise its line editor can swallow the reset bytes.
await sendToTerminal(orcaPage, ptyId, '\x15\x03')
await execInTerminal(orcaPage, ptyId, "printf '\\033[=0u'")
await expect.poll(() => getKittyKeyboardFlags(orcaPage)).toBe(0)