throughline 0.6.2 → 0.7.0

package/src/cli/observer-wait.mjs

@@ -0,0 +1,123 @@
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import {
+  OBSERVER_WAIT_SCHEMA,
+  DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS,
+  waitForObserverTurnChange,
+} from '../observer-turn-wait.mjs';
+
+const ERRORS = Object.freeze({
+  args: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_ARGS', message: 'invalid observer-wait arguments' },
+  input: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_INPUT', message: 'observer wait input is invalid' },
+  cancelled: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_CANCELLED', message: 'observer wait was cancelled' },
+  internal: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_INTERNAL', message: 'observer wait failed' },
+});
+const PARENT_WATCH_INTERVAL_MS = 1000;
+
+export function parseArgs(argv = []) {
+  const out = { projectPath: null, afterCursor: null, timeoutSeconds: DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS, json: false };
+  const seen = new Set();
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--json') {
+      if (seen.has(arg)) throw new TypeError('duplicate option');
+      seen.add(arg); out.json = true; continue;
+    }
+    if (!['--project', '--after-cursor', '--timeout-seconds'].includes(arg) || seen.has(arg)) {
+      throw new TypeError('invalid option');
+    }
+    const value = argv[++index];
+    if (!value || value.startsWith('-')) throw new TypeError('missing option value');
+    seen.add(arg);
+    if (arg === '--project') out.projectPath = value;
+    else if (arg === '--after-cursor') out.afterCursor = value;
+    else out.timeoutSeconds = parseTimeout(value);
+  }
+  if (!out.json || !out.projectPath || !out.afterCursor) throw new TypeError('missing required option');
+  return out;
+}
+
+export async function run(argv = [], {
+  wait = waitForObserverTurnChange,
+  validateProject = assertProjectDirectory,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  processRef = process,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  parentWatchIntervalMs = PARENT_WATCH_INTERVAL_MS,
+} = {}) {
+  let args;
+  try { args = parseArgs(argv); } catch { writeJson(stderr, ERRORS.args); return 1; }
+
+  try { validateProject(args.projectPath); } catch { writeJson(stderr, ERRORS.input); return 1; }
+
+  const controller = new AbortController();
+  const cleanup = installCancellation({ controller, processRef, setIntervalFn, clearIntervalFn, parentWatchIntervalMs });
+  try {
+    const result = await wait({
+      projectPath: args.projectPath,
+      afterCursor: args.afterCursor,
+      timeoutSeconds: args.timeoutSeconds,
+      signal: controller.signal,
+    });
+    writeJson(stdout, result);
+    return 0;
+  } catch (error) {
+    writeJson(stderr, mapError(error));
+    return 1;
+  } finally {
+    cleanup();
+  }
+}
+
+function parseTimeout(value) {
+  if (!/^\d+$/.test(value)) throw new TypeError('invalid timeout');
+  const timeout = Number(value);
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600) throw new TypeError('invalid timeout');
+  return timeout;
+}
+
+function assertProjectDirectory(projectPath) {
+  if (!isAbsolute(projectPath) || !statSync(projectPath).isDirectory()) {
+    throw new TypeError('project must be an absolute existing directory');
+  }
+}
+
+function installCancellation({ controller, processRef, setIntervalFn, clearIntervalFn, parentWatchIntervalMs }) {
+  const abort = () => controller.abort();
+  const parentPid = processRef.ppid;
+  processRef.on('SIGINT', abort);
+  processRef.on('SIGTERM', abort);
+  processRef.on('disconnect', abort);
+
+  let parentTimer = null;
+  if (Number.isSafeInteger(parentPid) && parentPid > 1) {
+    const checkParent = () => {
+      if (processRef.ppid !== parentPid) return abort();
+      try {
+        processRef.kill(parentPid, 0);
+      } catch (error) {
+        if (error?.code === 'ESRCH') abort();
+      }
+    };
+    parentTimer = setIntervalFn(checkParent, parentWatchIntervalMs);
+    parentTimer?.unref?.();
+  }
+
+  return () => {
+    processRef.removeListener('SIGINT', abort);
+    processRef.removeListener('SIGTERM', abort);
+    processRef.removeListener('disconnect', abort);
+    if (parentTimer !== null) clearIntervalFn(parentTimer);
+  };
+}
+
+function mapError(error) {
+  if (error?.code === 'E_OBSERVER_WAIT_CANCELLED') return ERRORS.cancelled;
+  return ERRORS.internal;
+}
+
+function writeJson(stream, value) { stream.write(`${JSON.stringify(value)}\n`); }
+
+export const _internal = { assertProjectDirectory, installCancellation, PARENT_WATCH_INTERVAL_MS };

