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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* Adoption as an engine's contract declares it (facets/adoption.ts): its conversations on disk, the process that
* holds each, and whether a turn is running there. Moved from lib/sessionSearch/externals/{claude,codex}.ts, whose
* every answer this reproduces (engines/transcriptReads.golden.spec.ts). A provider reads the engine's own store and
* nothing else: it never writes, never starts the engine, and never logs a process's arguments (they can carry a key).
*/
import { join } from 'node:path'
import { externalEvidenceActive, externalReadFailed } from '../../lib/sessionSearch/evidence.js'
import { agentCommandOwnershipSnapshot } from '../../lib/engineBin.js'
import { absoluteFolder, entries, fileStamp, firstLine, parseLine, readHead, readJson, readTail, readText, record, text } from '../../lib/sessionSearch/externals/support.js'
import { argvTokens, engineProcessMatch, resumeSessionId } from '../../lib/processTable.js'
import {
type ExternalEngine, type ExternalOrigin, type ExternalProvider, type ExternalSession, type OwnerClaim, type Ownership, type ProcessView,
type RunningProcess, type ScanContext, UNSETTLED,
} from '../../lib/sessionSearch/externals/types.js'
import type { AdoptionContract } from '../facets/adoption.js'
type Head = AdoptionContract['head']
type Owners = AdoptionContract['owners']
type Tail = Extract<AdoptionContract['busy'], { tail: unknown }>['tail']
export interface AdoptedHead { sessionId: string; cwd: string; origin: ExternalOrigin }
/** Where a provider looks: each root its layout lists (a sessions folder, or a home), and where an engine that
* keeps process records keeps them (beside each root, unless given). Asked on every scan: a home the person moves
* is adopted while the daemon runs. */
export interface AdoptionPlaces {
roots(): string[]
records?(): string[]
}
/** The value at `path` below `row`, each step an object. */
function at(row: Record<string, unknown> | null, path: readonly string[]): unknown {
let value: unknown = row
for (const key of path) value = record(value)?.[key]
return value
}
/** Who wrote it, from the record's fields; null for anyone but a person at a terminal, an app or an editor. */
function originOf(fields: Record<string, unknown>, origin: Head['origin']): ExternalOrigin | null {
const value = fields[origin.field]
if (typeof value !== 'string' || !Object.hasOwn(origin.values, value)) return null
const rule = origin.values[value]
return typeof rule === 'string' ? rule : fields[rule.field] === rule.is ? rule.then : rule.otherwise
}
/** What a head record says: its conversation, folder and author, or null when it is not a person's. */
function judge(row: Record<string, unknown> | null, head: Head): AdoptedHead | null {
const fields = head.at ? record(at(row, head.at)) : row
if ((head.type !== undefined && row?.type !== head.type) || !fields) return null
if (head.skip && fields[head.skip.field] === head.skip.is) return null
const origin = originOf(fields, head.origin)
const cwd = absoluteFolder(fields[head.cwd])
if (!origin || !head.id.pattern.test(text(fields[head.id.field])) || !cwd) return null
return { sessionId: text(fields[head.id.field]), cwd, origin }
}
/**
* A file's conversation, folder and author, from its head. UNSETTLED while the engine is still writing the line
* that would say: a file read whole without one.
*/
export async function readAdoptedHead(path: string, head: Head): Promise<AdoptedHead | null | typeof UNSETTLED> {
if (head.line === 'first') {
let line: string | null = null
for (const bytes of head.windows) {
line = await firstLine(path, bytes)
if (line !== null) break
// The whole file was read and it has no line yet: the engine is still writing it.
if (Buffer.byteLength(await readHead(path, bytes)) < bytes) return UNSETTLED
}
return line === null ? null : judge(record(parseLine(line)), head)
}
const marker = head.line.marked
for (const bytes of head.windows) {
const read = await readHead(path, bytes)
const whole = Buffer.byteLength(read) < bytes
// A window that ends mid-file ends mid-line: that line is read whole by the next, wider one.
const lines = read.split('\n')
if (!whole) lines.pop()
for (const line of lines) {
if (!line.includes(marker)) continue
let row: Record<string, unknown> | null
try { row = record(JSON.parse(line)) } catch { continue }
if (!row) continue
return judge(row, head)
}
if (whole) return UNSETTLED
}
return null
}
/** The engine's own names for its conversations, the last one winning, read again only when the file changes. */
export async function adoptedTitles(engine: string, path: string, titles: NonNullable<AdoptionContract['titles']>, ctx: ScanContext): Promise<Map<string, string>> {
const stamp = await fileStamp(path)
if (!stamp) return new Map()
return ctx.memo(`${engine}:titles:${path}`, stamp.stamp, async () => {
const found = new Map<string, string>()
for (const line of (await readText(path)).split('\n')) {
const row = record(parseLine(line))
const name = text(row?.[titles.title]).trim()
if (text(row?.[titles.id]) && name) found.set(text(row?.[titles.id]), name)
}
return found
})
}
/** Every file a walk layout lists below `dir`, at any depth up to its limit. */
export async function walkFiles(dir: string, files: Extract<AdoptionContract['files'], { layout: 'walk' }>): Promise<string[]> {
const out: string[] = []
const walk = async (from: string, depth: number): Promise<void> => {
for (const entry of await entries(from)) {
const path = join(from, entry.name)
if (entry.isDirectory() && depth < files.depth) await walk(path, depth + 1)
// A file or a link to one; the scan's stat drops a broken link.
else if (!entry.isDirectory() && entry.name.startsWith(files.prefix) && entry.name.endsWith(files.suffix)) out.push(path)
}
}
await walk(dir, 0)
return out
}
/** Whether a process serves other clients rather than a person's terminal. */
export function servesOthers(row: RunningProcess | undefined, servers: Extract<Owners, { open: unknown }>['open']['servers']): boolean {
if (!row) return false
if (servers.executable.test(row.executable) || servers.args.test(row.args)) return true
// The subcommand: the first argument that is not an option.
const subcommand = argvTokens(row.args).slice(1).find((token) => !token.startsWith('-'))
return !!subcommand && servers.subcommands.includes(subcommand)
}
/**
* Whether a file's last turn is still running: the last turn event near its end says. What was said can name the
* events; only events count. A file that cannot say answers `unknown`.
*/
export async function turnOpen(path: string, tail: Tail, unknown: boolean | null): Promise<boolean | null> {
const mark = new RegExp(`"(${[tail.open, ...tail.closed].join('|')})"`)
for (const bytes of tail.windows) {
const lines = (await readTail(path, bytes)).split('\n')
for (let i = lines.length - 1; i > 0; i--) {
const line = lines[i]
if (!line.includes(tail.marker) || !mark.test(line)) continue
const kind = at(record(parseLine(line)), tail.at)
if (kind === tail.open) return true
if (typeof kind === 'string' && tail.closed.includes(kind)) return false
}
}
return unknown
}
/** The conversation a process's arguments say it started on: a resume of it, or one of `flags` naming it. */
function namedSession(engine: ExternalEngine, args: string, flags: readonly string[], pattern: RegExp): string | null {
const resumed = resumeSessionId(engine as never, args)
if (resumed) return resumed
const tokens = argvTokens(args)
for (const [i, token] of tokens.entries()) {
const flag = flags.find(name => token === name || token.startsWith(`${name}=`))
const value = flag && (token === flag ? tokens[i + 1] : token.slice(flag.length + 1))
if (value && pattern.test(value)) return value
}
return null
}
async function recordOwners(engine: ExternalEngine, owners: Extract<Owners, { records: unknown }>['records'], pattern: RegExp, dirs: string[], view: ProcessView): Promise<Ownership> {
const claims: OwnerClaim[] = []
for (const dir of dirs) {
const records = (await entries(dir)).filter((file) => file.isFile() && file.name.endsWith(owners.suffix))
if (!records.length) continue
const processes = new Map((await view.list()).map((process): [number, RunningProcess] => [process.pid, process]))
const ownership = agentCommandOwnershipSnapshot()
for (const file of records) {
const path = join(dir, file.name)
const row = record(await readJson(path))
const pid = row?.[owners.pid]
if (externalEvidenceActive() && (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fffffff
|| !pattern.test(text(row?.[owners.id])))) {
externalReadFailed(new Error('incomplete owner record'), 'owner record'); continue
}
if (typeof pid !== 'number' || !text(row?.[owners.id]) || !view.alive(pid)) continue
// A record outlives a crash, and its pid can be handed to anything after — a shell in another tab. Only a
// process of this engine already running when the record says it started still has it.
const process = processes.get(pid)
if (!process && externalEvidenceActive()) externalReadFailed(new Error('missing owner process'), 'owner process')
if (!process || engineProcessMatch(process, engine as never, ownership).score <= 0) continue
const started = row?.[owners.started]
if (externalEvidenceActive() && (typeof started !== 'number' || !Number.isFinite(started) || started <= 0
|| !Number.isFinite(process.started) || process.started! <= 0)) {
externalReadFailed(new Error('incomplete owner incarnation'), 'owner record'); continue
}
if (process.started !== undefined && typeof started === 'number' && process.started > started + owners.slackMs) continue
claims.push({ sessionId: text(row?.[owners.id]), pid, record: path })
}
}
const unresolved: Array<{ pid: number; named?: string }> = []
if (externalEvidenceActive()) {
const ownership = agentCommandOwnershipSnapshot()
for (const process of await view.list()) {
if (!view.alive(process.pid) || engineProcessMatch(process, engine as never, ownership).score <= 0) continue
const ids = new Set(claims.filter(claim => claim.pid === process.pid).map(claim => claim.sessionId))
if (ids.size === 1) continue
// Records that disagree about one live process are a store nobody can read: nothing is admitted on it.
if (ids.size > 1) { externalReadFailed(new Error('no unambiguous current process record'), 'current owner'); continue }
// No record. This used to fail every conversation: one long-running `claude` started before it kept
// records (two such TUIs on a developer's Mac, days old) held every adoption on the machine forever,
// "The conversation's current owner could not be verified" (CLI 0.3.70). Such a process can hold only
// the conversation its arguments name and, moved on with `/resume` or `/clear`, one its folder's picker
// lists. The first is a claim never stopped on; for the rest it stays unplaced, and admission judges it
// against each conversation's folder. A name alone is not enough: it is where it started, not where it is.
const named = namedSession(engine, process.args, owners.sessionFlags ?? [], pattern)
if (named) claims.push({ sessionId: named, pid: process.pid, record: '', fromArgs: true })
unresolved.push({ pid: process.pid, ...(named ? { named } : {}) })
}
}
const cwds = unresolved.length ? await view.cwds(unresolved.map(row => row.pid)) : new Map<number, string>()
return { claims, unresolved: unresolved.map(row => ({ ...row, cwd: cwds.get(row.pid) ?? null })) }
}
async function openFileOwners(engine: ExternalEngine, open: Extract<Owners, { open: unknown }>['open'], view: ProcessView): Promise<OwnerClaim[]> {
const claims: OwnerClaim[] = []
const held = await view.openFilesOf(open.commands)
if (!held.size) return claims
const processes = new Map((await view.list()).map((row): [number, RunningProcess] => [row.pid, row]))
const ownership = agentCommandOwnershipSnapshot()
for (const [pid, files] of held) {
const records = files.filter(path => open.id.test(path) && path.includes(open.contains))
if (!records.length) continue
// lsof -c selects command prefixes; a codex-audit helper can hold a rollout too. The exact
// process snapshot must identify the engine before an FD claim can authorize its termination.
const process = processes.get(pid)
if (externalEvidenceActive() && (!process || !view.alive(pid) || engineProcessMatch(process, engine as never, ownership).score <= 0)) {
externalReadFailed(new Error('unverified file owner process'), 'owner process'); continue
}
// A server holding a thread is never stopped from here, even when a terminal started it.
const app = servesOthers(processes.get(pid), open.servers)
for (const path of records) {
const id = open.id.exec(path)?.[1]
if (id && path.includes(open.contains)) claims.push({ sessionId: id, pid, record: path, ...(app ? { app: true } : {}) })
}
}
return claims
}
/** One engine's provider, from its contract, looking where `places` says. */
export function adoptionProvider(engine: ExternalEngine, contract: AdoptionContract, places: AdoptionPlaces): ExternalProvider {
const { files, head } = contract
const sessionAt = async (path: string, ctx: ScanContext): Promise<{ head: AdoptedHead; mtime: number } | null> => {
// A file, or a link to one; not a folder, not a broken link.
const stamp = await fileStamp(path)
if (!stamp) return null
// A head never changes: read once, however the file grows.
const found = await ctx.head(`${engine}:${path}`, stamp.stamp, () => readAdoptedHead(path, head))
await ctx.pace()
return found && !ctx.excluded(found.cwd) ? { head: found, mtime: stamp.mtime } : null
}
const owners = contract.owners
const busy = contract.busy
const ownership = async (view: ProcessView): Promise<Ownership> => 'records' in owners
? recordOwners(engine, owners.records, head.id.pattern, places.records?.() ?? places.roots().map((root) => join(root, '..', owners.records.folder)), view)
: { claims: await openFileOwners(engine, owners.open, view), unresolved: [] }
return {
engine,
async scan(ctx: ScanContext): Promise<ExternalSession[]> {
const found: ExternalSession[] = []
for (const root of places.roots()) {
if (files.layout === 'projects') {
for (const project of await entries(root)) {
if (!project.isDirectory()) continue
const folder = join(root, project.name)
// Only the project's own files: a sub-agent's are in a folder beneath it.
for (const file of await entries(folder)) {
if (!file.name.endsWith(files.suffix)) continue
const path = join(folder, file.name)
const session = await sessionAt(path, ctx)
if (session) found.push({ ...session.head, engine, title: '', mtime: session.mtime, transcriptPath: path })
}
}
continue
}
const titles = contract.titles ? await adoptedTitles(engine, join(root, contract.titles.file), contract.titles, ctx) : new Map<string, string>()
const archived = new Set(files.folders.archived ? await walkFiles(join(root, files.folders.archived), files) : [])
for (const path of [...await walkFiles(join(root, files.folders.sessions), files), ...archived]) {
const session = await sessionAt(path, ctx)
if (!session) continue
found.push({
...session.head, engine, title: titles.get(session.head.sessionId) ?? '', mtime: session.mtime, transcriptPath: path,
...(archived.has(path) ? { archived: true as const } : {}),
})
}
}
return found
},
ownership,
owners: async (view: ProcessView) => (await ownership(view)).claims,
async confirmOwner(owner, process) {
// Only its arguments name it (no record): nothing says whether it is still there or mid-turn, and it is
// never stopped on that, so its activity stays unknown.
if (!('records' in owners) || !('record' in busy) || owner.fromArgs) return null
// Claude's one record carries the session, PID, incarnation and activity together. A final
// transcript read cannot offer this guarantee when ownership lives in a separate store.
const row = record(await readJson(owner.record)), fields = owners.records
const started = row?.[fields.started]
if (!process || process.pid !== owner.pid || row?.[fields.pid] !== owner.pid || row?.[fields.id] !== owner.sessionId
|| typeof started !== 'number' || !Number.isFinite(started) || started <= 0
|| !Number.isFinite(process.started) || process.started! <= 0 || process.started! > started + fields.slackMs)
return { current: false, busy: null }
return { current: true, busy: row?.[busy.record.field] === busy.record.busy ? true : row?.[busy.record.field] === busy.record.idle ? false : null }
},
async busy(owner): Promise<boolean | null> {
if ('tail' in busy) return turnOpen(owner.record, busy.tail, null)
// A process placed by its arguments has no record to read; that absence says nothing here.
if (!owner.record) return null
const row = record(await readJson(owner.record))
// No record: the process ended with it, so it is not mid-turn.
if (!row) return false
return row[busy.record.field] === busy.record.busy ? true : row[busy.record.field] === busy.record.idle ? false : null
},
}
}