@raidiant/notifai 9.3.0 → 10.0.0

package/src/install-hooks.test.ts

@@ -27,9 +27,9 @@ import {
   WORKER_ACTIVATION_CONTEXT,
 } from './session-activation.js'
 import { hookAdapterPath, installHookAdapter } from './hook-adapter.js'
+import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js'
 import {
   QUESTION_STOP_TIMEOUT_SECONDS,
-  HARNESSES,
   applyPlan,
   detectHarness,
   detectedHarnesses,
@@ -1045,7 +1045,8 @@ describe('the OpenCode adapter', () => {
   })
 
   it('is a harness `hooks install` knows about', () => {
-    expect(HARNESSES).toContain('opencode')
+    expect(HOOK_INSTALLABLE_HARNESSES).toContain('opencode')
+    expect(HOOK_INSTALLABLE_HARNESSES).not.toContain('hermes')
     expect(settingsFile('opencode', false, '/repo', {})).toContain('notifai.js')
   })
 
@@ -1099,7 +1100,7 @@ describe('detectHarness', () => {
     const dir = project('AGENTS.md')
     const answer = detectHarness(dir)
     expect(answer).not.toBe('codex')
-    expect(HARNESSES.includes(answer as never) || answer === null).toBe(true)
+    expect(HOOK_INSTALLABLE_HARNESSES.includes(answer as never) || answer === null).toBe(true)
   })
 
   it('pairs AGENTS.md with CLAUDE.md as Claude Code, not Codex', () => {
@@ -1155,7 +1156,7 @@ describe('detectHarness', () => {
     // Whatever this machine has, an empty project must never crash and must
     // return either a single harness or null — never an arbitrary pick.
     const answer = detectHarness(empty)
-    expect(answer === null || HARNESSES.includes(answer)).toBe(true)
+    expect(answer === null || HOOK_INSTALLABLE_HARNESSES.includes(answer)).toBe(true)
   })
 })
 

package/src/install-hooks.ts

@@ -20,15 +20,13 @@ import {
   type HookHostPlatform,
 } from './hook-adapter.js'
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
-import { HARNESSES, type Harness } from './harnesses.js'
+import { HOOK_INSTALLABLE_HARNESSES, type HookInstallableHarness } from './harnesses.js'
 import { accountHome } from './platform.js'
 import {
   NON_ROUTING_STOP_TIMEOUT_SECONDS,
   QUESTION_STOP_TIMEOUT_SECONDS,
 } from './question-timing.js'
 
-export { HARNESSES, type Harness } from './harnesses.js'
-
 /**
  * The three joints the OpenCode plugin hooks into, as (harness event, the
  * `notifai hook` event it runs). The plugin is a module and has no settings
@@ -73,7 +71,7 @@ export interface HookGroup {
 export type HookConfig = Record<string, HookGroup[]>
 
 export interface InstallPlan {
-  harness: Harness
+  harness: HookInstallableHarness
   /** Absolute path of the settings file that will be written. */
   file: string
   /** True when the file is machine-wide rather than per-project. */
@@ -97,7 +95,7 @@ export interface HookCommandOptions {
 export function hookCommand(
   adapterPath: string,
   event: string,
-  harness?: Harness,
+  harness?: HookInstallableHarness,
   options: HookCommandOptions = {},
 ): string {
   return (
@@ -174,7 +172,7 @@ export interface BuildOptions {
   /** Stable user-level executable installed by the hook adapter module. */
   adapterPath: string
   /** The installed adapter stamps its exact harness into project pointers. */
-  harness?: Harness
+  harness?: HookInstallableHarness
   platform?: NodeJS.Platform | HookHostPlatform
   /** Registered Node named first in Windows hook commands. */
   nodePath?: string
@@ -195,7 +193,7 @@ export { QUESTION_STOP_TIMEOUT_SECONDS } from './question-timing.js'
  * `question-timing.ts`.
  */
 export function stopHandlerIsDetached(
-  harness: Harness | undefined,
+  harness: HookInstallableHarness | undefined,
   platform?: Parameters<typeof hookHostPlatform>[0],
 ): boolean {
   return harness === 'claude-code' && hookHostPlatform(platform) === 'posix'
@@ -213,7 +211,7 @@ export function stopHandlerIsDetached(
  */
 function stopHandler(
   adapterPath: string,
-  harness: Harness | undefined,
+  harness: HookInstallableHarness | undefined,
   options: HookCommandOptions,
 ): HookHandler {
   const command = hookCommand(adapterPath, 'stop', harness, options)
@@ -355,7 +353,7 @@ export function buildCursorHookConfig(options: BuildOptions): CursorHookConfig {
  * questions pushed to is not a property of the repository.
  */
 export function settingsFile(
-  harness: Harness,
+  harness: HookInstallableHarness,
   global: boolean,
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -606,7 +604,7 @@ export function withCodexLayerTransaction<T>(
 
 /** Every file in this layer Codex might already be reading hooks from. */
 export function hookDefinitionFiles(
-  harness: Harness,
+  harness: HookInstallableHarness,
   global: boolean,
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -741,8 +739,8 @@ function ourHandlerEvents(document: SettingsDocument | null): string[] {
  * document. Treating it as evidence of any one harness would be a guess
  * dressed up as detection.
  */
-function localHarnessEvidence(cwd: string): Harness[] {
-  const found: Harness[] = []
+function localHarnessEvidence(cwd: string): HookInstallableHarness[] {
+  const found: HookInstallableHarness[] = []
   if (existsSync(path.join(cwd, '.claude')) || existsSync(path.join(cwd, 'CLAUDE.md'))) {
     found.push('claude-code')
   }
@@ -756,9 +754,9 @@ function localHarnessEvidence(cwd: string): Harness[] {
 function globalHarnessEvidence(
   env: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform | HookHostPlatform = process.platform,
-): Harness[] {
+): HookInstallableHarness[] {
   const home = harnessAccountHome(env, platform)
-  const found: Harness[] = []
+  const found: HookInstallableHarness[] = []
   if (existsSync(path.join(home, '.claude'))) found.push('claude-code')
   if (existsSync(codexGlobalDir(env, platform))) found.push('codex')
   if (existsSync(path.join(home, '.cursor'))) found.push('cursor')
@@ -777,12 +775,12 @@ export function detectedHarnesses(
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform | HookHostPlatform = process.platform,
-): Harness[] {
-  const seen = new Set<Harness>([
+): HookInstallableHarness[] {
+  const seen = new Set<HookInstallableHarness>([
     ...localHarnessEvidence(cwd),
     ...globalHarnessEvidence(env, platform),
   ])
-  return HARNESSES.filter((harness) => seen.has(harness))
+  return HOOK_INSTALLABLE_HARNESSES.filter((harness) => seen.has(harness))
 }
 
 /**
@@ -798,7 +796,7 @@ export function detectHarness(
   cwd: string,
   env: NodeJS.ProcessEnv = process.env,
   platform: NodeJS.Platform | HookHostPlatform = process.platform,
-): Harness | null {
+): HookInstallableHarness | null {
   const local = localHarnessEvidence(cwd)
   if (local.length > 0) return local.length === 1 ? local[0]! : null
   const global = globalHarnessEvidence(env, platform)
@@ -1193,7 +1191,7 @@ export interface InstalledHandler {
 }
 
 export interface Installation {
-  harness: Harness
+  harness: HookInstallableHarness
   file: string
   global: boolean
   handlers: InstalledHandler[]
@@ -1331,7 +1329,7 @@ export function findInstallations(
     ...(nodePath === undefined ? {} : { nodePath }),
   }
   const found: Installation[] = []
-  for (const harness of HARNESSES) {
+  for (const harness of HOOK_INSTALLABLE_HARNESSES) {
     for (const global of [false, true]) {
       const files = hookDefinitionFiles(harness, global, cwd, env, platform)
       for (const file of files) {
@@ -1411,7 +1409,7 @@ export function findInstallations(
 }
 
 function harnessMarkerProblems(
-  harness: Harness,
+  harness: HookInstallableHarness,
   handlers: InstalledHandler[],
   adapterHome?: string,
   options: HookCommandOptions = {},

package/src/invocation-context.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process'
 import path from 'node:path'
 import { type SourceContextT } from '@raidiant/notifai-protocol'
-import type { Harness } from './harnesses.js'
+import type { SourceContextHarness } from './harnesses.js'
 import { resolveSessionLabel } from './session-labels.js'
 
 export type GitCommand = (cwd: string, args: readonly string[]) => string | null
@@ -138,7 +138,7 @@ export interface SourceContextInput {
   sessionId?: string
   sessionLabel?: string
   activeHarness?: {
-    harness: Harness
+    harness: SourceContextHarness
     sessionId?: string
     sessionLabel?: string
     sessionLabelPending?: boolean

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

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+import { readOrcaSessionTitle, type OrcaCommand } from './orca-session-title.js'
+
+const worktreeId = 'repo-123::/worktrees/agent-session-labels'
+
+function response(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    ok: true,
+    result: {
+      worktree: {
+        id: worktreeId,
+        path: '/worktrees/agent-session-labels',
+        displayName: 'Agent Session context labels',
+        ...overrides,
+      },
+    },
+  })
+}
+
+describe('Orca Agent Session title context', () => {
+  it('accepts only the User-facing title 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('Agent Session context labels')
+    expect(calls).toEqual([
+      {
+        executable: 'orca',
+        args: ['worktree', 'show', '--worktree', `id:${worktreeId}`, '--json'],
+      },
+    ])
+  })
+
+  it.each([
+    ['command failure', () => null],
+    ['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: '   ' })],
+  ])('leaves the generated fallback exceptional when context is unavailable: %s', (_name, command) => {
+    expect(
+      readOrcaSessionTitle(
+        { TERM_PROGRAM: 'Orca', ORCA_WORKTREE_ID: worktreeId },
+        command,
+      ),
+    ).toBeUndefined()
+  })
+})

package/src/orca-session-title.ts

@@ -0,0 +1,103 @@
+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 User-facing task 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 an Agent Session 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
+}

package/src/program.test.ts

@@ -116,6 +116,33 @@ describe('program argv parsing', () => {
     expect(enabled).toBe(1)
   })
 
+  it('dispatches the current Agent Session rename without exposing an id override', async () => {
+    let label: string | undefined
+    const result = await parse(['session', 'rename', 'Hermes Support'], {
+      agentSessionRename: (async (_deps, value) => ((label = value), 0)) as ProgramRunners['agentSessionRename'],
+    })
+    expect(result.exitCode).toBe(0)
+    expect(label).toBe('Hermes Support')
+  })
+
+  it('dispatches sounds --json onto soundsCommand', async () => {
+    let seen: Record<string, unknown> | undefined
+    const result = await parse(['sounds', '--json'], {
+      sounds: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['sounds'],
+    })
+    expect(result.exitCode).toBe(0)
+    expect(seen).toMatchObject({ json: true })
+  })
+
+  it('passes a custom sound name through --sound', async () => {
+    let seen: Record<string, unknown> | undefined
+    await parse(
+      ['send', '--kind', 'done', '--title', 'T', '--body', 'B', '--sound', 'Kitchen timer'],
+      { send: (async (_deps, flags) => ((seen = flags as Record<string, unknown>), 0)) as ProgramRunners['send'] },
+    )
+    expect(seen).toMatchObject({ sound: 'Kitchen timer' })
+  })
+
   it('drops empty collector defaults so "not passed" stays absent', async () => {
     let seen: Record<string, unknown> | undefined
     await parse(

package/src/program.ts

@@ -4,6 +4,7 @@ import {
   acknowledgeCommand,
   askCommand,
   accessStatusCommand,
+  agentSessionRenameCommand,
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
@@ -30,11 +31,12 @@ import {
   repliesCommand,
   reportAskFailure,
   sendCommand,
+  soundsCommand,
   statusCommand,
   type CommandDeps,
 } from './commands.js'
 import { packageVersion } from './release.js'
-import { HARNESSES } from './install-hooks.js'
+import { HOOK_INSTALLABLE_HARNESSES } from './harnesses.js'
 import type { Platform } from '@raidiant/notifai-protocol'
 import type { SkillScope } from './native-skills.js'
 import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
@@ -83,10 +85,12 @@ const defaultRunners = {
   authStatus: authStatusCommand,
   accessStatus: accessStatusCommand,
   devices: devicesCommand,
+  sounds: soundsCommand,
   capabilities: capabilitiesCommand,
   projectEnable: projectEnableCommand,
   projectDisable: projectDisableCommand,
   projectStatus: projectStatusCommand,
+  agentSessionRename: agentSessionRenameCommand,
   send: sendCommand,
   replies: repliesCommand,
   acknowledge: acknowledgeCommand,
@@ -271,6 +275,21 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     exit(runners.projectStatus(deps, opts.json === true))
   })
 
+  const session = program
+    .command('session')
+    .helpGroup(GROUP.agent)
+    .summary('Inspect or rename the current Agent Session')
+    .description('Operate on the exact Agent Session owned by the active harness')
+  session
+    .command('rename <label>')
+    .description(
+      'Rename this exact Agent Session; agents use this only after its job changes completely enough that the old label would mislead',
+    )
+    .option('--json', 'machine-readable output')
+    .action(async (label: string, opts: { json?: boolean }) => {
+      exit(await runners.agentSessionRename(deps, label, opts))
+    })
+
   program
     .command('login')
     .helpGroup(GROUP.start)
@@ -323,6 +342,18 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       exit(await runners.devices(deps, opts))
     })
 
+  program
+    .command('sounds')
+    .helpGroup(GROUP.daily)
+    .summary('List shipped and Account custom sounds')
+    .description(
+      'List the sounds --sound and the saved sound key accept: shipped names and this Account\'s custom sounds',
+    )
+    .option('--json', 'machine-readable output')
+    .action(async (opts: { json?: boolean }) => {
+      exit(await runners.sounds(deps, opts))
+    })
+
   program
     .command('capabilities')
     .helpGroup(GROUP.advanced)
@@ -389,7 +420,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     )
     .option('--multi', 'with --choice, several answers may be selected')
     .optionsGroup(SEND_GROUP.advanced)
-    .option('--sound <sound>', 'override saved sound: default | done | attention | alert | none')
+    .option(
+      '--sound <sound>',
+      'override saved sound: default | done | attention | alert | none, or a custom name or id from notifai sounds',
+    )
     .option(
       '--level <level>',
       'Apple-only interruption level: passive | active | time_sensitive (unsupported with --platform android)',
@@ -435,7 +469,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
 
   send.addHelpText(
     'after',
-    `\nKind is required, and it selects the sound the notification arrives with: done rings the completion chime, failed the most insistent tone, blocked and question a distinct attention tone, update the standard one.\nAn explicit --sound or saved sound preference outranks that default. --level is Apple-only; Android attention is owned by kind, product channels, and device settings.\n`,
+    `\nKind is required, and it selects the sound the notification arrives with: done rings the completion chime, failed the most insistent tone, blocked and question a distinct attention tone, update Device default.\nAn explicit --sound or saved sound preference outranks that default. --sound accepts a shipped name, an Account custom sound name or id from \`notifai sounds\`, or none. --level is Apple-only; Android attention is owned by kind, product channels, and device settings.\n`,
   )
 
   program
@@ -593,7 +627,7 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--owner <name>', 'internal ownership marker')
     .option('--harness <name>', 'internal harness output adapter')
     .action(async (event: string, opts: { harness?: string }) => {
-      const harness = HARNESSES.find((candidate) => candidate === opts.harness)
+      const harness = HOOK_INSTALLABLE_HARNESSES.find((candidate) => candidate === opts.harness)
       exit(await runners.hookRun(deps, event, () => readStdinWithTimeout(), harness))
     })
 

package/src/send.ts

@@ -1,5 +1,4 @@
 import {
-  CLI_SOUNDS,
   COLLAPSE_KEY_MAX_BYTES,
   INTERRUPTION_LEVELS,
   MEDIA_MAX_ITEMS,
@@ -13,9 +12,6 @@ import {
   type MediaItemT,
   type NotificationDraftT,
   NOTIFICATION_KINDS,
-  DEFAULT_NOTIFICATION_KIND,
-  defaultSoundForKind,
-  type NotificationKind,
   PLATFORMS,
   type Platform,
   type QuestionT,
@@ -23,8 +19,7 @@ import {
   type SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import type { CliConfig } from './config.js'
-
-type CliSound = (typeof CLI_SOUNDS)[number]
+import { isCliSoundRef, unknownSoundMessage } from './sound-ref.js'
 
 export interface SendFlags {
   title: string
@@ -217,18 +212,15 @@ export function buildDraft(
     }
   }
 
-  // Kind states what happened; the sound table turns that truth into the
-  // attention it deserves, so an honest sender gets the right sound without
-  // reasoning about audio. An explicit --sound and the user's saved preference
-  // both outrank it, and `none` still means silent.
-  const kindForSound: NotificationKind = flags.reply
-    ? 'question'
-    : ((flags.kind as NotificationKind | undefined) ?? DEFAULT_NOTIFICATION_KIND)
-  const sound = flags.sound ?? config.sound.value ?? defaultSoundForKind(kindForSound)
-  if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound as CliSound)) {
+  // Explicit --sound and the saved sound key outrank kind. The server is the
+  // one that applies kind, Project, and Account maps — stamping a kind default
+  // here would look like an explicit choice and skip those layers. `none` is
+  // still silent.
+  const sound = flags.sound !== undefined ? flags.sound : config.sound.value
+  if (sound !== null && sound !== undefined && !isCliSoundRef(sound)) {
     return {
       ok: false,
-      error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
+      error: unknownSoundMessage(sound),
     }
   }
   const level =
@@ -254,9 +246,8 @@ export function buildDraft(
     appleOptions.sound = null
     androidOptions.sound = null
   } else if (sound !== null && sound !== undefined) {
-    const semanticSound = sound as Exclude<(typeof CLI_SOUNDS)[number], 'none'>
-    appleOptions.sound = semanticSound
-    androidOptions.sound = semanticSound
+    appleOptions.sound = sound
+    androidOptions.sound = sound
   }
   if (flags.threadId !== undefined) {
     appleOptions.thread_id = flags.threadId

package/src/session-labels.test.ts

@@ -1,9 +1,20 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { stateDir } from './config.js'
-import { formatSessionFirstSeen, resolveSessionLabel } from './session-labels.js'
+import {
+  formatSessionFirstSeen,
+  renameStoredSessionLabel,
+  resolveSessionLabel,
+} from './session-labels.js'
 
 function fixture(): { env: NodeJS.ProcessEnv; now: number } {
   const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-session-labels-'))
@@ -416,26 +427,64 @@ describe('semantic session labels', () => {
     })
   })
 
-  it('fails closed instead of replacing an unreadable name store', () => {
+  it('isolates an unreadable name store before creating a clean one', () => {
     const { env, now } = fixture()
     const file = path.join(stateDir(env), 'session-labels.json')
     mkdirSync(path.dirname(file), { recursive: true })
     writeFileSync(file, '{not json}\n')
 
-    const resolved = resolveSessionLabel({
+    expect(
+      resolveSessionLabel({
       env,
       now,
       sessionId: 'new-session',
       explicitLabel: 'Do not overwrite me',
-    })
-
-    expect(resolved.ok).toBe(false)
-    expect(!resolved.ok && resolved.error).toContain('session-name store is unreadable')
-    expect(readFileSync(file, 'utf8')).toBe('{not json}\n')
+      }),
+    ).toEqual({ ok: true, label: 'Do not overwrite me', source: 'explicit' })
+    expect(readFileSync(file, 'utf8')).not.toBe('{not json}\n')
+    const backups = readdirSync(path.dirname(file)).filter((name) =>
+      /^session-labels\.invalid-[a-f0-9]{64}\.json$/u.test(name),
+    )
+    expect(backups).toHaveLength(1)
+    expect(readFileSync(path.join(path.dirname(file), backups[0]!), 'utf8')).toBe('{not json}\n')
   })
 
   it('formats first seen using the machine local calendar', () => {
     const now = new Date(2026, 0, 2, 3, 4).getTime()
     expect(formatSessionFirstSeen(now)).toBe('Jan 2, 2026 03:04')
   })
+
+  it('explicitly replaces a semantic or fallback label after an authorized rename', () => {
+    const { env, now } = fixture()
+    resolveSessionLabel({
+      env,
+      now,
+      sessionId: 'rename-me',
+      harness: 'codex',
+      explicitLabel: 'Old job',
+    })
+
+    expect(
+      renameStoredSessionLabel({
+        env,
+        now: now + 1_000,
+        sessionId: 'rename-me',
+        harness: 'codex',
+        label: '  Completely   different job  ',
+      }),
+    ).toEqual({ ok: true, label: 'Completely different job', source: 'explicit' })
+    expect(
+      resolveSessionLabel({
+        env,
+        now: now + 2_000,
+        sessionId: 'rename-me',
+        harness: 'codex',
+        harnessLabel: 'Later task context',
+      }),
+    ).toEqual({
+      ok: true,
+      label: 'Completely different job',
+      source: 'explicit',
+    })
+  })
 })