fix: harden agentty session lifecycle

docs/plans/2026-03-06-agentty-reliability-implementation.md

@@ -0,0 +1,67 @@
+# Agentty Reliability Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Fix the highest-priority reliability and CLI contract issues in `agentty` without broad refactoring.
+
+**Architecture:** Tighten the session startup contract so `start` preserves argv boundaries and only reports success once the PTY is ready. Add cross-process state serialization so concurrent CLI invocations do not lose session records. Validate `attach` targets and make `kill` fail when the session has not actually exited.
+
+**Tech Stack:** TypeScript, Vitest, node-pty, execa
+
+---
+
+### Task 1: Preserve argv boundaries and delay `start` success until PTY readiness
+
+**Files:**
+- Modify: `src/index.ts`
+- Modify: `src/sessionRuntime.ts`
+- Modify: `src/worker.ts`
+- Modify: `src/ipc.ts`
+- Test: `tests/sessionRuntime.start.test.ts`
+- Test: `tests/e2e.start-argv.test.ts`
+
+**Steps:**
+1. Write a failing test that proves `start` preserves quoted and empty argv entries.
+2. Run the targeted test and confirm it fails for the expected reason.
+3. Write a failing test that proves `startSession()` returns the PTY pid rather than the worker pid.
+4. Run the targeted test and confirm it fails.
+5. Implement the minimal `file + args[]` start contract and a worker readiness handshake.
+6. Re-run the targeted tests until green.
+
+### Task 2: Prevent session state loss across concurrent CLI invocations
+
+**Files:**
+- Modify: `src/state.ts`
+- Test: `tests/e2e.concurrent-start.test.ts`
+
+**Steps:**
+1. Write a failing concurrency test that starts multiple sessions in parallel and asserts all session records remain present.
+2. Run the targeted test and confirm it fails.
+3. Add minimal cross-process state serialization around shared state mutations.
+4. Re-run the targeted test until green.
+
+### Task 3: Tighten `attach` validation and `kill` semantics
+
+**Files:**
+- Modify: `src/resolveSession.ts`
+- Modify: `src/sessionRuntime.ts`
+- Modify: `tests/attach.test.ts`
+- Modify: `tests/kill.test.ts`
+
+**Steps:**
+1. Write failing tests for attaching nonexistent or exited sessions.
+2. Run the targeted test and confirm it fails.
+3. Write a failing unit test that proves `killSession()` should reject when exit confirmation never arrives.
+4. Run the targeted test and confirm it fails.
+5. Implement minimal validation for `attach` and make `kill` timeout explicit.
+6. Re-run the targeted tests until green.
+
+### Task 4: Verify the full suite
+
+**Files:**
+- Test: `tests/*.test.ts`
+
+**Steps:**
+1. Run the full test suite in the same environment used for real `agentty` socket access.
+2. Confirm exit code `0` and zero failing tests.
+3. Review diffs for unintended changes before reporting completion.

src/index.ts

