@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/omp/rpc/frame.test.ts

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Bounded NDJSON framing for the omp RPC transport.
+ *
+ * Framing bugs are silent data corruption: a frame read as two lines, or a
+ * chunk sequence reassembled with the wrong bytes, reaches the session wrapper
+ * as a plausible-looking but wrong event. These tests pin the length boundary
+ * that selects single-line vs chunked encoding, the exact chunk sequence
+ * bookkeeping (ordering, count, declared byte length), the strict base64 and
+ * UTF-8 decoding, and the failure modes that must reject rather than guess.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  MAX_RPC_FRAME_BYTES,
+  MAX_RPC_REASSEMBLED_BYTES,
+  RpcFrameDecoder,
+  encodeRpcFrames,
+  type RpcFrameRecord,
+} from '@/shared/lib/omp/rpc/frame';
+
+/** A frame whose JSON is exactly `byteLength` bytes (ASCII pad ⇒ bytes = chars). */
+function frameOfBytes(byteLength: number): RpcFrameRecord {
+  const overhead = JSON.stringify({ type: 'x', pad: '' }).length;
+  return { type: 'x', pad: 'A'.repeat(byteLength - overhead) };
+}
+
+/** Chunk record with the defaults every case overrides one field of — keeping
+ *  them in lockstep is what makes a single-field override meaningful. */
+function chunk(overrides: Record<string, unknown>): Record<string, unknown> {
+  return { type: 'rpc_chunk', chunkId: 'c1', index: 0, count: 2, byteLength: MAX_RPC_FRAME_BYTES, data: 'AAAA', ...overrides };
+}
+
+describe('transport limits', () => {
+  test('the frame and reassembly ceilings are the documented values', () => {
+    expect(MAX_RPC_FRAME_BYTES).toBe(1024 * 1024);
+    expect(MAX_RPC_REASSEMBLED_BYTES).toBe(64 * 1024 * 1024);
+  });
+});
+
+describe('encodeRpcFrames — single-line path', () => {
+  test('a small frame is one JSON line terminated by a newline', () => {
+    const frame = { type: 'ready', n: 1 };
+    expect(encodeRpcFrames(frame, 1, 'chunk')).toEqual([`${JSON.stringify(frame)}\n`]);
+  });
+
+  test('the exact boundary is a frame whose JSON is MAX-1 bytes (plus newline = MAX)', () => {
+    const frame = frameOfBytes(MAX_RPC_FRAME_BYTES - 1);
+    const lines = encodeRpcFrames(frame, 1, 'chunk');
+    expect(lines.length).toBe(1);
+    expect(lines[0].length).toBe(MAX_RPC_FRAME_BYTES);
+  });
+
+  test('one byte over the boundary stops being a single line', () => {
+    const frame = frameOfBytes(MAX_RPC_FRAME_BYTES);
+    // v1 has no fallback: an oversized frame is a hard error.
+    expect(() => encodeRpcFrames(frame, 1, 'chunk')).toThrow('RPC frame exceeds the v1 transport limit');
+  });
+});
+
+describe('encodeRpcFrames — v2 chunking', () => {
+  test('an oversized frame becomes a contiguous chunk sequence that round-trips', () => {
+    const frame = frameOfBytes(MAX_RPC_FRAME_BYTES + 5_000);
+    const lines = encodeRpcFrames(frame, 2, 'chunk-1');
+    const payload = new TextEncoder().encode(JSON.stringify(frame));
+    const expectedCount = Math.ceil(payload.byteLength / (256 * 1024));
+    expect(lines.length).toBe(expectedCount);
+
+    const decoder = new RpcFrameDecoder();
+    const records = lines.map((line) => JSON.parse(line));
+    for (let i = 0; i < records.length; i++) {
+      expect(records[i].type).toBe('rpc_chunk');
+      expect(records[i].chunkId).toBe('chunk-1');
+      expect(records[i].index).toBe(i);
+      expect(records[i].count).toBe(expectedCount);
+      expect(records[i].byteLength).toBe(payload.byteLength);
+      expect(lines[i].endsWith('\n')).toBe(true);
+      // Every push before the last must yield nothing — the decoder is holding
+      // an incomplete logical frame.
+      const out = decoder.push(records[i]);
+      if (i < records.length - 1) expect(out).toBeUndefined();
+      else expect(out).toEqual(frame);
+    }
+  });
+
+  test('a frame over the reassembly ceiling is refused before chunking', () => {
+    const frame = { type: 'x', pad: 'A'.repeat(MAX_RPC_REASSEMBLED_BYTES) };
+    expect(() => encodeRpcFrames(frame, 2, 'chunk')).toThrow('RPC frame exceeds the v2 reassembly limit');
+  });
+});
+
+describe('RpcFrameDecoder — plain frames', () => {
+  test('a record with a string type passes through unchanged', () => {
+    const decoder = new RpcFrameDecoder();
+    const frame = { type: 'message_update', text: 'hi' };
+    expect(decoder.push(frame)).toBe(frame);
+  });
+
+  test('an unknown type is still a valid frame', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(decoder.push({ type: 'something_new' })).toEqual({ type: 'something_new' });
+  });
+
+  test('non-records and typeless records are rejected', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(null)).toThrow('RPC frame must be an object');
+    expect(() => decoder.push([1, 2])).toThrow('RPC frame must be an object');
+    expect(() => decoder.push('nope')).toThrow('RPC frame must be an object');
+    expect(() => decoder.push({ noType: 1 })).toThrow('RPC frame must be an object');
+  });
+});
+
+describe('RpcFrameDecoder — chunk metadata validation', () => {
+  test('a sequence that does not start at index 0 is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ index: 1 }))).toThrow('RPC chunk sequence must start at index 0');
+  });
+
+  test('a single-chunk sequence is impossible: count must be >= 2', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ count: 1 }))).toThrow('invalid RPC chunk metadata');
+  });
+
+  test('an index at or past the count is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ index: 2, count: 2 }))).toThrow('invalid RPC chunk metadata');
+  });
+
+  test('a declared byte length below the frame limit is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ byteLength: MAX_RPC_FRAME_BYTES - 1 }))).toThrow('invalid RPC chunk metadata');
+  });
+
+  test('missing/empty/oversized chunk ids and non-integer numbers are refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ chunkId: '' }))).toThrow('invalid RPC chunk metadata');
+    expect(() => decoder.push(chunk({ chunkId: 'x'.repeat(129) }))).toThrow('invalid RPC chunk metadata');
+    expect(() => decoder.push(chunk({ chunkId: 7 }))).toThrow('invalid RPC chunk metadata');
+    expect(() => decoder.push(chunk({ index: 0.5 }))).toThrow('invalid RPC chunk metadata');
+    expect(() => decoder.push(chunk({ byteLength: Number.MAX_SAFE_INTEGER + 1 }))).toThrow('invalid RPC chunk metadata');
+  });
+
+  test('non-canonical base64 is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ data: '' }))).toThrow('invalid RPC chunk data');
+    expect(() => decoder.push(chunk({ data: 'AAAA=' }))).toThrow('invalid RPC chunk data');
+    expect(() => decoder.push(chunk({ data: '!!!!' }))).toThrow('invalid RPC chunk data');
+    expect(() => decoder.push(chunk({ data: 42 }))).toThrow('invalid RPC chunk data');
+  });
+
+  test('a chunk payload larger than the transport slice is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(() => decoder.push(chunk({ data: new Uint8Array(256 * 1024 + 1).fill(65).toBase64() }))).toThrow(
+      'RPC chunk payload exceeds the transport limit',
+    );
+  });
+});
+
+describe('RpcFrameDecoder — sequence bookkeeping', () => {
+  test('a plain frame arriving mid-sequence is an interruption', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(decoder.push(chunk({ data: new Uint8Array(1024).fill(65).toBase64() }))).toBeUndefined();
+    expect(() => decoder.push({ type: 'ready' })).toThrow('RPC chunk sequence interrupted');
+  });
+
+  test('a mismatched chunk id or count is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(decoder.push(chunk({ data: new Uint8Array(1024).fill(65).toBase64() }))).toBeUndefined();
+    expect(() => decoder.push(chunk({ index: 1, chunkId: 'other', data: new Uint8Array(1024).fill(65).toBase64() }))).toThrow(
+      'RPC chunk sequence mismatch',
+    );
+  });
+
+  test('a skipped index is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(decoder.push(chunk({ count: 3, data: new Uint8Array(1024).fill(65).toBase64() }))).toBeUndefined();
+    expect(() => decoder.push(chunk({ count: 3, index: 2, data: new Uint8Array(1024).fill(65).toBase64() }))).toThrow(
+      'RPC chunk sequence mismatch',
+    );
+  });
+
+  test('a completed sequence whose bytes do not match the declared length is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    expect(decoder.push(chunk({ data: new Uint8Array(256 * 1024).fill(65).toBase64() }))).toBeUndefined();
+    expect(() => decoder.push(chunk({ index: 1, data: new Uint8Array(256 * 1024).fill(65).toBase64() }))).toThrow(
+      'RPC chunk sequence length mismatch',
+    );
+  });
+
+  test('bytes past the declared length are refused immediately', () => {
+    const decoder = new RpcFrameDecoder();
+    for (let index = 0; index < 4; index++) {
+      expect(decoder.push(chunk({ count: 5, index, data: new Uint8Array(256 * 1024).fill(65).toBase64() }))).toBeUndefined();
+    }
+    expect(() => decoder.push(chunk({ count: 5, index: 4, data: new Uint8Array(256 * 1024).fill(65).toBase64() }))).toThrow(
+      'RPC chunk sequence exceeds declared length',
+    );
+  });
+
+  test('a reassembled payload that is not a frame record is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    const padded = new Uint8Array(MAX_RPC_FRAME_BYTES).fill(32);
+    padded.set(new TextEncoder().encode('[1,2,3]'), 0);
+    // Declared length must be >= the frame limit and equal the real byte count;
+    // the payload is split into 256 KiB slices, the largest a chunk may carry.
+    const base = { chunkId: 'c', count: 4, byteLength: padded.byteLength };
+    for (let index = 0; index < 3; index++) {
+      const slice = padded.subarray(index * 256 * 1024, (index + 1) * 256 * 1024).toBase64();
+      expect(decoder.push({ type: 'rpc_chunk', ...base, index, data: slice })).toBeUndefined();
+    }
+    const last = padded.subarray(3 * 256 * 1024).toBase64();
+    expect(() => decoder.push({ type: 'rpc_chunk', ...base, index: 3, data: last })).toThrow('RPC frame must be an object');
+  });
+
+  test('a reassembled payload with a truncated UTF-8 sequence is refused', () => {
+    const decoder = new RpcFrameDecoder();
+    const padded = new Uint8Array(MAX_RPC_FRAME_BYTES).fill(32);
+    // 0xE2 0x82 is the start of a 3-byte sequence with its tail missing.
+    padded.set([0xe2, 0x82], 0);
+    const base = { chunkId: 'c', count: 4, byteLength: padded.byteLength };
+    for (let index = 0; index < 3; index++) {
+      const slice = padded.subarray(index * 256 * 1024, (index + 1) * 256 * 1024).toBase64();
+      expect(decoder.push({ type: 'rpc_chunk', ...base, index, data: slice })).toBeUndefined();
+    }
+    const last = padded.subarray(3 * 256 * 1024).toBase64();
+    // The bytes never reach JSON.parse: the strict decoder rejects them first.
+    expect(() => decoder.push({ type: 'rpc_chunk', ...base, index: 3, data: last })).toThrow();
+  });
+
+  test('a fresh sequence can start after a completed one', () => {
+    const decoder = new RpcFrameDecoder();
+    const frame = frameOfBytes(MAX_RPC_FRAME_BYTES + 1_000);
+    for (const line of encodeRpcFrames(frame, 2, 'a')) decoder.push(JSON.parse(line));
+    expect(decoder.push({ type: 'ready' })).toEqual({ type: 'ready' });
+  });
+});

