@raidiant/notifai 7.0.0 → 7.0.2

package/dist/orca-session-title.js

@@ -0,0 +1,99 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+const runOrcaCommand = (executable, args) => {
+    try {
+        return execFileSync(executable, args, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2_000,
+            maxBuffer: 512 * 1024,
+            windowsHide: true,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+function containsControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint < 32 || codePoint === 127;
+    });
+}
+function worktreePathFromId(value) {
+    if (value.length === 0 || value.length > 4_096 || containsControlCharacter(value)) {
+        return null;
+    }
+    const separator = value.indexOf('::');
+    if (separator <= 0)
+        return null;
+    const repoId = value.slice(0, separator);
+    const worktreePath = value.slice(separator + 2);
+    if (!/^[A-Za-z0-9._-]+$/u.test(repoId) || worktreePath.length === 0)
+        return null;
+    return path.posix.isAbsolute(worktreePath) || path.win32.isAbsolute(worktreePath)
+        ? worktreePath
+        : null;
+}
+function orcaExecutable(env) {
+    const configured = env['ORCA_CLI_COMMAND']?.trim();
+    if (configured !== undefined && configured.length > 0) {
+        return containsControlCharacter(configured) ? null : configured;
+    }
+    return env['ORCA_DEV_REPO_ROOT'] === undefined ? 'orca' : 'orca-dev';
+}
+/**
+ * Read the semantic display name assigned to this exact Orca worktree.
+ *
+ * The environment contributes only an opaque selector. Orca must return that
+ * exact id and its matching path before its display name becomes trusted; no
+ * path component or identifier is ever promoted into the User-visible label.
+ */
+export function readOrcaSessionTitle(env, command = runOrcaCommand) {
+    if (env['TERM_PROGRAM'] !== 'Orca')
+        return undefined;
+    const worktreeId = env['ORCA_WORKTREE_ID'];
+    if (worktreeId === undefined)
+        return undefined;
+    const expectedPath = worktreePathFromId(worktreeId);
+    if (expectedPath === null)
+        return undefined;
+    const executable = orcaExecutable(env);
+    if (executable === null)
+        return undefined;
+    let output;
+    try {
+        output = command(executable, [
+            'worktree',
+            'show',
+            '--worktree',
+            `id:${worktreeId}`,
+            '--json',
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    if (output === null || output === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const response = parsed;
+    const worktree = response.result?.worktree;
+    if (response.ok !== true ||
+        worktree?.id !== worktreeId ||
+        worktree.path !== expectedPath ||
+        typeof worktree.displayName !== 'string' ||
+        worktree.displayName.trim().length === 0) {
+        return undefined;
+    }
+    return worktree.displayName;
+}
+//# sourceMappingURL=orca-session-title.js.map

package/dist/orca-session-title.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orca-session-title.js","sourceRoot":"","sources":["../src/orca-session-title.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "type": "module",
   "description": "Send native phone notifications from agents and local programs",
   "bin": {

package/src/commands-core.ts

@@ -13,6 +13,7 @@ import type { CredentialStore, MachineCredential } from './credentials.js'
 import { type HookAdapterTarget } from './hook-adapter.js'
 import { logConfigResolved, logSettingsFrom, nullLogger, type Logger } from './logging.js'
 import type { NativeSkills } from './native-skills.js'
+import type { OrcaSessionTitleLookup } from './orca-session-title.js'
 import { packageVersion } from './release.js'
 import type { Tone } from './ui/theme.js'
 
@@ -81,6 +82,8 @@ export interface CommandDeps {
   codexSourcePid?: number
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
+  /** Test seam for Orca's exact-worktree semantic title lookup. */
+  orcaSessionTitle?: OrcaSessionTitleLookup
   /**
    * The local record of what this invocation did. Optional so a test fake need
    * not carry one; `log(deps)` supplies a logger that records nothing.
@@ -151,12 +154,29 @@ export function authedClient(deps: CommandDeps, config: CliConfig): { client: Ap
 
 export const UPDATE_CLI_COMMAND = 'npm install -g @raidiant/notifai'
 
-function localRecovery(action: RecoveryAction | null): string | null {
+function affectedDeviceNames(details: unknown): string[] {
+  if (typeof details !== 'object' || details === null || !('device_names' in details)) return []
+  const names = (details as { device_names?: unknown }).device_names
+  if (!Array.isArray(names)) return []
+  return [...new Set(names.filter((name): name is string => typeof name === 'string' && name.trim() !== ''))]
+}
+
+function naturalList(values: readonly string[]): string {
+  if (values.length <= 1) return values[0] ?? ''
+  if (values.length === 2) return `${values[0]} and ${values[1]}`
+  return `${values.slice(0, -1).join(', ')}, and ${values.at(-1)}`
+}
+
+function localRecovery(action: RecoveryAction | null, details: unknown): string | null {
   switch (action) {
     case 'update_cli':
       return `next: ${UPDATE_CLI_COMMAND}`
-    case 'update_companion':
-      return 'next: Update Notifai on the named device.'
+    case 'update_companion': {
+      const names = affectedDeviceNames(details)
+      return names.length > 0
+        ? `next: Update Notifai on ${naturalList(names)}.`
+        : 'next: Update Notifai on the affected devices.'
+    }
     case 'wait_for_service':
       return 'next: The service is being updated; try again later.'
     default:
@@ -213,7 +233,7 @@ export function reportError(
           'disagree about the contract; check with `notifai doctor`',
       )
     }
-    const recovery = localRecovery(err.recoveryAction)
+    const recovery = localRecovery(err.recoveryAction, err.details)
     if (recovery !== null) deps.io.err(recovery)
     else if (err.recoveryAction === null && err.nextAction) deps.io.err(`next: ${err.nextAction}`)
     if (err.code === 'auth_required' || err.code === 'machine_revoked') return EXIT.auth

package/src/commands-doctor.ts

@@ -589,13 +589,14 @@ export async function doctorCommand(
       deps.io.out(`${mark}  ${line(s)}`)
     }
   }
-  await deps.io.outro?.(
-    ok
-      ? 'Everything looks good'
-      : blocker?.id === 'contract'
-        ? 'Update Notifai, then run doctor again'
-        : `Start with: ${remedyLine(blocker)}`,
+  const surfacedUpdate = readiness.states.some(
+    (state) => state.id === 'contract' && (state.status === 'gap' || state.status === 'optional-gap'),
   )
+  if (blocker !== null && blocker.id !== 'contract') {
+    await deps.io.outro?.(`Start with: ${remedyLine(blocker)}`)
+  } else if (!surfacedUpdate) {
+    await deps.io.outro?.('Everything looks good')
+  }
   return ok ? EXIT.ok : EXIT.failed
 }
 

package/src/commands-init.ts

@@ -672,7 +672,6 @@ async function printInitClose(
   if (blocker?.id === 'contract') {
     deps.io.out(blocker.detail)
     deps.io.out(UPDATE_CLI_COMMAND)
-    await deps.io.outro?.('Update Notifai, then run init again')
     return
   }
 

package/src/commands-send-support.ts

@@ -4,16 +4,40 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { isRetryableReplyPollError, type ApiClient } from './client.js'
 import { buildSourceContext, inferInvocationContext } from './invocation-context.js'
+import { readOrcaSessionTitle } from './orca-session-title.js'
 import { type DraftInvocation, type SendFlags } from './send.js'
 import { EXIT, reportError, type CommandDeps } from './commands-core.js'
 import type { ActiveHarnessSession } from './commands-harness-context.js'
 
+function managedSessionTitle(
+  deps: CommandDeps,
+  flags: Pick<SendFlags, 'sessionLabel'>,
+  active: ActiveHarnessSession | null,
+): string | undefined {
+  if (active?.sessionLabel !== undefined) return active.sessionLabel
+  if (
+    active?.harness !== 'claude-code' ||
+    active.sessionId === undefined ||
+    active.sessionId !== deps.env['CLAUDE_CODE_SESSION_ID'] ||
+    flags.sessionLabel !== undefined ||
+    deps.env['NOTIFAI_SESSION_LABEL'] !== undefined
+  ) {
+    return undefined
+  }
+  try {
+    return (deps.orcaSessionTitle ?? readOrcaSessionTitle)(deps.env)
+  } catch {
+    return undefined
+  }
+}
+
 export function resolveDraftInvocation(
   deps: CommandDeps,
   flags: Pick<SendFlags, 'sessionId' | 'sessionLabel'>,
   active: ActiveHarnessSession | null,
 ): { ok: true; invocation: DraftInvocation } | { ok: false; error: string } {
   const inferred = inferInvocationContext(deps.cwd)
+  const sessionTitle = managedSessionTitle(deps, flags, active)
   const source = buildSourceContext({
     env: deps.env,
     invocation: inferred,
@@ -25,7 +49,7 @@ export function resolveDraftInvocation(
           activeHarness: {
             harness: active.harness,
             ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
-            ...(active.sessionLabel === undefined ? {} : { sessionLabel: active.sessionLabel }),
+            ...(sessionTitle === undefined ? {} : { sessionLabel: sessionTitle }),
             ...(active.sessionLabelPending === true ? { sessionLabelPending: true } : {}),
           },
         }),

package/src/commands.test.ts

@@ -180,6 +180,14 @@ class PlainInteractiveIo extends CapturedIo {
   interactive = true
 }
 
+class OutroCapturedIo extends CapturedIo {
+  outros: string[] = []
+
+  async outro(message: string) {
+    this.outros.push(message)
+  }
+}
+
 class InteractiveIo extends CapturedIo {
   interactive = true
   selectAnswer: string | null = 'global'
@@ -505,6 +513,86 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).not.toContain('opaque-claude-session-42')
   })
 
+  it('uses the exact Orca worktree title for an active Claude session send', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-claude-title-'))
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+    const worktreeId = `repo-123::${cwd}`
+    const env = {
+      XDG_CONFIG_HOME: path.join(cwd, 'config'),
+      XDG_STATE_HOME: path.join(cwd, 'state'),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'orca-claude-session',
+      TERM_PROGRAM: 'Orca',
+      ORCA_WORKTREE_ID: worktreeId,
+    }
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env,
+      orcaSessionTitle: (lookupEnv: NodeJS.ProcessEnv) => {
+        expect(lookupEnv['ORCA_WORKTREE_ID']).toBe(worktreeId)
+        return 'Worker - semantic session implementation'
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Resolver implemented',
+        body: 'The Orca worktree title was frozen locally.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: 'orca-claude-session',
+      session_label: 'Worker - semantic session implementation',
+      harness: 'claude-code',
+    })
+  })
+
+  it('falls back safely when Orca returns a private path as its title', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-private-title-'))
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: {
+        XDG_CONFIG_HOME: path.join(cwd, 'config'),
+        XDG_STATE_HOME: path.join(cwd, 'state'),
+        CLAUDECODE: '1',
+        CLAUDE_CODE_SESSION_ID: 'orca-private-title-session',
+        TERM_PROGRAM: 'Orca',
+        ORCA_WORKTREE_ID: `repo-123::${cwd}`,
+      },
+      orcaSessionTitle: () => '/private/untrusted/worktree',
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Resolver implemented',
+        body: 'Unsafe metadata must never become a visible name.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    expect(submitted?.draft.source?.session_label).not.toContain('/private/')
+  })
+
   it('uses the trusted OpenCode session title published by its managed adapter', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-opencode-title-'))
     const io = new CapturedIo()
@@ -2938,7 +3026,7 @@ describe('compatibility-first update guidance', () => {
         listDevices: async () => ({ devices: [] }),
         accessStatus: async () => ({ email: 'user@example.test' }),
       } as unknown as ApiClient
-      const humanIo = new PlainInteractiveIo()
+      const humanIo = new InteractiveIo()
       const deps = {
         ...makeDeps(humanIo, client),
         cwd,
@@ -2953,6 +3041,9 @@ describe('compatibility-first update guidance', () => {
       ).toBe(exit)
       expect(humanIo.outLines).toEqual(humanLines)
       expect(humanIo.errLines).toEqual([])
+      expect(humanIo.outros).toEqual(
+        status === 'ready' ? ['Everything looks good'] : [],
+      )
 
       const jsonIo = new CapturedIo()
       expect(
@@ -3211,7 +3302,7 @@ describe('init', () => {
 
   it('resumes the same init after a required CLI update becomes current', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-init-update-resume-'))
-    const io = new CapturedIo()
+    const io = new OutroCapturedIo()
     let cliSupport = compatibilityWithCli({
       state: 'must_update',
       reason: 'minimum_not_met',
@@ -3246,11 +3337,13 @@ describe('init', () => {
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
     expect(io.outLines).toContain("Notifai can't send notifications until you update.")
     expect(io.outLines).toContain('npm install -g @raidiant/notifai')
+    expect(io.outros).toEqual([])
     expect(submissions).toBe(0)
 
     cliSupport = currentCompatibility
     io.outLines = []
     io.errLines = []
+    io.outros = []
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
     expect(submissions).toBe(1)
@@ -4555,6 +4648,39 @@ describe('asking before the hooks have ever run', () => {
     expect(readSessionState('codex-orchestrator', env).pending).toBeUndefined()
   })
 
+  it('registers an Orca-managed Claude question under the semantic worktree title', () => {
+    const cwd = scratchDir('notifai-orca-claude-ask-')
+    const io = new CapturedIo()
+    const env = {
+      ...isolatedEnv(cwd),
+      CLAUDECODE: '1',
+      CLAUDE_CODE_SESSION_ID: 'orca-claude-question',
+      TERM_PROGRAM: 'Orca',
+      ORCA_WORKTREE_ID: `repo-123::${cwd}`,
+    }
+    const deps = {
+      ...makeDeps(io, {} as ApiClient),
+      cwd,
+      env,
+      now: () => 42,
+      orcaSessionTitle: () => 'Worker - semantic session implementation',
+    }
+
+    expect(hooksInstallCommand(deps, { harness: 'claude-code', execPath, scriptPath })).toBe(
+      EXIT.ok,
+    )
+    writeSessionState('orca-claude-question', env, { last_prompt_at: 42, last_stop_at: 41 })
+    writeProjectSession(cwd, env, 'orca-claude-question', 42, 'claude-code')
+    io.outLines = []
+
+    expect(askCommand(deps, 'Ship the semantic resolver?', {})).toBe(EXIT.ok)
+    expect(readSessionState('orca-claude-question', env).pending?.[0]?.source).toMatchObject({
+      session_id: 'orca-claude-question',
+      session_label: 'Worker - semantic session implementation',
+      harness: 'claude-code',
+    })
+  })
+
   it('judges the fired check against the active harness, not a global installation of another', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-fired-active-harness-'))
     const io = new CapturedIo()
@@ -5457,7 +5583,7 @@ describe('command failures carrying server details', () => {
 
     expect(io.errLines).toEqual([
       "feature_unavailable: The selected device can't answer questions.",
-      'next: Update Notifai on the named device.',
+      'next: Update Notifai on Old phone.',
     ])
     expect(io.errLines.join(' ')).not.toContain('untrusted')
     expect(io.errLines.join(' ')).not.toContain('disagree about the contract')

package/src/config-schema.ts

@@ -199,7 +199,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     kind: 'string',
     summary: 'Free text an agent reads before deciding whether to notify you',
     detail:
-      'Your own guidance, in your own words, about what is worth a notification in this project — read by agents before they send. Something like "only tell me about failures and finished deploys; never per-file progress".\n\nIt is advice to the agent, not a filter the service enforces.',
+      'Your own guidance, in your own words, about what is worth a notification in this project — read by agents before they send. Something like "only tell me about failures and finished deploys; never per-file progress".\n\nIt is advice to the agent, not a filter the service enforces. Agents follow it as your literal standing word, so an agent may write it only when you ask for a preference to be remembered — and only in your words, never its own summary.',
     unsetMeans: 'agents fall back to their default judgement',
     example: 'Only failures and completed deploys',
   },

package/src/orca-session-title.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import { readOrcaSessionTitle, type OrcaCommand } from './orca-session-title.js'
+
+const worktreeId = 'repo-123::/worktrees/semantic-session-implementation'
+
+function response(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    ok: true,
+    result: {
+      worktree: {
+        id: worktreeId,
+        path: '/worktrees/semantic-session-implementation',
+        displayName: 'Worker - semantic session implementation',
+        ...overrides,
+      },
+    },
+  })
+}
+
+describe('Orca semantic session title', () => {
+  it('accepts only the display name returned for the exact managed worktree', () => {
+    const calls: { executable: string; args: readonly string[] }[] = []
+    const command: OrcaCommand = (executable, args) => {
+      calls.push({ executable, args })
+      return response()
+    }
+
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: worktreeId },
+        command,
+      ),
+    ).toBe('Worker - semantic session implementation')
+    expect(calls).toEqual([
+      {
+        executable: 'orca',
+        args: ['worktree', 'show', '--worktree', `id:${worktreeId}`, '--json'],
+      },
+    ])
+  })
+
+  it('uses Orca-provided executable selection without invoking a shell', () => {
+    const calls: string[] = []
+    expect(
+      readOrcaSessionTitle(
+        {
+          TERM_PROGRAM: 'Orca',
+          ORCA_WORKTREE_ID: worktreeId,
+          ORCA_CLI_COMMAND: '/mnt/c/Program Files/Orca/orca.exe',
+        },
+        (executable) => {
+          calls.push(executable)
+          return response()
+        },
+      ),
+    ).toBe('Worker - semantic session implementation')
+    expect(calls).toEqual(['/mnt/c/Program Files/Orca/orca.exe'])
+  })
+
+  it('ignores non-Orca and malformed selectors without running a command', () => {
+    const command: OrcaCommand = () => {
+      throw new Error('must not run')
+    }
+    expect(readOrcaSessionTitle({ ORCA_WORKTREE_ID: worktreeId }, command)).toBeUndefined()
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: '/private/untrusted' },
+        command,
+      ),
+    ).toBeUndefined()
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: 'repo-123::relative/path' },
+        command,
+      ),
+    ).toBeUndefined()
+  })
+
+  it.each([
+    ['command failure', () => null],
+    ['thrown command failure', () => { throw new Error('offline') }],
+    ['malformed JSON', () => '{not json}'],
+    ['failed response', () => JSON.stringify({ ok: false })],
+    ['different worktree id', () => response({ id: 'repo-123::/worktrees/other' })],
+    ['different worktree path', () => response({ path: '/private/untrusted' })],
+    ['blank display name', () => response({ displayName: '   ' })],
+  ])('fails closed for %s', (_name, command) => {
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: worktreeId },
+        command,
+      ),
+    ).toBeUndefined()
+  })
+})

package/src/orca-session-title.ts

@@ -0,0 +1,105 @@
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+
+export type OrcaSessionTitleLookup = (env: NodeJS.ProcessEnv) => string | undefined
+export type OrcaCommand = (executable: string, args: readonly string[]) => string | null
+
+const runOrcaCommand: OrcaCommand = (executable, args) => {
+  try {
+    return execFileSync(executable, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2_000,
+      maxBuffer: 512 * 1024,
+      windowsHide: true,
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+function containsControlCharacter(value: string): boolean {
+  return Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0
+    return codePoint < 32 || codePoint === 127
+  })
+}
+
+function worktreePathFromId(value: string): string | null {
+  if (value.length === 0 || value.length > 4_096 || containsControlCharacter(value)) {
+    return null
+  }
+  const separator = value.indexOf('::')
+  if (separator <= 0) return null
+  const repoId = value.slice(0, separator)
+  const worktreePath = value.slice(separator + 2)
+  if (!/^[A-Za-z0-9._-]+$/u.test(repoId) || worktreePath.length === 0) return null
+  return path.posix.isAbsolute(worktreePath) || path.win32.isAbsolute(worktreePath)
+    ? worktreePath
+    : null
+}
+
+function orcaExecutable(env: NodeJS.ProcessEnv): string | null {
+  const configured = env['ORCA_CLI_COMMAND']?.trim()
+  if (configured !== undefined && configured.length > 0) {
+    return containsControlCharacter(configured) ? null : configured
+  }
+  return env['ORCA_DEV_REPO_ROOT'] === undefined ? 'orca' : 'orca-dev'
+}
+
+/**
+ * Read the semantic display name assigned to this exact Orca worktree.
+ *
+ * The environment contributes only an opaque selector. Orca must return that
+ * exact id and its matching path before its display name becomes trusted; no
+ * path component or identifier is ever promoted into the User-visible label.
+ */
+export function readOrcaSessionTitle(
+  env: NodeJS.ProcessEnv,
+  command: OrcaCommand = runOrcaCommand,
+): string | undefined {
+  if (env['TERM_PROGRAM'] !== 'Orca') return undefined
+  const worktreeId = env['ORCA_WORKTREE_ID']
+  if (worktreeId === undefined) return undefined
+  const expectedPath = worktreePathFromId(worktreeId)
+  if (expectedPath === null) return undefined
+  const executable = orcaExecutable(env)
+  if (executable === null) return undefined
+
+  let output: string | null
+  try {
+    output = command(executable, [
+      'worktree',
+      'show',
+      '--worktree',
+      `id:${worktreeId}`,
+      '--json',
+    ])
+  } catch {
+    return undefined
+  }
+  if (output === null || output === '') return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(output)
+  } catch {
+    return undefined
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined
+  const response = parsed as {
+    ok?: unknown
+    result?: { worktree?: { id?: unknown; path?: unknown; displayName?: unknown } }
+  }
+  const worktree = response.result?.worktree
+  if (
+    response.ok !== true ||
+    worktree?.id !== worktreeId ||
+    worktree.path !== expectedPath ||
+    typeof worktree.displayName !== 'string' ||
+    worktree.displayName.trim().length === 0
+  ) {
+    return undefined
+  }
+  return worktree.displayName
+}