@vybestack/llxprt-code-core 0.10.0 → 0.11.0-nightly.260728.ffaa8d5d7

package/src/recording/ReplayEngine.ts

@@ -147,10 +147,21 @@ function handleSessionStart(
     return undefined;
   }
   const startPayload = payload as unknown as SessionStartPayload;
-  if (!startPayload.sessionId || !startPayload.projectHash) {
+  const requiredStrings = [
+    startPayload.sessionId,
+    startPayload.projectHash,
+    startPayload.provider,
+    startPayload.model,
+    startPayload.startTime,
+  ];
+  if (
+    requiredStrings.some(
+      (value) => typeof value !== 'string' || value.length === 0,
+    )
+  ) {
     return {
       ok: false,
-      error: 'Invalid session_start: missing required fields',
+      error: 'Invalid session_start: missing or malformed required fields',
       warnings: acc.warnings,
     };
   }
@@ -167,6 +178,7 @@ function handleSessionStart(
     provider: startPayload.provider,
     model: startPayload.model,
     workspaceDirs: resolveWorkspaceDirs(startPayload.workspaceDirs),
+    ...(typeof startPayload.cwd === 'string' ? { cwd: startPayload.cwd } : {}),
     startTime: startPayload.startTime,
   };
   return undefined;
@@ -289,6 +301,40 @@ function handleSessionEvent(
   }
 }
 
