Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

5.9 KB
Raw Blame
/** Stop the exact discovered engine process while leaving the user's tmux pane and shell alive. */

import type { RegisteredSession } from './registry.js'
import { type RuntimeCheck } from './paneEngineProcess.js'
import { processRows } from './processTable.js'
import { type AgentSignal } from './processSignals.js'
import { sameProcessIdentity } from './terminalRuntime.js'

/** Delete has already removed the UI entry; signal the saved process immediately. */
export const TERMINATE_CHECK_MS = 0
/** After SIGTERM. Matches the daemon's own stop sequence rather than inventing a tighter one. */
export const FALLBACK_KILL_GRACE_MS = 3_000
const POLL_MS = 250

/**
 * Exact PID + start-marker + executable validation — the PID-reuse guard shared by delete and restart.
 * Deliberately PID-only, not pane-based (unlike paneEngineProcess.ts's `checkSessionRuntime`): by the time either
 * caller runs, the pane's UI entry may already be gone (delete) or is about to host a brand-new process
 * on purpose (restart), so nothing here should care whether a `tmux` pane still shows the expected
 * engine — only whether the exact saved process is still the one running.
 */
export async function checkPidRuntime(
  session: Pick<RegisteredSession, 'engine' | 'processIdentity'>,
): Promise<RuntimeCheck> {
  const expected = session.processIdentity
  if (!expected) return { state: 'gone', reason: 'agent has no saved process identity' }
  const rows = await processRows()
  if (!rows) return { state: 'unknown', reason: 'process table is unavailable' }
  const live = rows.find((row) => row.pid === expected.pid)
  return live && sameProcessIdentity(live, expected) && live.executable === expected.executable
    ? { state: 'alive' }
    : { state: 'gone', reason: 'saved process identity is no longer running' }
}

export type TerminateOutcome =
  /** It left before or during signalling. */
  | 'gone'
  /** SIGTERM was enough. */
  | 'terminated'
  /** It ignored SIGTERM and had to be killed. */
  | 'killed'
  /** The pane holds a DIFFERENT process now; signalling it would hit an innocent bystander. */
  | 'not-ours'
  /** We could not signal it (permissions, gone mid-flight). The engine may still be running. */
  | 'failed'

export interface TerminateDeps {
  /** Stop or a newer binding can revoke this operation while native identity is being read. */
  current?: () => boolean
  /** Three-valued exact identity check. Probe failure is not evidence that the process is gone. */
  checkRuntime: (session: RegisteredSession) => Promise<RuntimeCheck>
  /** `process.kill`. Throws on EPERM/ESRCH like the real one. */
  kill: (pid: number, signal: AgentSignal) => void
  sleep: (ms: number) => Promise<void>
  log: (message: string) => void
}

/**
 * Validate the saved PID/start marker, then stop the engine if it is still there. Never throws.
 *
 * Failures are logged loudly on purpose: by the time this runs the UI already says the agent is gone, so
 * a silently-swallowed EPERM would leave a running engine that nothing on screen accounts for.
 */
export async function terminateDeletedAgent(
  session: RegisteredSession,
  deps: TerminateDeps,
  checkAfterMs = TERMINATE_CHECK_MS,
  killGraceMs = FALLBACK_KILL_GRACE_MS,
): Promise<TerminateOutcome> {
  await deps.sleep(checkAfterMs)
  if (deps.current?.() === false) return 'not-ours'

  const check = async (): Promise<RuntimeCheck> => {
    try { return await deps.checkRuntime(session) }
    catch (err) { return { state: 'unknown', reason: err instanceof Error ? err.message : String(err) } }
  }
  // PID + start marker validation is what prevents a recycled PID from receiving our signal. Unknown
  // means we cannot prove the target and must leave the runtime suppressed rather than call it gone.
  const initial = await check()
  if (deps.current?.() === false) return 'not-ours'
  if (initial.state === 'gone') return 'gone'
  if (initial.state === 'unknown') {
    deps.log(`[delete] could not validate ${session.engine} runtime: ${initial.reason}`)
    return 'failed'
  }

  const pid = session.processIdentity?.pid
  if (!pid) return 'not-ours'

  const signal = (sig: AgentSignal): boolean => {
    if (deps.current?.() === false) return false
    try { deps.kill(pid, sig); return true } catch (err) {
      const code = (err as NodeJS.ErrnoException)?.code
      // ESRCH = it exited between the check and the signal. Anything else (EPERM…) is a real failure to
      // enforce the delete, and the person who pressed delete has already been told it worked.
      if (code !== 'ESRCH') {
        deps.log(`[delete] could not ${sig} ${session.engine} pid ${pid}: ${err instanceof Error ? err.message : String(err)}`)
      }
      return false
    }
  }

  deps.log(`[delete] ${session.engine} did not exit on request — SIGTERM pid ${pid}`)
  if (!signal('SIGTERM')) return (await check()).state === 'gone' ? 'gone' : 'failed'

  for (let waited = 0; waited < killGraceMs; waited += POLL_MS) {
    await deps.sleep(POLL_MS)
    const current = await check()
    if (deps.current?.() === false) return 'not-ours'
    if (current.state === 'gone') return 'terminated'
  }

  // Revalidate at the escalation boundary. A process-table timeout or PID replacement after SIGTERM is
  // not permission to send SIGKILL to the saved number.
  const beforeKill = await check()
  if (deps.current?.() === false) return 'not-ours'
  if (beforeKill.state === 'gone') return 'terminated'
  if (beforeKill.state === 'unknown') {
    deps.log(`[delete] could not revalidate ${session.engine} before SIGKILL: ${beforeKill.reason}`)
    return 'failed'
  }
  deps.log(`[delete] ${session.engine} ignored SIGTERM — SIGKILL pid ${pid}`)
  if (!signal('SIGKILL')) return (await check()).state === 'gone' ? 'gone' : 'failed'
  await deps.sleep(POLL_MS)
  if ((await check()).state !== 'gone') {
    deps.log(`[delete] ${session.engine} pid ${pid} is STILL running after SIGKILL`)
    return 'failed'
  }
  return 'killed'
}