@raidiant/notifai 6.0.0 → 7.0.0

package/dist/session-labels.d.ts

@@ -0,0 +1,30 @@
+import { type Harness } from './harnesses.js';
+type SessionLabelSource = 'explicit' | 'harness' | 'fallback';
+export interface SessionLabelInput {
+    env: NodeJS.ProcessEnv;
+    sessionId: string;
+    harness?: Harness;
+    explicitLabel?: string;
+    harnessLabel?: string;
+    harnessLabelPending?: boolean;
+    now?: number;
+}
+export type SessionLabelResolution = {
+    ok: true;
+    label: string;
+    source: SessionLabelSource;
+} | {
+    ok: false;
+    error: string;
+};
+/** Stable English shape using the machine's local calendar and clock. */
+export declare function formatSessionFirstSeen(now: number): string;
+/**
+ * Freeze the first accepted human name for one immutable session.
+ *
+ * Explicit agent/User input wins, then a title supplied by a trusted harness
+ * adapter, then a generated fallback. Later sends reuse the frozen value
+ * even when their branch, worktree, title candidate, or notification changes.
+ */
+export declare function resolveSessionLabel(input: SessionLabelInput): SessionLabelResolution;
+export {};

package/dist/session-labels.js

@@ -0,0 +1,278 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SESSION_LABEL_MAX_LENGTH } from '@raidiant/notifai-protocol';
+import { atomicWriteFileSync } from './atomic-file.js';
+import { stateDir } from './config.js';
+import { withFileLock } from './file-lock.js';
+import { generatedSessionLabel } from './generated-session-label.js';
+import { HARNESS_LABELS } from './harnesses.js';
+const STORE_VERSION = 1;
+const MONTHS = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+function storePath(env) {
+    return path.join(stateDir(env), 'session-labels.json');
+}
+/** The state key cannot reveal the harness's opaque session identifier. */
+function sessionKey(sessionId) {
+    return createHash('sha256').update(sessionId).digest('hex');
+}
+function emptyStore() {
+    return { version: STORE_VERSION, sessions: {} };
+}
+function storedRecord(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return null;
+    const value = candidate;
+    if (typeof value.label !== 'string' ||
+        value.label.length === 0 ||
+        value.label.length > SESSION_LABEL_MAX_LENGTH ||
+        !['explicit', 'harness', 'fallback'].includes(value.source ?? '') ||
+        typeof value.first_seen_at !== 'number' ||
+        !Number.isFinite(value.first_seen_at)) {
+        return null;
+    }
+    const harness = value.harness;
+    if (harness !== undefined && !Object.hasOwn(HARNESS_LABELS, harness))
+        return null;
+    return {
+        label: value.label,
+        source: value.source,
+        first_seen_at: value.first_seen_at,
+        ...(harness === undefined ? {} : { harness }),
+    };
+}
+function readStore(file) {
+    if (!existsSync(file))
+        return emptyStore();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`the session-name store is unreadable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('the session-name store is not a JSON object');
+    }
+    const raw = parsed;
+    if (raw.version !== STORE_VERSION) {
+        throw new Error(`unsupported session-name store version ${String(raw.version)}`);
+    }
+    if (typeof raw.sessions !== 'object' || raw.sessions === null) {
+        throw new Error('the session-name store has no sessions object');
+    }
+    const sessions = {};
+    for (const [key, candidate] of Object.entries(raw.sessions)) {
+        const record = storedRecord(candidate);
+        if (!/^[a-f0-9]{64}$/.test(key) || record === null) {
+            throw new Error('the session-name store contains an invalid record');
+        }
+        sessions[key] = record;
+    }
+    return { version: STORE_VERSION, sessions };
+}
+function writeStore(file, store) {
+    atomicWriteFileSync(file, `${JSON.stringify(store, null, 2)}\n`);
+}
+function normalizeWhitespace(value) {
+    return value.trim().replaceAll(/\s+/gu, ' ');
+}
+/** Match the same UTF-16 length TypeBox enforces at the wire boundary. */
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    let prefix = value.slice(0, Math.max(0, maxLength - 1));
+    const last = prefix.charCodeAt(prefix.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        prefix = prefix.slice(0, -1);
+    return `${prefix}…`;
+}
+const UUID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/iu;
+const HASH_PATTERN = /\b[0-9a-f]{12,}\b/iu;
+const HARNESS_ID_PATTERN = /\b(?:ses|thread)_[A-Za-z0-9_-]{8,}\b/iu;
+const FILESYSTEM_PATH_PATTERN = /(?:^|[\s("'=:])(?:~[\\/]|[A-Za-z]:[\\/]|\\\\|\/(?:Users|home|private|tmp|var|Volumes|opt|etc|usr|workspace|workspaces)(?:[\\/]|$))/u;
+const OPENCODE_PENDING_TITLE = /^New session(?:\s*-\s*\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)?$/iu;
+function containsPrivatePath(value, env) {
+    if (FILESYSTEM_PATH_PATTERN.test(value))
+        return true;
+    const folded = value.toLocaleLowerCase('en-US');
+    for (const key of ['HOME', 'USERPROFILE', 'TMPDIR']) {
+        const candidate = env[key]?.trim().replace(/[\\/]+$/u, '');
+        if (candidate !== undefined &&
+            candidate.length > 1 &&
+            folded.includes(candidate.toLocaleLowerCase('en-US'))) {
+            return true;
+        }
+    }
+    return false;
+}
+function violatesLabelPrivacy(value, input) {
+    const sessionId = input.sessionId.trim();
+    const exposesCurrentId = sessionId.length > 0 &&
+        (value === sessionId || (sessionId.length >= 8 && value.includes(sessionId)));
+    return (exposesCurrentId ||
+        UUID_PATTERN.test(value) ||
+        HASH_PATTERN.test(value) ||
+        HARNESS_ID_PATTERN.test(value) ||
+        containsPrivatePath(value, input.env));
+}
+function explicitCandidate(value, input) {
+    if (value === undefined)
+        return null;
+    const normalized = normalizeWhitespace(value);
+    if (normalized.length === 0) {
+        return { error: '--session-label (or NOTIFAI_SESSION_LABEL) must not be empty.' };
+    }
+    if (normalized.length > SESSION_LABEL_MAX_LENGTH) {
+        return {
+            error: `--session-label (or NOTIFAI_SESSION_LABEL) must be at most ${SESSION_LABEL_MAX_LENGTH} characters.`,
+        };
+    }
+    if (violatesLabelPrivacy(normalized, input)) {
+        return {
+            error: '--session-label (or NOTIFAI_SESSION_LABEL) must not contain a session identifier, hash, or filesystem path.',
+        };
+    }
+    return { label: normalized, source: 'explicit' };
+}
+function harnessLabelIsPending(value, input) {
+    if (input.harnessLabelPending === true)
+        return true;
+    if (input.harness !== 'opencode' || value === undefined)
+        return false;
+    return OPENCODE_PENDING_TITLE.test(normalizeWhitespace(value));
+}
+function harnessCandidate(value, input) {
+    if (value === undefined)
+        return null;
+    const normalized = normalizeWhitespace(value);
+    if (normalized.length === 0 || violatesLabelPrivacy(normalized, input))
+        return null;
+    return {
+        label: truncate(normalized, SESSION_LABEL_MAX_LENGTH),
+        source: 'harness',
+    };
+}
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** Stable English shape using the machine's local calendar and clock. */
+export function formatSessionFirstSeen(now) {
+    const date = new Date(now);
+    return `${MONTHS[date.getMonth()]} ${date.getDate()}, ${date.getFullYear()} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+function fallbackCandidate(sessionId) {
+    return {
+        label: generatedSessionLabel(sessionId),
+        source: 'fallback',
+    };
+}
+function isLegacyDateFallback(record) {
+    if (record.source !== 'fallback')
+        return false;
+    const owner = record.harness === undefined ? 'Agent' : HARNESS_LABELS[record.harness];
+    return record.label.startsWith(`${owner} session · `);
+}
+function withSuffix(base, suffix) {
+    const room = SESSION_LABEL_MAX_LENGTH - suffix.length;
+    return `${truncate(base, room)}${suffix}`;
+}
+function collisionKey(value) {
+    return value.normalize('NFKC').toLocaleLowerCase('en-US');
+}
+function uniqueLabel(base, source, harness, now, used) {
+    if (!used.has(collisionKey(base)))
+        return base;
+    if (source === 'fallback') {
+        for (let ordinal = 2;; ordinal += 1) {
+            const candidate = withSuffix(base, ` · ${ordinal}`);
+            if (!used.has(collisionKey(candidate)))
+                return candidate;
+        }
+    }
+    const owner = harness === undefined ? 'Agent' : HARNESS_LABELS[harness];
+    const ownerCandidate = withSuffix(base, ` · ${owner}`);
+    if (!used.has(collisionKey(ownerCandidate)))
+        return ownerCandidate;
+    const timed = withSuffix(base, ` · ${owner} · ${formatSessionFirstSeen(now)}`);
+    if (!used.has(collisionKey(timed)))
+        return timed;
+    for (let ordinal = 2;; ordinal += 1) {
+        const candidate = withSuffix(timed, ` · ${ordinal}`);
+        if (!used.has(collisionKey(candidate)))
+            return candidate;
+    }
+}
+/**
+ * Freeze the first accepted human name for one immutable session.
+ *
+ * Explicit agent/User input wins, then a title supplied by a trusted harness
+ * adapter, then a generated fallback. Later sends reuse the frozen value
+ * even when their branch, worktree, title candidate, or notification changes.
+ */
+export function resolveSessionLabel(input) {
+    const now = input.now ?? Date.now();
+    const file = storePath(input.env);
+    const key = sessionKey(input.sessionId);
+    try {
+        return withFileLock(`${file}.lock`, () => {
+            const store = readStore(file);
+            const existing = store.sessions[key];
+            if (existing !== undefined) {
+                if (!isLegacyDateFallback(existing)) {
+                    return { ok: true, label: existing.label, source: existing.source };
+                }
+                const used = new Set(Object.entries(store.sessions)
+                    .filter(([storedKey]) => storedKey !== key)
+                    .map(([, record]) => collisionKey(record.label)));
+                const label = uniqueLabel(generatedSessionLabel(input.sessionId), 'fallback', input.harness ?? existing.harness, now, used);
+                store.sessions[key] = { ...existing, label };
+                writeStore(file, store);
+                return { ok: true, label, source: existing.source };
+            }
+            const explicit = explicitCandidate(input.explicitLabel, input);
+            if (explicit !== null && 'error' in explicit) {
+                return { ok: false, error: explicit.error };
+            }
+            const nativePending = harnessLabelIsPending(input.harnessLabel, input);
+            const native = nativePending ? null : harnessCandidate(input.harnessLabel, input);
+            if (explicit === null && nativePending) {
+                return {
+                    ok: false,
+                    error: "OpenCode is still generating this session's title; retry shortly or pass --session-label.",
+                };
+            }
+            const candidate = explicit ?? native ?? fallbackCandidate(input.sessionId);
+            const used = new Set(Object.values(store.sessions).map((record) => collisionKey(record.label)));
+            const label = uniqueLabel(candidate.label, candidate.source, input.harness, now, used);
+            store.sessions[key] = {
+                label,
+                source: candidate.source,
+                first_seen_at: now,
+                ...(input.harness === undefined ? {} : { harness: input.harness }),
+            };
+            writeStore(file, store);
+            return { ok: true, label, source: candidate.source };
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Could not persist this session's name: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=session-labels.js.map

package/dist/session-labels.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "type": "module",
   "description": "Send native phone notifications from agents and local programs",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "3.0.0",
+    "@raidiant/notifai-protocol": "4.0.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"

package/src/atomic-file.ts

@@ -57,6 +57,7 @@ export function atomicWriteFileSync(
     assertSameDirectory(directory, parent)
     assertUnchangedTarget(file, target)
     renameSync(temp, file)
+    syncDirectory(directory)
   } catch (err) {
     if (handle !== undefined) closeSync(handle)
     try {
@@ -68,6 +69,17 @@ export function atomicWriteFileSync(
   }
 }
 
+/** Persist the published directory entry where the host supports directory fsync. */
+function syncDirectory(directory: string): void {
+  if (process.platform === 'win32') return
+  const handle = openSync(directory, 'r')
+  try {
+    fsyncSync(handle)
+  } finally {
+    closeSync(handle)
+  }
+}
+
 /** Mode to preserve, or the mode for a new file. Refuses a non-regular target. */
 interface TargetMetadata {
   mode: number

package/src/commands-harness-context.ts

@@ -12,6 +12,10 @@ export interface ActiveHarnessSession {
   harness: Harness
   label: string
   sessionId?: string
+  /** Trusted human title published by this harness's managed adapter. */
+  sessionLabel?: string
+  /** The harness has only a temporary placeholder title so far. */
+  sessionLabelPending?: boolean
 }
 
 /**
@@ -26,10 +30,14 @@ function harnessEnvCandidates(env: NodeJS.ProcessEnv): ActiveHarnessSession[] {
   const candidates: ActiveHarnessSession[] = []
   if (env['NOTIFAI_ACTIVE_HARNESS'] === 'opencode') {
     const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
+    const sessionLabel = env['NOTIFAI_ACTIVE_SESSION_LABEL']
+    const sessionLabelPending = env['NOTIFAI_ACTIVE_SESSION_LABEL_PENDING'] === '1'
     candidates.push({
       harness: 'opencode',
       label: 'OpenCode',
       ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+      ...(sessionLabel === undefined || sessionLabel === '' ? {} : { sessionLabel }),
+      ...(sessionLabelPending ? { sessionLabelPending: true } : {}),
     })
   }
   if (env['CLAUDECODE'] === '1') {

package/src/commands-send-support.ts

@@ -25,8 +25,11 @@ export function resolveDraftInvocation(
           activeHarness: {
             harness: active.harness,
             ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
+            ...(active.sessionLabel === undefined ? {} : { sessionLabel: active.sessionLabel }),
+            ...(active.sessionLabelPending === true ? { sessionLabelPending: true } : {}),
           },
         }),
+    now: (deps.now ?? Date.now)(),
   })
   if (!source.ok) return source
   return {

package/src/commands.test.ts

@@ -500,11 +500,82 @@ describe('command contracts', () => {
       session_id: 'opaque-claude-session-42',
       harness: 'claude-code',
     })
-    expect(submitted?.draft.source?.session_label).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    expect(submitted?.draft.source?.session_label).toBe('Rapid Antelope')
     expect(io.outLines.join('\n')).not.toContain('opaque-claude-session-42')
     expect(io.errLines.join('\n')).not.toContain('opaque-claude-session-42')
   })
 
+  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()
+    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'),
+        NOTIFAI_ACTIVE_HARNESS: 'opencode',
+        NOTIFAI_ACTIVE_SESSION_ID: 'opencode-session',
+        NOTIFAI_ACTIVE_SESSION_LABEL: 'Semantic session names',
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Resolver implemented',
+        body: 'The first-party title was frozen locally.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: 'opencode-session',
+      session_label: 'Semantic session names',
+      harness: 'opencode',
+    })
+  })
+
+  it('does not freeze or submit an OpenCode placeholder title', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-opencode-pending-'))
+    const io = new CapturedIo()
+    let submitted = false
+    const client = {
+      submit: async () => {
+        submitted = true
+        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'),
+        NOTIFAI_ACTIVE_HARNESS: 'opencode',
+        NOTIFAI_ACTIVE_SESSION_ID: 'opencode-session',
+        NOTIFAI_ACTIVE_SESSION_LABEL_PENDING: '1',
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Resolver implemented',
+        body: 'Wait for the semantic title before freezing a name.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.usage)
+    expect(submitted).toBe(false)
+    expect(io.errLines.join('\n')).toContain('still generating this session')
+    expect(existsSync(path.join(cwd, 'state', 'notifai', 'session-labels.json'))).toBe(false)
+  })
+
   it('uploads repeatable images in order and sends only canonical media references', async () => {
     const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-media-order-'))
     const first = path.join(root, 'first.png')
@@ -653,7 +724,7 @@ describe('command contracts', () => {
       expect(grammar).not.toContain(".option('--session <")
       expect(grammar).toContain(".option('--body-file")
       expect(grammar).toContain(".option('--session-id")
-      expect(grammar).toContain(".option('--session-label")
+      expect(grammar).toContain("'--session-label <text>'")
       expect(grammar).toContain("'--image <path|url|media_id>'")
       expect(grammar).toContain("'--image-alt <text>'")
     }
@@ -4352,7 +4423,7 @@ describe('asking before the hooks have ever run', () => {
     })
     expect(
       readSessionState('codex-current-thread', env).pending?.[0]?.source?.session_label,
-    ).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/)
+    ).toBe('Gentle Salmon')
   })
 
   it('uploads ask images before registration and freezes canonical body media', async () => {

package/src/config.ts

@@ -188,9 +188,9 @@ export function globalConfigPath(env: NodeJS.ProcessEnv = process.env): string {
 }
 
 /**
- * Machine-local mutable state: presence markers, pending questions, and
- * session config overrides. Separate from the config dir because none of it is
- * user-authored and none of it should ever be synced or committed.
+ * Machine-local mutable state: presence markers, pending questions, frozen
+ * session names, and session config overrides. Separate from the config dir
+ * because none of it should ever be synced or committed.
  */
 export function stateDir(
   env: NodeJS.ProcessEnv = process.env,

package/src/generated-session-label.ts

@@ -0,0 +1,155 @@
+const FNV1A_64_OFFSET = 0xcbf29ce484222325n
+const FNV1A_64_PRIME = 0x100000001b3n
+const WORD_COUNT = 64n
+
+/** Frozen word lists keep generated fallbacks stable for a given opaque id. */
+const ADJECTIVES = [
+  'Amber',
+  'Arctic',
+  'Ash',
+  'Azure',
+  'Blue',
+  'Bold',
+  'Bright',
+  'Bronze',
+  'Calm',
+  'Cedar',
+  'Clear',
+  'Copper',
+  'Coral',
+  'Crisp',
+  'Dawn',
+  'Deep',
+  'Ember',
+  'Fern',
+  'Frost',
+  'Gentle',
+  'Golden',
+  'Green',
+  'Harbor',
+  'Hazel',
+  'Indigo',
+  'Ivory',
+  'Jade',
+  'Keen',
+  'Lively',
+  'Lunar',
+  'Maple',
+  'Meadow',
+  'Mellow',
+  'Misty',
+  'Noble',
+  'Ocean',
+  'Olive',
+  'Onyx',
+  'Quiet',
+  'Rapid',
+  'Red',
+  'River',
+  'Royal',
+  'Sage',
+  'Silver',
+  'Solar',
+  'Steady',
+  'Stone',
+  'Sunny',
+  'Swift',
+  'Teal',
+  'Timber',
+  'True',
+  'Velvet',
+  'Verdant',
+  'Violet',
+  'Warm',
+  'Wild',
+  'Winter',
+  'Wise',
+  'Witty',
+  'Yellow',
+  'Young',
+  'Zealous',
+] as const
+
+const NOUNS = [
+  'Alpaca',
+  'Antelope',
+  'Badger',
+  'Bear',
+  'Beaver',
+  'Bison',
+  'Bobcat',
+  'Caribou',
+  'Cougar',
+  'Coyote',
+  'Crane',
+  'Deer',
+  'Dolphin',
+  'Dragonfly',
+  'Eagle',
+  'Elk',
+  'Falcon',
+  'Finch',
+  'Firefly',
+  'Fox',
+  'Gazelle',
+  'Gecko',
+  'Hare',
+  'Heron',
+  'Ibex',
+  'Jay',
+  'Kestrel',
+  'Kingfisher',
+  'Koala',
+  'Lark',
+  'Leopard',
+  'Lynx',
+  'Magpie',
+  'Mantis',
+  'Marten',
+  'Moose',
+  'Osprey',
+  'Otter',
+  'Owl',
+  'Panda',
+  'Panther',
+  'Pelican',
+  'Penguin',
+  'Puma',
+  'Quail',
+  'Rabbit',
+  'Raven',
+  'Robin',
+  'Sable',
+  'Salmon',
+  'Seal',
+  'Shark',
+  'Sparrow',
+  'Stag',
+  'Swan',
+  'Tiger',
+  'Tortoise',
+  'Trout',
+  'Turtle',
+  'Viper',
+  'Whale',
+  'Wolf',
+  'Wren',
+  'Yak',
+] as const
+
+function fnv1a64(value: string): bigint {
+  let hash = FNV1A_64_OFFSET
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte)
+    hash = BigInt.asUintN(64, hash * FNV1A_64_PRIME)
+  }
+  return hash
+}
+
+/** Deterministic fallback for a session whose work has no semantic title. */
+export function generatedSessionLabel(sessionId: string): string {
+  const hash = fnv1a64(sessionId)
+  const adjective = ADJECTIVES[Number(hash % WORD_COUNT)]
+  const noun = NOUNS[Number((hash >> 6n) % WORD_COUNT)]
+  return `${adjective} ${noun}`
+}