+/**
+ * @requirement issue #1611: session_metadata — update metadata.title (tri-state).
+ *
+ * The title is tri-state: undefined (field absent) is legacy and does NOT
+ * modify metadata.title; null sets it to null (explicit untitled); string sets
+ * it to that string. Malformed title values (non-string, non-null, non-
+ * undefined) are recorded as malformed.
+ */
+function handleSessionMetadata(
+  payload: Record<string, unknown>,
+  acc: ReplayAccumulators,
+  lineNumber: number,
+): void {
+  if (acc.metadata === null) {
+    acc.malformedCount++;
+    acc.warnings.push(
+      `Line ${lineNumber}: session_metadata before session_start, skipping`,
+    );
+    return;
+  }
+  if (!('title' in payload)) {
+    return;
+  }
+  const title = payload.title;
+  if (title === null || typeof title === 'string') {
+    acc.metadata.title = title;
+  } else if (title !== undefined) {
+    acc.malformedCount++;
+    acc.warnings.push(
+      `Line ${lineNumber}: malformed session_metadata title, skipping`,
+    );
+  }
+}
+
 /** @pseudocode line 126-131: directories_changed — update metadata or record malformed. */
 function handleDirectoriesChanged(
   payload: Record<string, unknown>,
@@ -381,6 +427,9 @@ function dispatchEvent(
     case 'session_event':
       handleSessionEvent(payload, acc, lineNumber);
       break;
+    case 'session_metadata':
+      handleSessionMetadata(payload, acc, lineNumber);
+      break;
     case 'directories_changed':
       handleDirectoriesChanged(payload, acc, lineNumber);
       break;

package/src/recording/SessionDiscovery.ts

@@ -24,10 +24,21 @@
  * for the resume flow.
  */
 
+import { createReadStream } from 'node:fs';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { type SessionSummary, type SessionStartPayload } from './types.js';
+import * as readline from 'node:readline';
+import {
+  SESSION_TITLE_MAX_LENGTH,
+  type SessionSummary,
+  type SessionStartPayload,
+} from './types.js';
 import { readSessionHeader } from './ReplayEngine.js';
+import {
+  resumeSessionIndexOutOfRangeMessage,
+  resumeSessionNotFoundMessage,
+} from './resumeNotFoundMessages.js';
+import { debugLogger } from '../utils/debugLogger.js';
 
 /**
  * Result of successfully resolving a session reference.
@@ -163,7 +174,7 @@ export class SessionDiscovery {
         return { session: sessions[indexNum - 1] };
       }
       return {
-        error: `Session index ${ref} out of range (1-${sessions.length})`,
+        error: resumeSessionIndexOutOfRangeMessage(indexNum, sessions.length),
       };
     }
 
@@ -176,7 +187,7 @@ export class SessionDiscovery {
       };
     }
 
-    return { error: `Session not found for this project: ${ref}` };
+    return { error: resumeSessionNotFoundMessage(ref) };
   }
 
   /**
@@ -268,7 +279,7 @@ export class SessionDiscovery {
    */
   static async readFirstUserMessage(
     filePath: string,
-    maxLength: number = 120,
+    maxLength: number = SESSION_TITLE_MAX_LENGTH,
   ): Promise<string | null> {
     try {
       const fileContent = await fs.readFile(filePath, 'utf-8');
@@ -284,6 +295,44 @@ export class SessionDiscovery {
       return null;
     }
   }
+
+  /**
+   * Read the tri-state title from the last valid `session_metadata` event in a
+   * session file (issue #1611). Returns:
+   * - `undefined` when no `session_metadata` event exists (legacy fallback).
+   * - `null` when the event explicitly asserts untitled.
+   * - `string` when the event carries a concrete title.
+   */
+  static async readSessionMetadataTitle(
+    filePath: string,
+  ): Promise<string | null | undefined> {
+    let stream: ReturnType<typeof createReadStream> | undefined;
+    let reader: readline.Interface | undefined;
+    try {
+      stream = createReadStream(filePath, { encoding: 'utf8' });
+      reader = readline.createInterface({
+        input: stream,
+        crlfDelay: Infinity,
+      });
+      let title: string | null | undefined;
+      for await (const line of reader) {
+        const result = extractSessionMetadataTitle(line);
+        if (result !== undefined) {
+          title = result;
+        }
+      }
+      return title;
+    } catch (error) {
+      debugLogger.debug(
+        () =>
+          `readSessionMetadataTitle failed for ${filePath}: ${String(error)}`,
+      );
+      return undefined;
+    } finally {
+      reader?.close();
+      stream?.destroy();
+    }
+  }
 }
 
 async function readSessionSummary(
@@ -310,6 +359,10 @@ async function readSessionSummary(
     fileSize: stat.size,
     provider: header.provider,
     model: header.model,
+    ...(typeof header.cwd === 'string' ? { cwd: header.cwd } : {}),
+    ...(typeof header.startTime === 'string'
+      ? { createdAt: header.startTime }
+      : {}),
   };
 }
 
@@ -367,3 +420,45 @@ function extractUserMessageText(line: string): string | null {
 
   return text || null;
 }
+
+/**
+ * Extract the title from a `session_metadata` JSONL line.
+ * Returns:
+ * - `undefined` when the line is not a valid `session_metadata` event (so
+ *   callers can continue scanning).
+ * - `null` when title is explicitly null (untitled).
+ * - `string` when a concrete title is present.
+ */
+function extractSessionMetadataTitle(line: string): string | null | undefined {
+  if (!line.trim()) {
+    return undefined;
+  }
+  let event: unknown;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+  if (event === null || typeof event !== 'object') {
+    return undefined;
+  }
+  const record = event as Record<string, unknown>;
+  if (record.type !== 'session_metadata') {
+    return undefined;
+  }
+  const payload = record.payload as Record<string, unknown> | undefined;
+  if (!payload || typeof payload !== 'object') {
+    return undefined;
+  }
+  if (!('title' in payload)) {
+    return undefined;
+  }
+  const title = payload.title;
+  if (title === null) {
+    return null;
+  }
+  if (typeof title === 'string') {
+    return title;
+  }
+  return undefined;
+}

package/src/recording/SessionLockManager.ts

@@ -37,6 +37,13 @@ export interface LockHandle {
   release(): Promise<void>;
 }
 
+export class SessionLockedError extends Error {
+  constructor() {
+    super('Session is in use by another process');
+    this.name = 'SessionLockedError';
+  }
+}
+
 /** @pseudocode concurrency-lifecycle.md lines 10-134 */
 export class SessionLockManager {
   /** @pseudocode concurrency-lifecycle.md lines 12-14 */
@@ -108,7 +115,7 @@ export class SessionLockManager {
       await fs.writeFile(lockPath, lockContent, { flag: 'wx' });
     } catch (writeErr: unknown) {
       if ((writeErr as NodeJS.ErrnoException).code === 'EEXIST') {
-        throw new Error('Session is in use by another process');
+        throw new SessionLockedError();
       }
       throw writeErr;
     }
@@ -121,7 +128,7 @@ export class SessionLockManager {
   ): Promise<void> {
     const isStale = await SessionLockManager.checkStale(lockPath);
     if (!isStale) {
-      throw new Error('Session is in use by another process');
+      throw new SessionLockedError();
     }
     try {
       await fs.unlink(lockPath);
@@ -135,7 +142,7 @@ export class SessionLockManager {
     } catch (writeErr: unknown) {
       const code = (writeErr as NodeJS.ErrnoException).code;
       if (code === 'EEXIST') {
-        throw new Error('Session is in use by another process');
+        throw new SessionLockedError();
       }
       if (code === 'ENOENT') {
         await SessionLockManager.createLockAfterMkdir(lockPath, lockContent);

package/src/recording/SessionRecordingService.ts

@@ -35,6 +35,8 @@ import {
   type SessionRecordLine,
 } from './types.js';
 
+export const SESSION_FILE_ID_PREFIX_LENGTH = 12;
+
 /**
  * Core service for recording session events to a JSONL file.
  *
@@ -55,6 +57,7 @@ export class SessionRecordingService {
   private readonly chatsDir: string;
   private preContentBuffer: SessionRecordLine[] = [];
   private chatsDirWatcher: FSWatcher | null = null;
+  private sessionTitle: string | null | undefined;
 
   /**
    * @plan PLAN-20260211-SESSIONRECORDING.P05
@@ -69,6 +72,7 @@ export class SessionRecordingService {
       sessionId: config.sessionId,
       projectHash: config.projectHash,
       workspaceDirs: config.workspaceDirs,
+      ...(config.cwd === undefined ? {} : { cwd: config.cwd }),
       provider: config.provider,
       model: config.model,
       startTime: new Date().toISOString(),
@@ -106,7 +110,10 @@ export class SessionRecordingService {
   enqueue(type: SessionEventType, payload: unknown): void {
     if (!this.active) return;
 
-    if (type === 'content' && !this.materialized) {
+    if (
+      (type === 'content' || type === 'session_metadata') &&
+      !this.materialized
+    ) {
       this.materialize();
       for (const buffered of this.preContentBuffer) {
         this.queue.push(buffered);
@@ -142,7 +149,7 @@ export class SessionRecordingService {
   private materialize(): void {
     const now = new Date();
     const timestamp = now.toISOString().slice(0, 19).replace(/:/g, '-');
-    const prefix = this.sessionId.substring(0, 12);
+    const prefix = this.sessionId.substring(0, SESSION_FILE_ID_PREFIX_LENGTH);
     const fileName = `session-${timestamp}-${prefix}.jsonl`;
     this.filePath = path.join(this.chatsDir, fileName);
     mkdirSync(this.chatsDir, { recursive: true });
@@ -307,11 +314,16 @@ export class SessionRecordingService {
    * @requirement REQ-REC-008
    * @pseudocode session-recording-service.md lines 174-179
    */
-  initializeForResume(filePath: string, lastSeq: number): void {
+  initializeForResume(
+    filePath: string,
+    lastSeq: number,
+    title?: string | null,
+  ): void {
     this.filePath = filePath;
     this.seq = lastSeq;
     this.materialized = true;
     this.preContentBuffer = [];
+    this.sessionTitle = title;
     this.startChatsDirWatcher();
   }
 
@@ -468,4 +480,25 @@ export class SessionRecordingService {
   recordDirectoriesChanged(directories: string[]): void {
     this.enqueue('directories_changed', { directories });
   }
+
+  /**
+   * Record a session_metadata event — persisted human-readable title.
+   * The title is tri-state: `string` for a concrete title, `null` for explicit
+   * untitled, `undefined` for legacy (field absent). Like `content`, this event
+   * materializes the file so slash/failure sessions persist metadata even
+   * without a content event.
+   *
+   * @requirement REQ-REC-002
+   */
+  recordSessionMetadata(title: string | null): void {
+    if (!this.active) {
+      return;
+    }
+    this.enqueue('session_metadata', { title });
+    this.sessionTitle = title;
+  }
+
+  getSessionMetadataTitle(): string | null | undefined {
+    return this.sessionTitle;
+  }
 }

package/src/recording/index.ts

@@ -21,9 +21,16 @@
  */
 
 export * from './types.js';
-export { SessionRecordingService } from './SessionRecordingService.js';
+export {
+  SessionRecordingService,
+  SESSION_FILE_ID_PREFIX_LENGTH,
+} from './SessionRecordingService.js';
 export { replaySession, readSessionHeader } from './ReplayEngine.js';
-export { SessionLockManager, type LockHandle } from './SessionLockManager.js';
+export {
+  SessionLockManager,
+  SessionLockedError,
+  type LockHandle,
+} from './SessionLockManager.js';
 export { RecordingIntegration } from './RecordingIntegration.js';
 export {
   type JsonlSessionFileEntry,
@@ -43,9 +50,19 @@ export {
   type ResumeResult,
   type ResumeError,
 } from './resumeSession.js';
+export {
+  RESUME_NO_SESSIONS_FOUND,
+  RESUME_SESSION_NOT_FOUND_PREFIX,
+  RESUME_SESSION_INDEX_OUT_OF_RANGE_PREFIX,
+  RESUME_SESSION_INDEX_OUT_OF_RANGE_RE,
+  resumeSessionNotFoundMessage,
+  resumeSessionIndexOutOfRangeMessage,
+} from './resumeNotFoundMessages.js';
 export {
   listSessions,
   deleteSession,
+  deleteSessionById,
+  SESSION_NOT_FOUND_PREFIX,
   type ListSessionsResult,
   type DeleteSessionResult,
   type DeleteSessionError,

package/src/recording/replay-test-helpers.ts

@@ -199,6 +199,20 @@ export function _directoriesChangedLine(
   });
 }
 
+/**
+ * Build a valid JSONL line for a session_metadata event (issue #1611).
+ * The title is either a concrete string or explicit null.
+ */
+export function sessionMetadataLine(seq: number, title: string | null): string {
+  return JSON.stringify({
+    v: 1,
+    seq,
+    ts: new Date().toISOString(),
+    type: 'session_metadata',
+    payload: { title },
+  });
+}
+
 /**
  * Write raw JSONL lines to a file.
  */

package/src/recording/resumeNotFoundMessages.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright 2025 Vybestack LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The "session not found"-style messages the resume/discovery flow emits, as
+ * shared constants so downstream classifiers (e.g. the Zed ACP loadSession
+ * error mapper) can match them WITHOUT string-literal coupling that would
+ * silently break if the wording changed. The emitting sites
+ * (resumeSession.ts, SessionDiscovery.ts) and every matcher must reference
+ * these — never inline copies of the sentences.
+ */
+
+/** Emitted by resumeSession when the project has no recorded sessions at all. */
+export const RESUME_NO_SESSIONS_FOUND = 'No sessions found for this project';
+
+/**
+ * Prefix (including the trailing colon) of the
+ * SessionDiscovery.resolveSessionRef message for an unknown session reference;
+ * the full message appends ` <ref>` (space + ref) after it — see
+ * {@link resumeSessionNotFoundMessage}.
+ */
+export const RESUME_SESSION_NOT_FOUND_PREFIX =
+  'Session not found for this project:';
+
+/**
+ * Builds the full SessionDiscovery.resolveSessionRef not-found message for a
+ * specific reference.
+ */
+export function resumeSessionNotFoundMessage(ref: string): string {
+  return `${RESUME_SESSION_NOT_FOUND_PREFIX} ${ref}`;
+}
+
+/**
+ * Prefix of the SessionDiscovery.resolveSessionRef message for a numeric
+ * session index outside the listing range; the full message is
+ * `Session index <n> out of range (1-<m>)`.
+ */
+export const RESUME_SESSION_INDEX_OUT_OF_RANGE_PREFIX = 'Session index ';
+
+/**
+ * Builds the full SessionDiscovery.resolveSessionRef out-of-range message for
+ * a specific index and session count. `ref` must render as digits (a number,
+ * or the digit-only string the caller already validated with /^\d+$/) so the
+ * produced message stays matchable by
+ * {@link RESUME_SESSION_INDEX_OUT_OF_RANGE_RE}.
+ */
+export function resumeSessionIndexOutOfRangeMessage(
+  ref: number | `${number}`,
+  count: number,
+): string {
+  if (count <= 0) {
+    return RESUME_NO_SESSIONS_FOUND;
+  }
+  return `${RESUME_SESSION_INDEX_OUT_OF_RANGE_PREFIX}${ref} out of range (1-${count})`;
+}
+
+/**
+ * Matches the out-of-range message shape for classifiers that only have the
+ * final (envelope-wrapped) detail string to inspect.
+ */
+export const RESUME_SESSION_INDEX_OUT_OF_RANGE_RE =
+  /^(?:Failed to resume session: )?Session index \d+ out of range \(1-\d+\)$/;

package/src/recording/resumeSession.ts

@@ -30,6 +30,7 @@ import { SessionRecordingService } from './SessionRecordingService.js';
 import { SessionDiscovery } from './SessionDiscovery.js';
 import { SessionLockManager, type LockHandle } from './SessionLockManager.js';
 import { replaySession } from './ReplayEngine.js';
+import { RESUME_NO_SESSIONS_FOUND } from './resumeNotFoundMessages.js';
 
 /**
  * Sentinel constant for "resume most recent session".
@@ -138,6 +139,7 @@ function initializeRecordingForResume(
   recording.initializeForResume(
     lockedSession.targetFilePath,
     replayResult.lastSeq,
+    replayResult.metadata.title,
   );
 
   if (
@@ -180,7 +182,7 @@ export async function resumeSession(
   );
 
   if (sessions.length === 0) {
-    return { ok: false, error: 'No sessions found for this project' };
+    return { ok: false, error: RESUME_NO_SESSIONS_FOUND };
   }
 
   // Step 2: Resolve which session to resume

package/src/recording/sessionManagement.ts

@@ -25,7 +25,12 @@
 
 import { type SessionSummary } from './types.js';
 import { SessionDiscovery } from './SessionDiscovery.js';
-import { SessionLockManager } from './SessionLockManager.js';
+import {
+  SessionLockManager,
+  SessionLockedError,
+  type LockHandle,
+} from './SessionLockManager.js';
+import { RESUME_NO_SESSIONS_FOUND } from './resumeNotFoundMessages.js';
 
 /**
  * Result of listing sessions for a project.
@@ -77,7 +82,7 @@ export async function deleteSession(
   const sessions = await SessionDiscovery.listSessions(chatsDir, projectHash);
 
   if (sessions.length === 0) {
-    return { ok: false, error: 'No sessions found for this project' };
+    return { ok: false, error: RESUME_NO_SESSIONS_FOUND };
   }
 
   const resolved = SessionDiscovery.resolveSessionRef(ref, sessions);
@@ -85,38 +90,63 @@ export async function deleteSession(
     return { ok: false, error: resolved.error };
   }
 
-  const target = resolved.session;
+  return deleteResolvedSession(resolved.session, chatsDir);
+}
+
+export const SESSION_NOT_FOUND_PREFIX = 'Session not found:';
+
+/** Delete a session only when the supplied identifier is an exact match. */
+export async function deleteSessionById(
+  sessionId: string,
+  chatsDir: string,
+  projectHash: string,
+): Promise<DeleteSessionResult | DeleteSessionError> {
+  const sessions = await SessionDiscovery.listSessions(chatsDir, projectHash);
+  const target = sessions.find((session) => session.sessionId === sessionId);
+  if (target === undefined) {
+    return {
+      ok: false,
+      error: `${SESSION_NOT_FOUND_PREFIX} ${sessionId}`,
+    };
+  }
+
+  return deleteResolvedSession(target, chatsDir);
+}
 
-  const locked = await SessionLockManager.isLocked(chatsDir, target.sessionId);
-  if (locked) {
-    const stale = await SessionLockManager.isStale(chatsDir, target.sessionId);
-    if (stale) {
-      await SessionLockManager.removeStaleLock(chatsDir, target.sessionId);
-    } else {
+async function deleteResolvedSession(
+  target: SessionSummary,
+  chatsDir: string,
+): Promise<DeleteSessionResult | DeleteSessionError> {
+  let lock: LockHandle;
+  try {
+    lock = await SessionLockManager.acquire(chatsDir, target.sessionId);
+  } catch (error: unknown) {
+    if (error instanceof SessionLockedError) {
       return {
         ok: false,
         error: 'Cannot delete: session is in use by another process',
       };
     }
+    const detail = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      error: `Failed to lock session for deletion: ${detail}`,
+    };
   }
 
   const { unlink } = await import('node:fs/promises');
-
+  let result: DeleteSessionResult | DeleteSessionError;
   try {
     await unlink(target.filePath);
+    result = { ok: true, deletedSessionId: target.sessionId };
   } catch (error: unknown) {
-    return {
+    const detail = error instanceof Error ? error.message : String(error);
+    result = {
       ok: false,
-      error: `Failed to delete session: ${(error as Error).message}`,
+      error: `Failed to delete session: ${detail}`,
     };
+  } finally {
+    await lock.release().catch(() => undefined);
   }
-
-  const lockPath = SessionLockManager.getLockPath(chatsDir, target.sessionId);
-  try {
-    await unlink(lockPath);
-  } catch {
-    // Lock file may not exist
-  }
-
-  return { ok: true, deletedSessionId: target.sessionId };
+  return result;
 }