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.

10.9 KB
Raw Blame
/** A shared contribution belongs to its Super Tab even while no terminal is shown.
 * Keep the last confirmed roster across host/network restarts; only a successful
 * roster read may release it to automatic cleanup. This grants no input access.
 *
 * Membership only in archived groups is not in use, and a roster nobody confirms
 * for a week (signed out, unlinked machine) lapses, except a project's Lead, which
 * is never stopped. A paused tab still counts: pause blocks new work, while
 * discussion and running assignments continue. */
import { existsSync, mkdirSync, readFileSync, renameSync, statSync, utimesSync, writeFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { leadSwitchOf, SWITCH_RECOVERY_MS, switchWithin } from './leadSwitch.js'
import { isCrewRow } from './crew.js'
import { identifier, object } from './wire.js'
import { isTeamDaemon } from './teamDaemon.js'

/** `leads`: the Leads of active projects here, which never lapse (owner, 2026-10-23: the Lead of an active project is never
 *  stopped in any case). Absent in a file from before Leads were kept.
 *  `buddies`: the Buddies here, which a close never stops (Diego, 10-30): only their person removing them, or the machine's
 *  owner with Stop Harness. Absent in a file from before Buddies were kept, which names none until the next roster.
 *  `assigned`: when the host first received each assignment its harnesses hold, epoch ms. Such a harness is in `harnesses`
 *  while it holds it and for ASSIGNED_GRACE_MS after it came, whatever its groups (task #2744). Absent in older files.
 *  `crew`: its project's crew here (crew.ts isCrewRow, task #3397), kept as Leads are: in no open group and past the lapse,
 *  and reopened by the core when gone. Absent in older files.
 *  `wakeableBuddies`: only main Buddies the server manages for sleep (#3824); ordinary Buddies gain no resume authority.
 *  `sleepingBuddies`: the subset its latest roster puts to sleep, revoking the internal close permit when awake. */
interface Retention { version: 2; machineId: string; harnesses: string[]; leads?: string[]; crew?: string[]; buddies?: string[]; wakeableBuddies?: string[]; sleepingBuddies?: string[]; assigned?: Record<string, number> }
export const retentionFile = (dataDir: string) => join(dataDir, 'super-tabs', 'retained.json')
export const RETENTION_LAPSE_MS = 7 * 24 * 60 * 60_000
const REFRESH_MS = 60 * 60_000
/** How long a harness stays kept after the host first received an assignment for it: an assignment that ends at once (the
 *  PM moves it, the agent answers in a second) never leaves the harness to a cleanup that was about to close it. */
export const ASSIGNED_GRACE_MS = 60_000

function read(file: string): Retention {
  if (statSync(file).size > 4 * 1024 * 1024) throw new Error('Super Tab retention is too large. Automatic cleanup is paused.')
  let value: Record<string, unknown> = {}
  try { value = object(JSON.parse(readFileSync(file, 'utf8'))) } catch { /* reported below */ }
  if (value.version !== 2 || !identifier(value.machineId) || !Array.isArray(value.harnesses) || !value.harnesses.every(identifier)
    || (value.leads !== undefined && (!Array.isArray(value.leads) || !value.leads.every(identifier)))
    || (value.crew !== undefined && (!Array.isArray(value.crew) || !value.crew.every(identifier)))
    || (value.wakeableBuddies !== undefined && (!Array.isArray(value.wakeableBuddies) || !value.wakeableBuddies.every(identifier)))
    || (value.sleepingBuddies !== undefined && (!Array.isArray(value.sleepingBuddies) || !value.sleepingBuddies.every(identifier)))
    || (value.buddies !== undefined && (!Array.isArray(value.buddies) || !value.buddies.every(identifier)))
    || (value.assigned !== undefined && !Object.entries(object(value.assigned)).every(([id, at]) => identifier(id) && Number.isFinite(at)))) {
    throw new Error('Super Tab retention is unreadable. Automatic cleanup is paused.')
  }
  return value as unknown as Retention
}

export function retainedHarnesses(dataDir: string, now = Date.now()): Set<string> {
  const file = retentionFile(dataDir)
  // An unreadable file fails closed only until it lapses; the host rewrites it on its next roster.
  if (!existsSync(file)) return new Set()
  if (now - statSync(file).mtimeMs > RETENTION_LAPSE_MS) return retainedLeads(dataDir)
  return new Set(read(file).harnesses)
}

/** Sessions a valid roster lets the core reopen: Leads, crew, managed main Buddies and a Buddy whose engine switch needs
 * rollback. A recovered unmanaged Buddy is excluded so its person's later Stop Harness stays effective. */
export function retainedLeads(dataDir: string): Set<string> {
  try {
    const kept = read(retentionFile(dataDir))
    const switching = (kept.buddies ?? []).filter(id => {
      const switched = leadSwitchOf(dataDir, id)
      return !switched?.recovered && switchWithin(switched, Date.now(), SWITCH_RECOVERY_MS)
    })
    return new Set([...kept.leads ?? [], ...kept.crew ?? [], ...kept.wakeableBuddies ?? [], ...switching])
  } catch { return new Set() }
}

/** Only the server's current sleep instruction grants an idle close, never a window's Close or a Team purge. A new
 *  awake roster revokes it even while checkpointing. Missing, lapsed or unreadable authority grants no sleep. */
export function retainedSleepingBuddies(dataDir: string, now = Date.now()): Set<string> {
  try {
    if (isTeamDaemon()) return new Set()
    const file = retentionFile(dataDir)
    if (now - statSync(file).mtimeMs > RETENTION_LAPSE_MS) return new Set()
    return new Set(read(file).sleepingBuddies ?? [])
  } catch { return new Set() }
}

/** Whether a stop may reach a Lead, for the core's guard, which fails closed (the review of #1635): with no file this
 *  machine never had a roster, so no Lead; one from before Leads were kept names no Lead apart, so each member may be one;
 *  one that cannot be read may name anyone, until the host's next roster rewrites it. */
export function mayBeLead(dataDir: string, agentId: string): boolean {
  const file = retentionFile(dataDir)
  if (!existsSync(file)) return false
  try {
    const kept = read(file)
    return (kept.leads ?? kept.harnesses).includes(agentId)
  } catch { return true }
}

/** Whether a close may reach a Buddy, for the core's close guard. Like `mayBeLead`, a file that cannot be read may name
 *  anyone until the host's next roster rewrites it; with no file, or one from before Buddies were kept, none is. Unlike a
 *  Lead, a Buddy lapses with a roster nobody confirms for a week, as every other member does.
 *  So protection lasts up to 7 days (`RETENTION_LAPSE_MS`) after the last roster this host read: while the roster cannot
 *  be read (offline, signed out, or this file unreadable), a Buddy, or anyone when the file is unreadable, stays
 *  protected until then, and a close stops it again after that. Stop Harness stops it throughout. */
export function mayBeBuddy(dataDir: string, agentId: string, now = Date.now()): boolean {
  const file = retentionFile(dataDir)
  if (!existsSync(file) || now - statSync(file).mtimeMs > RETENTION_LAPSE_MS) return false
  try { return (read(file).buddies ?? []).includes(agentId) } catch { return true }
}

/** [assignments]: the host form's assignment rows for this machine, which hold their harnesses (task #2744: Tern's last group
 *  was archived, so membership alone no longer kept it). */
export function retainContributions(dataDir: string, machineId: string, rows: unknown[], now = Date.now(), assignments: unknown[] = []): void {
  if (!identifier(machineId)) throw new Error('Invalid Super Tab retention machine.')
  const file = retentionFile(dataDir)
  // This machine's confirmed roster is authoritative: it replaces an unreadable
  // file and another identity's entry. Unchanged rosters only refresh the lapse clock.
  let previous: Retention | null = null
  try { if (existsSync(file)) previous = read(file) } catch { /* rebuilt below */ }
  const ids = new Set<string>(), leads = new Set<string>(), crew = new Set<string>(), buddies = new Set<string>(), wakeableBuddies = new Set<string>(), sleepingBuddies = new Set<string>()
  for (const item of rows) {
    const row = object(item), agent = object(row.agent)
    if (!identifier(row.tabId) || !identifier(agent.harnessId) || agent.machineId !== machineId) continue
    // A session the backend ends (its project deleted, the agent removed) stays kept until the host has closed it, and
    // only if it was a member here before: the host and the core close nothing this file did not already name.
    if (row.closeSession === true && row.lead !== true) {
      if (previous?.machineId === machineId && previous.harnesses.includes(agent.harnessId)) ids.add(agent.harnessId)
      continue
    }
    // A Buddy is in no open group, yet waits for its person however long (backend tidy.ts). Only the server marks one (its
    // agent's buddyOf, set when a person adds their Buddy); a row that ends it carries no agent record, so it is no Buddy.
    if (identifier(object(agent.buddyOf).personId)) {
      buddies.add(agent.harnessId)
      if (row.buddySleepManaged === true && !agent.buddySession && row.stopRequested !== true) {
        wakeableBuddies.add(agent.harnessId)
        if (agent.asleep && !agent.modelRequest && !agent.switchRequest && !agent.switchLanded && !agent.teamAccount) sleepingBuddies.add(agent.harnessId)
      }
    }
    if (row.lead === true) leads.add(agent.harnessId)
    // One whose stop is asked for is no crew the core may reopen (security review 1 of #3222).
    else if (isCrewRow(row) && row.stopRequested !== true) crew.add(agent.harnessId)
    else if (row.active === false && !buddies.has(agent.harnessId)) continue
    ids.add(agent.harnessId)
  }
  const assigned: Record<string, number> = {}
  const before = previous?.machineId === machineId ? previous.assigned ?? {} : {}
  for (const item of assignments) {
    const row = object(item)
    if (identifier(row.tabId) && identifier(row.harnessId)) assigned[row.harnessId] = before[row.harnessId] ?? now
  }
  for (const [id, at] of Object.entries(before)) if (!(id in assigned) && now - at < ASSIGNED_GRACE_MS) assigned[id] = at
  for (const id of Object.keys(assigned)) ids.add(id)
  const next: Retention = { version: 2, machineId, harnesses: [...ids].sort(), leads: [...leads].sort(), ...(crew.size ? { crew: [...crew].sort() } : {}), buddies: [...buddies].sort(), ...(wakeableBuddies.size ? { wakeableBuddies: [...wakeableBuddies].sort() } : {}),
    ...(sleepingBuddies.size ? { sleepingBuddies: [...sleepingBuddies].sort() } : {}),
    assigned: Object.fromEntries(Object.entries(assigned).sort(([a], [b]) => a.localeCompare(b))) }
  if (previous && JSON.stringify(previous) === JSON.stringify(next)) {
    if (now - statSync(file).mtimeMs > REFRESH_MS) utimesSync(file, new Date(now), new Date(now))
    return
  }
  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
  writeFileSync(`${file}.next`, JSON.stringify(next), { mode: 0o600, flush: true })
  renameSync(`${file}.next`, file)
  utimesSync(file, new Date(now), new Date(now))
}