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
/**
* Forgetting a session: release a mutable session binding (the agent stays, its session goes), or
* remove a process-owned agent everywhere — archived as stopped, and every per-session store the core
* keeps let go of, so a daemon that runs for days does not grow with every session it ever saw.
*
* Moved verbatim out of `runForeground` (the core boundary, step 10: docs/design/2026-10-03-harnessd.md).
*/
import { removePendingCursorTasks } from '../engines/cursorTasks.js'
import type { CursorTranscriptDiscovery } from '../../engines/cursor/discovery.js'
import type { CursorSubagentManager } from '../../engines/cursor/subagent.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import type { TurnRecaps } from '../turns/recaps.js'
import type { ShortTurnGuard } from '../turns/shortTurnGuard.js'
import { sid } from '../../lib/log.js'
import { sameProcessIdentity } from '../../lib/terminalRuntime.js'
import type { RegisteredSession, registry } from '../../lib/registry.js'
import type { RuntimeProfileManager } from '../../lib/runtimeProfile.js'
import type { SessionInputController } from '../../lib/sessionInput.js'
import type { StoppedAgentStore } from '../../lib/stoppedAgents.js'
import type { Watcher } from '../../watcher/watcher.js'
import type { SessionNormalizers } from '../transcripts/normalizers.js'
import type { RelaunchMarks } from '../transcripts/relaunch.js'
import type { ConversationOwners } from './conversationOwners.js'
type Frame = { type: string; payload: Record<string, unknown> }
export interface ForgetDeps {
onRemoved?: (agentId: string) => void
/** One owner per conversation, stopped harnesses included (conversationOwners.ts). */
owners?: Pick<ConversationOwners, 'settleSaved'>
registry: Pick<typeof registry, 'resolve' | 'unbindSession' | 'removeAgent' | 'remove'>
stoppedAgents: Pick<StoppedAgentStore, 'save'>
syncRecapPool: () => void
normalizers: Pick<SessionNormalizers, 'forget'>
forgetAttach: (sessionId: string) => void
turnStartedAt: Map<string, number>
/** The short-turn guard's count and hold for each session (turns/shortTurnGuard.ts): gone with the session. */
shortTurns?: Pick<ShortTurnGuard, 'forget'>
/** Each agent's kept prompt (turns/funnel.ts), by agent: gone with the agent. */
prompts: Map<string, string>
/** Attach's two per-session marks (core/transcripts/attach.ts). */
neverFoldedHistory: Set<string>
replayedFirstTurn: Set<string>
relaunchMarks?: Pick<RelaunchMarks, 'forget'>
clearAgyIdleWatch: (sessionId: string) => void
cursorDiscovery: Pick<CursorTranscriptDiscovery, 'remove'>
cursorSubagents: Pick<CursorSubagentManager, 'forget'>
runtimeProfiles: Pick<RuntimeProfileManager, 'forget'>
watcher: Pick<Watcher, 'removeSession'>
stopHeartbeat: (sessionId: string) => void
input: Pick<SessionInputController, 'forget'>
deviceInput: Pick<AutonomousDeviceInput, 'forget'>
detachDsh: (agentId: string) => void
mirror: Pick<TurnRecaps, 'forget'>
/** The app (`send`) and the dial (`sendCommander`). */
clients: { send(frame: Frame): void; sendCommander(frame: Frame): void }
dataDir: string
}
export function createForgetSession({
registry, stoppedAgents, syncRecapPool, normalizers, forgetAttach, turnStartedAt, prompts, neverFoldedHistory, replayedFirstTurn, relaunchMarks,
clearAgyIdleWatch, cursorDiscovery, cursorSubagents, runtimeProfiles, watcher, stopHeartbeat, input,
deviceInput, detachDsh, mirror, clients, dataDir, onRemoved, owners, shortTurns,
}: ForgetDeps) {
/** Release a mutable session binding, or remove the process-owned agent everywhere. */
const forgetSession = (
id: string,
opts: { force?: boolean; keepAgent?: boolean; agentId?: string; captured?: RegisteredSession } = {},
): void => {
const doomed = registry.resolve(id)
const sessionId = doomed?.sessionId || id
// Clients key on the AGENT id. Normally it is read off the entry, but an
// agent already removed from the registry cannot be looked up — and
// announcing its sessionId instead is silently useless: the app takes
// payload.agentId verbatim, matches nothing, and leaves the dead row on
// screen. Callers who know the id pass it.
const announceId = doomed?.agentId ?? opts.agentId ?? sessionId
console.log(opts.keepAgent
? `[agent] ${sid(announceId)} released session ${sid(sessionId)}`
: `[agent] ${sid(announceId)} forgotten`)
if (!opts.keepAgent && doomed) {
const captured = opts.captured
if (captured && (captured.agentId !== doomed.agentId || captured.engine !== doomed.engine
|| captured.registeredAt !== doomed.registeredAt || doomed.sessionId && captured.sessionId !== doomed.sessionId
|| captured.processIdentity && (!sameProcessIdentity(captured.processIdentity, doomed.processIdentity)
|| captured.processIdentity.executable !== doomed.processIdentity?.executable))) {
throw new Error('The harness changed before its captured conversation could be retained.')
}
// Stop may prove a parent path while the live row still names an overwritten child.
// Preserve that capture through this last archive, including intervening hook saves.
stoppedAgents.save(captured ? { ...doomed, sessionId: captured.sessionId, transcriptPath: captured.transcriptPath,
hermesHome: captured.hermesHome, boundAt: captured.boundAt, source: captured.source } : doomed)
}
if (opts.keepAgent) registry.unbindSession(sessionId)
else if (doomed) registry.removeAgent(doomed.agentId)
else registry.remove(sessionId)
// No longer running, its last record may still hold a conversation another harness took meanwhile: the
// save keeps a known one through an unbound row (StoppedAgentStore.save). One owner each from here on.
if (!opts.keepAgent && doomed) {
try { owners?.settleSaved(doomed.agentId) }
catch (error) { console.warn(`[agent] ${sid(doomed.agentId)} could not settle who owns its conversation: ${error instanceof Error ? error.message : error}`) }
}
syncRecapPool()
normalizers.forget(sessionId)
forgetAttach(sessionId)
turnStartedAt.delete(sessionId)
shortTurns?.forget(sessionId)
neverFoldedHistory.delete(sessionId)
// Both sets are per-session and must die with it: left behind they grow without bound in a daemon
// that runs for days, and a session forgotten then re-registered under the same id would inherit a
// stale "already replayed" and lose a first turn it was entitled to.
replayedFirstTurn.delete(sessionId)
relaunchMarks?.forget(sessionId)
clearAgyIdleWatch(sessionId)
cursorDiscovery.remove(sessionId)
cursorSubagents.forget(sessionId)
void removePendingCursorTasks(dataDir, sessionId)
runtimeProfiles.forget(sessionId)
void watcher.removeSession(sessionId)
stopHeartbeat(sessionId)
input.forget(announceId)
deviceInput.forget(announceId)
if (!opts.keepAgent) { detachDsh(announceId); onRemoved?.(announceId); prompts.delete(announceId) }
mirror.forget(sessionId) // aborts any in-flight recap + clears busy; KEEPS the persisted summary
if (opts.keepAgent) return
clients.send({ type: 'agent_deleted', payload: { agentId: announceId, retained: !!doomed } }) // web tab
clients.sendCommander({ type: 'agent_deleted', payload: { agentId: announceId } })
}
return forgetSession
}