@@ -16,8 +16,10 @@ interface GetOptionResult extends SessionOptionResult {
 
 interface StartOptionResult {
   command: string;
+  args?: string[];
   cwd: string;
   name?: string;
+  displayCommand: string;
 }
 
 export interface CliIo {
@@ -125,6 +127,18 @@ function parseGetOptions(args: string[]): GetOptionResult {
   };
 }
 
+function formatCommandForDisplay(commandParts: string[]): string {
+  return commandParts
+    .map((part) => {
+      if (part.length === 0 || /[\s"'\\]/.test(part)) {
+        return JSON.stringify(part);
+      }
+
+      return part;
+    })
+    .join(' ');
+}
+
 function parseStartOptions(args: string[]): StartOptionResult {
   let cwd = process.cwd();
   let name: string | undefined;
@@ -177,9 +191,11 @@ function parseStartOptions(args: string[]): StartOptionResult {
   }
 
   return {
-    command: commandParts.join(' '),
+    command: commandParts[0],
+    args: commandParts.length > 1 ? commandParts.slice(1) : undefined,
     cwd,
     name,
+    displayCommand: formatCommandForDisplay(commandParts),
   };
 }
 
@@ -262,8 +278,8 @@ export async function runCli(argv: string[] = process.argv.slice(2), io: CliIo =
   }
 
   if (command === 'start') {
-    const { command: startCommand, cwd, name } = parseStartOptions(argv.slice(1));
-    const session = await startSession({ command: startCommand, cwd, name });
+    const { command: startCommand, args, cwd, name, displayCommand } = parseStartOptions(argv.slice(1));
+    const session = await startSession({ command: startCommand, args, cwd, name, displayCommand });
 
     io.stdout(session.id);
     return;

src/resolveSession.ts

@@ -1,6 +1,15 @@
-import { readActiveSessionId, writeActiveSessionId } from './state';
+import { readActiveSessionId, readSessionById, writeActiveSessionId } from './state';
+
+async function ensureRunningSession(sessionId: string): Promise<void> {
+  const session = await readSessionById(sessionId);
+
+  if (!session || session.status !== 'running') {
+    throw new Error(`session is not running: ${sessionId}`);
+  }
+}
 
 export async function attachSession(id: string): Promise<void> {
+  await ensureRunningSession(id);
   await writeActiveSessionId(id);
 }
 

src/sessionRuntime.ts

@@ -15,8 +15,10 @@ import {
 
 export interface StartSessionInput {
   command: string;
+  args?: string[];
   cwd: string;
   name?: string;
+  displayCommand?: string;
 }
 
 export interface SessionMetadata {
@@ -37,8 +39,8 @@ const WORKER_ENTRY_PATH = path.resolve(__dirname, '../dist/worker.js');
 const LOGS_DIR = 'logs';
 const KILL_WAIT_TIMEOUT_MS = 3_000;
 const KILL_WAIT_INTERVAL_MS = 50;
-const SOCKET_READY_TIMEOUT_MS = 1_000;
-const SOCKET_READY_POLL_INTERVAL_MS = 50;
+const START_READY_TIMEOUT_MS = 10_000;
+const START_READY_POLL_INTERVAL_MS = 50;
 
 function isUnavailableIpcError(error: unknown): boolean {
   const code = (error as NodeJS.ErrnoException)?.code;
@@ -85,26 +87,28 @@ async function markSessionExited(sessionId: string, exitCode: number | null): Pr
   }
 }
 
-async function waitForExited(sessionId: string): Promise<void> {
+async function waitForExited(sessionId: string): Promise<boolean> {
   const deadline = Date.now() + KILL_WAIT_TIMEOUT_MS;
 
   while (Date.now() < deadline) {
     const session = await readSessionById(sessionId);
 
     if (!session || session.status === 'exited') {
-      return;
+      return true;
     }
 
     await new Promise((resolve) => setTimeout(resolve, KILL_WAIT_INTERVAL_MS));
   }
+
+  return false;
 }
 
 function getWorkerLogPath(sessionId: string): string {
   return path.join(getStateRoot(), LOGS_DIR, `${sessionId}.log`);
 }
 
 async function waitForSocketReady(socketPath: string, didWorkerExit: () => boolean): Promise<boolean> {
-  const deadline = Date.now() + SOCKET_READY_TIMEOUT_MS;
+  const deadline = Date.now() + START_READY_TIMEOUT_MS;
 
   while (Date.now() < deadline) {
     try {
@@ -118,7 +122,7 @@ async function waitForSocketReady(socketPath: string, didWorkerExit: () => boole
       break;
     }
 
-    await new Promise((resolve) => setTimeout(resolve, SOCKET_READY_POLL_INTERVAL_MS));
+    await new Promise((resolve) => setTimeout(resolve, START_READY_POLL_INTERVAL_MS));
   }
 
   try {
@@ -129,7 +133,37 @@ async function waitForSocketReady(socketPath: string, didWorkerExit: () => boole
   }
 }
 
-export async function startSession({ command, cwd, name }: StartSessionInput): Promise<SessionMetadata> {
+async function waitForSessionReady(
+  sessionId: string,
+  workerPid: number,
+  didWorkerExit: () => boolean,
+): Promise<SessionMetadata | null> {
+  const deadline = Date.now() + START_READY_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    const session = await readSessionById(sessionId);
+
+    if (
+      session &&
+      session.status === 'running' &&
+      typeof session.pid === 'number' &&
+      typeof session.workerPid === 'number' &&
+      session.pid !== workerPid
+    ) {
+      return session as SessionMetadata;
+    }
+
+    if (didWorkerExit()) {
+      break;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, START_READY_POLL_INTERVAL_MS));
+  }
+
+  return null;
+}
+
+export async function startSession({ command, args, cwd, name, displayCommand }: StartSessionInput): Promise<SessionMetadata> {
   const trimmedCommand = command.trim();
 
   if (!trimmedCommand) {
@@ -149,9 +183,11 @@ export async function startSession({ command, cwd, name }: StartSessionInput): P
   const workerSpec = {
     id: sessionId,
     command: trimmedCommand,
+    ...(args ? { args } : {}),
     cwd,
     socketPath,
     startedAt: now,
+    ...(displayCommand ? { displayCommand } : {}),
     ...(name ? { name } : {}),
   };
 
@@ -195,7 +231,7 @@ export async function startSession({ command, cwd, name }: StartSessionInput): P
     id: sessionId,
     pid: child.pid,
     workerPid: child.pid,
-    command: trimmedCommand,
+    command: displayCommand ?? trimmedCommand,
     cwd,
     startedAt: now,
     lastActiveAt: now,
@@ -229,13 +265,29 @@ export async function startSession({ command, cwd, name }: StartSessionInput): P
     await markSessionExited(sessionId, workerExitCode);
 
     throw new Error(
-      `session worker failed to start (socket was not created within ${SOCKET_READY_TIMEOUT_MS}ms): ${socketPath}. Check worker log: ${logFilePath}`,
+      `session worker failed to start (socket was not created within ${START_READY_TIMEOUT_MS}ms): ${socketPath}. Check worker log: ${logFilePath}`,
+    );
+  }
+
+  const readySession = await waitForSessionReady(sessionId, child.pid, () => workerExited);
+
+  if (!readySession) {
+    try {
+      process.kill(child.pid, 'SIGTERM');
+    } catch {
+      // ignore cleanup errors
+    }
+
+    await markSessionExited(sessionId, workerExitCode);
+
+    throw new Error(
+      `session worker failed to become ready within ${START_READY_TIMEOUT_MS}ms: ${socketPath}. Check worker log: ${logFilePath}`,
     );
   }
 
   child.unref();
 
-  return session;
+  return readySession;
 }
 
 export async function sendText(sessionId: string, payload: string): Promise<void> {
@@ -301,7 +353,11 @@ export async function killSession(sessionId: string): Promise<void> {
     await requestIpc(session.socketPath, {
       method: 'kill',
     });
-    await waitForExited(sessionId);
+    const exited = await waitForExited(sessionId);
+
+    if (!exited) {
+      throw new Error(`session did not exit within ${KILL_WAIT_TIMEOUT_MS}ms: ${sessionId}`);
+    }
   } catch (error) {
     if (isUnavailableIpcError(error)) {
       await markSessionExited(sessionId, null);