package/src/shared/lib/omp/rpc/frame.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Bounded protocol-v2 framing for OMP's NDJSON RPC transport.
+ *
+ * Faithful port of omp-web/lib/omp/rpc-frame.ts. Logical RPC frames are
+ * carried as single JSONL lines when small; frames larger than the transport
+ * limit are split into `rpc_chunk` sequences (base64 payloads) and
+ * reassembled on the receiving side.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+export const MAX_RPC_FRAME_BYTES = 1024 * 1024;
+export const MAX_RPC_REASSEMBLED_BYTES = 64 * 1024 * 1024;
+const RPC_CHUNK_PAYLOAD_BYTES = 256 * 1024;
+
+export type RpcProtocolVersion = 1 | 2;
+export type RpcFrameRecord = { type: string; [key: string]: unknown };
+
+interface PendingChunks {
+  chunkId: string;
+  count: number;
+  byteLength: number;
+  nextIndex: number;
+  chunks: Uint8Array[];
+  receivedBytes: number;
+}
+
+function isSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value);
+}
+
+/**
+ * One encoder for every length check on this path.
+ *
+ * `encode()` allocates a throwaway array just to read `.byteLength`, and this
+ * runs once per frame written to the child's stdin — every `message_update`,
+ * every steer, every tool result. Hoisting it measured 17.2 ms → 8.6 ms per
+ * 200k checks. A hoisted encoder rather than `Buffer.byteLength` because this
+ * module is in `src/shared/` and is therefore browser-safe: `Buffer` is not.
+ */
+const utf8 = new TextEncoder();
+/** Strict decoder for reassembled chunk payloads — a truncated sequence is an error. */
+const fatalUtf8 = new TextDecoder('utf-8', { fatal: true });
+
+function utf8ByteLength(value: string): number {
+  return utf8.encode(value).byteLength;
+}
+
+function lineByteLength(value: string): number {
+  return utf8ByteLength(value) + 1;
+}
+
+/** Strict base64 decode (canonical padding + round-trip equality). */
+function decodeBase64(value: unknown): Uint8Array {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  ) throw new Error('invalid RPC chunk data');
+  let bytes: Uint8Array;
+  try {
+    bytes = Uint8Array.fromBase64(value, { lastChunkHandling: 'strict' });
+  } catch {
+    throw new Error('invalid RPC chunk data');
+  }
+  if (bytes.toBase64() !== value) throw new Error('invalid RPC chunk data');
+  return bytes;
+}
+
+function concatChunks(chunks: Uint8Array[], byteLength: number): Uint8Array {
+  const merged = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return merged;
+}
+
+/** Decodes complete logical frames from parsed JSONL records. */
+export class RpcFrameDecoder {
+  private pending: PendingChunks | undefined;
+
+  push(value: unknown): RpcFrameRecord | undefined {
+    if (!isRecord(value) || value.type !== 'rpc_chunk') {
+      if (this.pending) throw new Error('RPC chunk sequence interrupted');
+      if (!isRecord(value) || typeof value.type !== 'string') throw new Error('RPC frame must be an object');
+      return value as RpcFrameRecord;
+    }
+    const { chunkId, index, count, byteLength } = value;
+    if (
+      typeof chunkId !== 'string' || chunkId.length === 0 || chunkId.length > 128 ||
+      !isSafeInteger(index) || !isSafeInteger(count) || !isSafeInteger(byteLength) ||
+      index < 0 || count < 2 || count > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||
+      index >= count || byteLength < MAX_RPC_FRAME_BYTES || byteLength > MAX_RPC_REASSEMBLED_BYTES
+    ) throw new Error('invalid RPC chunk metadata');
+
+    const bytes = decodeBase64(value.data);
+    if (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error('RPC chunk payload exceeds the transport limit');
+    if (!this.pending) {
+      if (index !== 0) throw new Error('RPC chunk sequence must start at index 0');
+      this.pending = { chunkId, count, byteLength, nextIndex: 0, chunks: [], receivedBytes: 0 };
+    }
+    const pending = this.pending!;
+    if (pending.chunkId !== chunkId || pending.count !== count || pending.byteLength !== byteLength || pending.nextIndex !== index) {
+      throw new Error('RPC chunk sequence mismatch');
+    }
+    pending.chunks.push(bytes);
+    pending.receivedBytes += bytes.byteLength;
+    pending.nextIndex++;
+    if (pending.receivedBytes > pending.byteLength) throw new Error('RPC chunk sequence exceeds declared length');
+    if (pending.nextIndex < pending.count) return undefined;
+    if (pending.receivedBytes !== pending.byteLength) throw new Error('RPC chunk sequence length mismatch');
+
+    this.pending = undefined;
+    const json = fatalUtf8.decode(concatChunks(pending.chunks, pending.byteLength));
+    const frame: unknown = JSON.parse(json);
+    if (!isRecord(frame) || typeof frame.type !== 'string') throw new Error('RPC frame must be an object');
+    return frame as RpcFrameRecord;
+  }
+}
+
+/** Physical JSONL records for a logical RPC frame at the selected protocol. */
+export function encodeRpcFrames(frame: RpcFrameRecord, protocolVersion: RpcProtocolVersion, chunkId: string): string[] {
+  const json = JSON.stringify(frame);
+  // Encode once and keep the bytes: the length check needs them either way, and
+  // the oversized path below needs them again. Previously this encoded the
+  // whole frame to measure it, discarded that array, then encoded it a second
+  // time to slice it.
+  const bytes = utf8.encode(json);
+  if (bytes.byteLength + 1 <= MAX_RPC_FRAME_BYTES) return [`${json}\n`];
+  if (protocolVersion === 1) throw new Error('RPC frame exceeds the v1 transport limit');
+  if (bytes.byteLength > MAX_RPC_REASSEMBLED_BYTES) throw new Error('RPC frame exceeds the v2 reassembly limit');
+  const count = Math.ceil(bytes.byteLength / RPC_CHUNK_PAYLOAD_BYTES);
+  const lines: string[] = [];
+  for (let index = 0; index < count; index++) {
+    const chunk = {
+      type: 'rpc_chunk', chunkId, index, count, byteLength: bytes.byteLength,
+      data: bytes.subarray(index * RPC_CHUNK_PAYLOAD_BYTES, (index + 1) * RPC_CHUNK_PAYLOAD_BYTES).toBase64(),
+    };
+    const line = JSON.stringify(chunk);
+    if (lineByteLength(line) > MAX_RPC_FRAME_BYTES) throw new Error('RPC chunk exceeds the transport limit');
+    lines.push(`${line}\n`);
+  }
+  return lines;
+}

package/src/shared/lib/omp/session/default-title.test.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { formatNewSessionTitle, isPendingSessionId, pendingSessionCreatedAt, pendingSessionTitle, sessionIdEpochMs } from '@/shared/lib/omp/session/default-title';
+
+describe('pendingSessionCreatedAt', () => {
+  test('parses the epoch out of a pending session id', () => {
+    expect(pendingSessionCreatedAt('new-1737000000000')).toBe(1737000000000);
+  });
+
+  test('is NaN for a real omp UUID', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt('01a08410-8135-772c-b1cc-9ceed604deec'))).toBe(true);
+  });
+
+  test('treats a bare prefix as epoch 0 because Number("") is 0', () => {
+    expect(pendingSessionCreatedAt('new-')).toBe(0);
+  });
+
+  test('is NaN for a non-numeric suffix', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt('new-abc'))).toBe(true);
+  });
+
+  test('is NaN for null and undefined', () => {
+    expect(Number.isNaN(pendingSessionCreatedAt(null))).toBe(true);
+    expect(Number.isNaN(pendingSessionCreatedAt(undefined))).toBe(true);
+  });
+});
+
+describe('sessionIdEpochMs', () => {
+  test('decodes the creation clock from a v7 session id', () => {
+    // The id and the clock below are a real pair: this session's own JSONL was
+    // created at 2026-10-03T00:50:11.431Z.
+    expect(sessionIdEpochMs('01a0ff3d-6f67-726d-b0ff-8e6a0d7d0e4a')).toBe(1790988611431);
+  });
+
+  test('is NaN for a v4 UUID, which carries no clock', () => {
+    expect(Number.isNaN(sessionIdEpochMs('110ec58a-a0f2-4ac4-8393-c866d813b8d1'))).toBe(true);
+  });
+
+  test('is NaN for pending, empty and malformed ids', () => {
+    expect(Number.isNaN(sessionIdEpochMs('new-1737000000000'))).toBe(true);
+    expect(Number.isNaN(sessionIdEpochMs(''))).toBe(true);
+    expect(Number.isNaN(sessionIdEpochMs(null))).toBe(true);
+    expect(Number.isNaN(sessionIdEpochMs('01a0ff3d6f6772'))).toBe(true);
+  });
+});
+
+describe('pendingSessionTitle', () => {
+  test('reflects the id epoch rather than the current clock', () => {
+    const title = pendingSessionTitle('new-1737000000000');
+    expect(title).toContain('New Session - ');
+    expect(title).toBe(formatNewSessionTitle(new Date(1737000000000)));
+  });
+
+  test('names an adopted v7 session id by ITS clock, so the row does not churn', () => {
+    // The sidebar renders this title while omp's transcript scan cannot see the
+    // session yet. Stamping it with `new Date()` advanced the seconds on every
+    // revalidate; the id's own clock holds still across calls.
+    const id = '01a0ff3d-6f67-726d-b0ff-8e6a0d7d0e4a';
+    const first = pendingSessionTitle(id);
+    expect(first).toBe(formatNewSessionTitle(new Date(sessionIdEpochMs(id))));
+    expect(pendingSessionTitle(id)).toBe(first);
+  });
+
+  test('falls back to now for a non-numeric id without throwing', () => {
+    expect(pendingSessionTitle('new-not-a-number').startsWith('New Session')).toBe(true);
+  });
+});
+
+describe('isPendingSessionId', () => {
+  test('is true for a pending id and false for a settled one', () => {
+    expect(isPendingSessionId('new-1737000000000')).toBe(true);
+    expect(isPendingSessionId('ses_alpha')).toBe(false);
+  });
+});