package/src/cli/observer-wait.test.mjs

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { EventEmitter, getEventListeners } from 'node:events';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import test from 'node:test';
+import { OBSERVER_WAIT_SCHEMA } from '../observer-turn-wait.mjs';
+import { parseArgs, run } from './observer-wait.mjs';
+
+const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const AFTER = 'tlc1.after';
+
+function streams() {
+  return { stdout: { text: '', write(value) { this.text += value; } }, stderr: { text: '', write(value) { this.text += value; } } };
+}
+
+function fakeProcess({ ppid = 42, kill = () => {} } = {}) {
+  const result = new EventEmitter();
+  result.ppid = ppid;
+  result.kill = kill;
+  return result;
+}
+
+test('observer-wait strictly parses its public arguments', async () => {
+  assert.deepEqual(parseArgs(['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '1', '--json']), {
+    projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1, json: true,
+  });
+  assert.equal(parseArgs(['--project', '/repo', '--after-cursor', AFTER, '--json']).timeoutSeconds, 3600);
+  for (const argv of [
+    ['--project', '/repo', '--project', '/repo', '--after-cursor', AFTER, '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--json', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '0', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '3601', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, 'extra', '--json'],
+    ['--project', '/repo', '--json'],
+  ]) {
+    const io = streams();
+    assert.equal(await run(argv, { ...io }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.deepEqual(JSON.parse(io.stderr.text), { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_ARGS', message: 'invalid observer-wait arguments' });
+  }
+});
+
+test('observer-wait returns each known core status as successful JSON', async () => {
+  for (const [status, throughCursor] of [['changed', 'tlc1.changed'], ['timeout', AFTER], ['resync_required', null], ['ambiguous_parent', null]]) {
+    const io = streams();
+    assert.equal(await run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io,
+      validateProject: () => {},
+      processRef: fakeProcess(),
+      setIntervalFn: () => ({ unref() {} }), clearIntervalFn: () => {},
+      wait: async () => ({ schema: OBSERVER_WAIT_SCHEMA, status, afterCursor: AFTER, throughCursor }),
+    }), 0);
+    assert.deepEqual(JSON.parse(io.stdout.text), { schema: OBSERVER_WAIT_SCHEMA, status, afterCursor: AFTER, throughCursor });
+    assert.equal(io.stderr.text, '');
+  }
+});
+
+test('observer-wait maps project, cancel, and internal failures to fixed errors without leakage', async () => {
+  for (const [dependencies, code] of [
+    [{ validateProject: () => { throw new Error('/private/project'); } }, 'E_OBSERVER_WAIT_INPUT'],
+    [{ wait: async () => { throw Object.assign(new Error('secret cursor'), { code: 'E_OBSERVER_WAIT_CANCELLED' }); } }, 'E_OBSERVER_WAIT_CANCELLED'],
+    [{ wait: async () => { throw new Error('secret /private/cursor'); } }, 'E_OBSERVER_WAIT_INTERNAL'],
+  ]) {
+    const io = streams();
+    assert.equal(await run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef: fakeProcess(),
+      setIntervalFn: () => ({ unref() {} }), clearIntervalFn: () => {}, ...dependencies,
+    }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.equal(JSON.parse(io.stderr.text).code, code);
+    assert.doesNotMatch(io.stderr.text, /private|secret|cursor/i);
+  }
+});
+
+test('observer-wait cancels on signals and removes listeners and parent watcher', async () => {
+  for (const event of ['SIGINT', 'SIGTERM', 'disconnect']) {
+    const io = streams();
+    const processRef = fakeProcess();
+    let checkParent;
+    let cleared = 0;
+    const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef,
+      setIntervalFn(callback) { checkParent = callback; return { unref() {} }; },
+      clearIntervalFn() { cleared++; },
+      wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(getEventListeners(processRef, 'SIGINT').length, 1);
+    assert.equal(getEventListeners(processRef, 'SIGTERM').length, 1);
+    assert.equal(getEventListeners(processRef, 'disconnect').length, 1);
+    assert.equal(typeof checkParent, 'function');
+    processRef.emit(event);
+    assert.equal(await pending, 1);
+    assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+    assert.equal(cleared, 1);
+    assert.equal(getEventListeners(processRef, 'SIGINT').length, 0);
+    assert.equal(getEventListeners(processRef, 'SIGTERM').length, 0);
+    assert.equal(getEventListeners(processRef, 'disconnect').length, 0);
+  }
+});
+
+test('observer-wait treats changed parent or ESRCH as cancellation but not EPERM', async () => {
+  for (const [mode, kill] of [
+    ['ppid', () => {}],
+    ['esrch', () => { throw Object.assign(new Error('gone'), { code: 'ESRCH' }); }],
+  ]) {
+    const io = streams();
+    const processRef = fakeProcess({ kill });
+    let checkParent;
+    const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef,
+      setIntervalFn(callback) { checkParent = callback; return { unref() {} }; }, clearIntervalFn: () => {},
+      wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    if (mode === 'ppid') processRef.ppid = 1;
+    checkParent();
+    assert.equal(await pending, 1);
+    assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+  }
+
+  const io = streams();
+  const processRef = fakeProcess({ kill: () => { throw Object.assign(new Error('denied'), { code: 'EPERM' }); } });
+  let checkParent;
+  const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+    ...io, validateProject: () => {}, processRef,
+    setIntervalFn(callback) { checkParent = callback; return { unref() {} }; }, clearIntervalFn: () => {},
+    wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+  checkParent();
+  assert.equal(io.stderr.text, '');
+  processRef.emit('disconnect');
+  assert.equal(await pending, 1);
+  assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+});
+
+test('observer-wait bin dispatch and help use the JSON-only contract', async () => {
+  const help = spawnSync(process.execPath, [BIN_PATH, '--help'], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(help.status, 0, help.stderr);
+  assert.match(help.stdout, /throughline observer-wait --project <absolute-directory> --after-cursor <opaque> --json/);
+
+  const root = await mkdtemp(join(tmpdir(), 'throughline-observer-wait-'));
+  const home = join(root, 'home');
+  const state = join(root, 'state');
+  const codexHome = join(root, 'codex');
+  const project = join(root, 'project');
+  try {
+    await Promise.all([mkdir(home), mkdir(state), mkdir(codexHome), mkdir(project)]);
+    const result = spawnSync(process.execPath, [BIN_PATH, 'observer-wait', '--project', project, '--after-cursor', 'invalid', '--json'], {
+      cwd: REPO_ROOT, encoding: 'utf8', timeout: 5000,
+      env: { ...process.env, HOME: home, USERPROFILE: home, XDG_STATE_HOME: state, CODEX_HOME: codexHome },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr, '');
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.schema, OBSERVER_WAIT_SCHEMA);
+    assert.equal(output.status, 'resync_required');
+    assert.equal(output.throughCursor, null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/codex-rollout-memory.mjs

@@ -135,6 +135,7 @@ export function parseCodexRolloutFile(
               number: `rollout-${stats.parsedRows}`,
               messages: [],
               details: [],
+              completedAt: null,
             };
             activeTurns.push(postRollbackTurn);
           }
@@ -162,6 +163,7 @@ export function parseCodexRolloutFile(
         number: stats.taskStarted + 1,
         messages: pendingSplit.currentMessages,
         details: pendingSplit.currentDetails,
+        completedAt: null,
       };
       pendingMessages = [];
       pendingDetails = [];
@@ -175,6 +177,7 @@ export function parseCodexRolloutFile(
 
     if (payload.type === 'task_complete') {
       stats.taskComplete++;
+      if (openTurn) openTurn.completedAt = parseHostTimestamp(row.timestamp);
       openTurn = null;
       continue;
     }
@@ -230,6 +233,7 @@ export function parseCodexRolloutFile(
           number: `rollout-${stats.parsedRows}`,
           messages: [],
           details: [],
+          completedAt: null,
         };
         activeTurns.push(postRollbackTurn);
       }
@@ -262,6 +266,7 @@ export function parseCodexRolloutFile(
       number: `rollout-${stats.parsedRows}`,
       messages: pendingMessages,
       details: pendingDetails,
+      completedAt: null,
     });
   }
 
@@ -410,6 +415,7 @@ function splitPendingMessagesForTaskStart({ messages, details, syntheticNumber }
         number: syntheticNumber,
         messages,
         details,
+        completedAt: null,
       },
       currentMessages: [],
       currentDetails: [],
@@ -443,12 +449,19 @@ function splitPendingMessagesForTaskStart({ messages, details, syntheticNumber }
       number: syntheticNumber,
       messages: syntheticMessages,
       details: syntheticDetails,
+      completedAt: null,
     },
     currentMessages,
     currentDetails,
   };
 }
 
+function parseHostTimestamp(value) {
+  if (typeof value !== 'string') return null;
+  const timestamp = Date.parse(value);
+  return Number.isSafeInteger(timestamp) && timestamp >= 0 ? timestamp : null;
+}
+
 function removeRolledBackTurns(activeTurns, count) {
   return activeTurns.splice(Math.max(0, activeTurns.length - count), count);
 }

package/src/codex-rollout-memory.test.mjs

@@ -216,6 +216,33 @@ test('parseCodexRolloutFile: keeps final pending messages as current synthetic t
   }
 });
 
+test('parseCodexRolloutFile: completedAtは自身のtask_completeを観測した通常turnだけに付く', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-codex-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));
+  try {
+    const rollout = writeRollout(home, {
+      id: '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9', cwd: project,
+      events: [
+        event('user_message', { message: 'completed request' }),
+        event('task_started'),
+        event('agent_message', { message: 'completed answer' }),
+        { timestamp: '2026-05-06T00:41:00.000Z', type: 'event_msg', payload: { type: 'task_complete' } },
+        event('agent_message', { message: 'synthetic continuation' }),
+        event('user_message', { message: 'open request' }),
+        event('task_started'),
+        event('agent_message', { message: 'open answer' }),
+      ],
+    });
+    const parsed = parseCodexRolloutFile(rollout);
+    assert.equal(parsed.activeTurns[0].completedAt, Date.parse('2026-05-06T00:41:00.000Z'));
+    assert.equal(parsed.activeTurns[1].completedAt, null);
+    assert.equal(parsed.activeTurns[2].completedAt, null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('parseCodexRolloutFile: trim source can exclude the current in-flight turn', () => {
   const home = mkdtempSync(join(tmpdir(), 'tl-codex-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));

package/src/codex-thread-index.mjs

@@ -185,7 +185,7 @@ function normalizePath(value) {
   } catch {
     // Keep the lexical path when it cannot be resolved.
   }
-  return resolved.split(sep).join('/').replace(/\/+$/, '').toLowerCase();
+  return resolved.split(sep).join('/').replace(/\/+$/, '');
 }
 
 function isSameProjectOrDescendant(candidate, root) {

package/src/codex-thread-index.test.mjs

@@ -67,6 +67,24 @@ test('listCodexThreadCandidates: filters rollouts to current project and merges
   }
 });
 
+test('listCodexThreadCandidates: POSIX project path matching preserves case', {
+  skip: process.platform === 'win32' ? 'Windows paths are case-insensitive' : undefined,
+}, () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-codex-home-'));
+  const root = mkdtempSync(join(tmpdir(), 'tl-codex-case-'));
+  const project = join(root, 'Project');
+  const other = join(root, 'project');
+  try {
+    writeRollout(home, { day: '06', started: '2026-05-06T09-40-50', id: '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9', cwd: project });
+    writeRollout(home, { day: '06', started: '2026-05-06T09-41-50', id: '019dfabb-1111-7111-8111-111111111111', cwd: other });
+    const candidates = listCodexThreadCandidates({ codexHome: home, projectPath: project });
+    assert.deepEqual(candidates.map((entry) => entry.cwd), [project]);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('listCodexThreadCandidates: sorts by rollout mtime rather than stale index updated_at', () => {
   const home = mkdtempSync(join(tmpdir(), 'tl-codex-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));