package/src/shared/lib/omp/session/default-title.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Default display titles for sessions that have no user/auto name yet.
+ *
+ * A brand-new session must still be distinguishable in the sidebar and navbar
+ * before omp derives a real title (first prompt / JSONL title slot), so the
+ * default carries the creation timestamp:
+ *
+ *   New Session - yyyy-mm-ddThh:mm:ss
+ *
+ * The timestamp is local time and is stable per session: pending sessions take
+ * it from their `new-<epochMs>` id, persisted sessions from the JSONL header
+ * timestamp — two nameless sessions can never render the same title.
+ */
+
+const PENDING_SESSION_PREFIX = 'new-';
+
+function pad2(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+/** `New Session - yyyy-mm-ddThh:mm:ss` (local time); plain "New Session" when
+ *  the date is invalid. */
+export function formatNewSessionTitle(date: Date = new Date()): string {
+  if (Number.isNaN(date.getTime())) return 'New Session';
+  return `New Session - ${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
+}
+
+/** True for client-side pending session ids (`new-<epochMs>`, pre-spawn). */
+export function isPendingSessionId(sessionId: string | null | undefined): boolean {
+  return Boolean(sessionId?.startsWith(PENDING_SESSION_PREFIX));
+}
+
+/** Creation epoch (ms) encoded in a pending session id (`new-<epochMs>`);
+ *  NaN for any other id, including real omp UUIDs. */
+export function pendingSessionCreatedAt(sessionId: string | null | undefined): number {
+  return sessionId?.startsWith(PENDING_SESSION_PREFIX)
+    ? Number(sessionId.slice(PENDING_SESSION_PREFIX.length))
+    : Number.NaN;
+}
+
+/**
+ * Creation epoch (ms) carried by an omp session id itself.
+ *
+ * omp ids are UUIDv7, whose leading 48 bits are the generation time in
+ * milliseconds — so an id the sidebar must render BEFORE omp's transcript scan
+ * can surface it still knows when its session was created. Verified against
+ * the session files: `01a0ff3d-6f67-…` decodes to 2026-10-03T00:50:11.431Z,
+ * which is that file's own creation clock.
+ *
+ * This is what keeps a placeholder row still. The caller used to fall back to
+ * `new Date()` for a non-pending id, so every revalidation re-stamped the row
+ * with the CURRENT clock: the title advanced on each list refresh (measured:
+ * 07:53:13 → :14 → :18 → :26 within one run) and the row's `updated_at` was
+ * perpetually "now", which re-shuffled LATEST_SESSION ordering each time.
+ *
+ * NaN for anything that is not a v7 UUID (a legacy v4 id, a Kabmo id), so
+ * the caller's own fallback still applies.
+ */
+export function sessionIdEpochMs(sessionId: string | null | undefined): number {
+  // `xxxxxxxx-xxxx-7xxx-…`: 8 hex, '-', 4 hex, '-', then the version nibble.
+  if (!sessionId || sessionId.length < 15 || sessionId[8] !== '-' || sessionId[13] !== '-' || sessionId[14] !== '7') {
+    return Number.NaN;
+  }
+  const ms = Number.parseInt(sessionId.slice(0, 8) + sessionId.slice(9, 13), 16);
+  return Number.isFinite(ms) ? ms : Number.NaN;
+}
+
+/** Default title of a client-side pending session; the id carries its
+ *  creation epoch (`new-<epochMs>`). An adopted omp UUID carries one in its v7
+ *  prefix instead, and using it is what keeps the row's text still: the
+ *  `new Date()` fallback re-stamped the title on every revalidate, so the
+ *  seconds advanced on each list refresh (measured 07:53:13 → :14 → :18 → :26
+ *  within one run) instead of naming the moment the session was created. */
+export function pendingSessionTitle(sessionId: string | null | undefined): string {
+  const epochMs = pendingSessionCreatedAt(sessionId);
+  const stableMs = Number.isFinite(epochMs) ? epochMs : sessionIdEpochMs(sessionId);
+  return formatNewSessionTitle(Number.isFinite(stableMs) ? new Date(stableMs) : new Date());
+}

package/src/shared/lib/omp/session/hashline-patch.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'bun:test';
+import { hashlinePatchFromArgs, hashlineTargetPath, parseHashlinePatch } from '@/shared/lib/omp/session/hashline-patch';
+
+/** Real args a model sent for `edit`: `{i, input}` with no delimiter wrapper. */
+const REAL_INPUT = '[app/components/workspace/chat-timeline/UndoConfirmModal.tsx#A328]\nCUT 18.=18';
+
+describe('parseHashlinePatch', () => {
+  test('reads the header and a bodyless op from a wrapper-less patch', () => {
+    const [section] = parseHashlinePatch(REAL_INPUT);
+    expect(section.path).toBe('app/components/workspace/chat-timeline/UndoConfirmModal.tsx');
+    expect(section.tag).toBe('A328');
+    expect(section.removed).toBe(false);
+    expect(section.ops).toEqual([{ verb: 'CUT', spec: '18.=18', body: [] }]);
+  });
+
+  test('keeps body rows verbatim — indent, blank and escaped markers', () => {
+    const [section] = parseHashlinePatch(
+      [
+        '*** Begin Patch',
+        '[app/x.ts#0a1b]',
+        'PUT 3.=3:',
+        '+  if (dry) return;',
+        '+',
+        '+- literal minus',
+        '++ literal plus',
+        '*** End Patch',
+      ].join('\n'),
+    );
+    expect(section.ops).toHaveLength(1);
+    expect(section.ops[0].verb).toBe('PUT');
+    expect(section.ops[0].spec).toBe('3.=3');
+    expect(section.ops[0].body).toEqual(['+  if (dry) return;', '+', '+- literal minus', '++ literal plus']);
+  });
+
+  test('treats REM and MV as section-level file ops', () => {
+    const [section] = parseHashlinePatch('[app/old.ts#beef]\nREM');
+    expect(section.removed).toBe(true);
+    expect(section.ops).toEqual([]);
+
+    const [moved] = parseHashlinePatch('[app/old.ts#beef]\nMV app/new.ts');
+    expect(moved.moveTo).toBe('app/new.ts');
+  });
+
+  test('parses gap, block and register ops, and splits sections', () => {
+    const sections = parseHashlinePatch(
+      [
+        '[app/a.ts#1111]',
+        'PUT <4:',
+        '+before',
+        'PUT >$ @tail',
+        '[app/b.ts#2222]',
+        'PUT 7*:',
+        '+replaced block',
+      ].join('\n'),
+    );
+    expect(sections.map((s) => s.path)).toEqual(['app/a.ts', 'app/b.ts']);
+    expect(sections[0].ops.map((op) => op.spec)).toEqual(['<4', '>$ @tail']);
+    expect(sections[1].ops[0].spec).toBe('7*');
+  });
+
+  test('accepts a missing closing bracket and a quoted path', () => {
+    expect(parseHashlinePatch('[app/x.ts#0000').at(0)?.path).toBe('app/x.ts');
+    expect(parseHashlinePatch('["app/with space.ts"#0000]\nCUT 1.=1').at(0)?.path).toBe('app/with space.ts');
+    expect(parseHashlinePatch('["app/with space.ts"]\nCUT 1.=1').at(0)?.path).toBe('app/with space.ts');
+    // omp strips the tag before the quotes, so a tag *inside* the quotes stays
+    // part of the path — mirrored here rather than silently "corrected".
+    expect(parseHashlinePatch('["app/x.ts#0000"]\nCUT 1.=1').at(0)?.path).toBe('app/x.ts#0000');
+    // Only a 4-hex suffix is a snapshot tag; anything else stays in the path.
+    expect(parseHashlinePatch('[app/x.ts#HEAD]\nCUT 1.=1').at(0)?.path).toBe('app/x.ts#HEAD');
+  });
+
+  test('returns nothing for non-patch text', () => {
+    expect(parseHashlinePatch('app/components/Foo.tsx')).toEqual([]);
+    expect(parseHashlinePatch('')).toEqual([]);
+  });
+});
+
+describe('hashline patch in tool args', () => {
+  test('finds the patch under `input` and derives the target path', () => {
+    const args = { i: 'Hapus deklarasi handler duplikat modal', input: REAL_INPUT };
+    expect(hashlinePatchFromArgs(args)?.text).toBe(REAL_INPUT);
+    expect(hashlineTargetPath(args)).toBe('app/components/workspace/chat-timeline/UndoConfirmModal.tsx');
+  });
+
+  test('ignores args that carry no hashline patch', () => {
+    expect(hashlineTargetPath({ i: 'x', path: 'app/y.ts', old_string: 'a' })).toBeUndefined();
+    expect(hashlineTargetPath(undefined)).toBeUndefined();
+  });
+});