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.

8.3 KB
Raw Blame
/** What a failed start's reason says to a group member who is neither its Lead nor its machine's owner. A host's raw reason
 *  can name the machine, a folder on it or a token problem (a privacy check's gitconfig path, the GitHub App token on
 *  2026-10-27), and every member reads the group and its starts (review of #1847). */
import { actorKey, type Actor, type AgentStart, type Conversation, type SuperTabState } from './model.js'
import { projectsOf } from './projects.js'
import { isBuddyChat } from './buddies.js'
import { DEFAULT_COORDINATOR_NAME } from './instructions.js'

export const MACHINE_FAILED = 'Its machine could not prepare or launch it.'
export const TIMED_OUT = 'Its machine did not start it within 3 minutes.'
/** liveness.ts writes `<machine name> did not start it within 3 minutes`. */
export const TIMED_OUT_SUFFIX = ' did not start it within 3 minutes'
/** liveness.ts writes these after a machine named the start as preparing: past its limit, or with its reports stopped. */
export const STILL_PREPARING_SUFFIX = ' was still preparing it after 15 minutes'
export const STOPPED_REPORTING_SUFFIX = ' stopped reporting while preparing it'
/** liveness.ts failRefusedStarts writes `<machine name> refused it: <the server's refusal>`, which members read as a machine
 *  failure (publicReason); whoever made it, its coordinator and its machine's owner read the refusal (task #2441). */
export const REFUSED_INFIX = ' refused it: '
/** liveness.ts writes this after a machine named a coordinator's start that it never took (leadStart.ts), with the name its
 *  project calls it. */
export const leadPickupSuffix = (name: string) => ` did not start this ${name}. Harness there may need an update.`
const LEAD_NOT_PICKED = 'Its machine did not start it. Harness there may need an update.'
/** That suffix, and the one written before project instructions, after any name. */
const LEAD_PICKUP = / did not start this .+\. (Harness there may need an update|Update Harness on it, then start it again)\.$/
/** Each suffix the server writes after a machine name, with what a group member reads instead. */
const TIMEOUTS: Array<[string, string]> = [[TIMED_OUT_SUFFIX, TIMED_OUT],
  [STILL_PREPARING_SUFFIX, 'Its machine was still preparing it after 15 minutes.'],
  [STOPPED_REPORTING_SUFFIX, 'Its machine stopped reporting while preparing it.']]
/** Reasons the server writes itself, which name nothing (commands.ts removeMachine and machine.contribute). */
export const MACHINE_REMOVED = 'Its machine was removed from the Swarm.'
/** Its machine's computer is signed in to another account now (commands.ts machine.moved, #3122). */
export const MACHINE_MOVED = 'Its machine is signed in to another account now.'
export const ABANDONED = 'Abandoned before it started.'
/** A Team account's host refusing a Codex Product Manager it cannot sign in (cli superTabs/start.ts): it names nothing of the
 *  machine but its lack of the owner's relay, which its project reads (security re-check 3 of #2089). */
export const NO_PM_RELAY = 'The owner\'s subscription relay is not available on this machine, so a Codex Product Manager cannot sign in here.'

/** A host's refusal for memory (cli superTabs/capacity.ts memoryShort): its numbers alone, which members already see in the
 *  Machines view. Read only at the start of the reason, so nothing else a host wrote is ever told (Ken's MacBook Pro,
 *  2026-10-28, where "could not prepare or launch it" sent people looking for a fault). */
const MEMORY_SHORT = /^Not enough free memory: (\d+(?:\.\d)? GiB) free, (\d+(?:\.\d)? GiB) needed\./

/** Faults of the machine itself, in the fixed words this CLI writes (cli superTabs/start.ts, lib/agentCreationReceipt.ts,
 *  superTabs/projectFolder.ts), told to every reader (task #3861): the creation folder, only under the home folder as `~/...` in plain
 *  path characters and with nothing after the sentence, and a clone that failed, without whatever git said after. Anything else
 *  a host adds is not told. */
const CREATION_FOLDER = /^CREATION_STORAGE_FAILED: The creation folder (~\/[\w.-]+(?:\/[\w.-]+){0,6}) is not usable by this account \(permissions\)\. It must belong to this account with mode 700; the owner of this computer fixes that, Harness does not change it\.$/
const CLONE_FAILED = /^This machine could not clone the project repository with the Harness GitHub App's token(?::|$)/

export function publicReason(error: string): string {
  if (error === MACHINE_REMOVED || error === ABANDONED || error === NO_PM_RELAY) return error
  const folder = CREATION_FOLDER.exec(error)
  if (folder) return `Its machine's creation folder ${folder[1]} is not usable by its account (permissions): the owner of that computer fixes its owner and mode.`
  if (CLONE_FAILED.test(error)) return "Its machine could not clone the project repository with the Harness GitHub App's token."
  const memory = MEMORY_SHORT.exec(error)
  if (memory) return `Its machine has only ${memory[1]} of memory free, and it needs ${memory[2]}.`
  if (LEAD_PICKUP.test(error)) return LEAD_NOT_PICKED
  return TIMEOUTS.find(([suffix]) => error.endsWith(suffix))?.[1] ?? MACHINE_FAILED
}

/** The group's notice of a failed start, with the model it asked for (project instructions, phase 4, decision 18): what
 *  happened, never what to do next. Whoever made it, its coordinator ([coordinator], as its project calls it) and its machine's
 *  owner read the raw reason on the start (readsRawReason). */
export function failureNotice(name: string, error: string, model?: string, coordinator = DEFAULT_COORDINATOR_NAME): string {
  const reason = publicReason(error)
  return `Could not start ${name}${model ? ` on ${model}` : ''}: ${reason[0]!.toLowerCase()}${reason.slice(1)}`
    + (reason === MACHINE_FAILED ? ` Whoever started it, the ${coordinator} and the machine owner can read why.` : '')
}

/** The model a start asked for: its grid model, else its model; none when it runs its engine's own. */
export const askedModel = (start: AgentStart): string | undefined => start.request.gridModel ?? start.request.model

/** Who a failed start's notice reaches: its task's coordinator, and the agent that made the start when it is in the task
 *  (project instructions, phase 4, decision 18). */
export function failureRecipients(start: AgentStart, group: Conversation): string[] {
  const coordinator = group.leadId && group.agentIds.includes(group.leadId) ? [group.leadId] : []
  const maker = start.actorKey?.startsWith('agent:') ? start.actorKey.slice('agent:'.length) : null
  return [...new Set([...coordinator, ...maker && group.agentIds.includes(maker) ? [maker] : []])]
}

/** Where a failed start's notice reaches its project's coordinator when the notice in the task does not ([recipients]): a task
 *  with no lead, or one its lead left. Its own chat, to it alone; null when the task's notice reaches it or it has none, so a
 *  failed start is never told to nobody (final review). Never a Buddy's: its owner reads it in their chat, and its name and
 *  model are theirs, not the coordinator's or its terminal's watchers' (security review L1; liveness.ts buddyNotice). */
export function coordinatorCopy(state: SuperTabState, group: Conversation, recipients: readonly string[]): { conversationId: string; coordinator: string } | null {
  if (isBuddyChat(group)) return null
  const chat = state.conversations.find(c => c.id === projectsOf(state).find(p => p.id === (group.projectId ?? 'lead'))?.leadConversationId)
  const coordinator = chat?.leadId && chat.agentIds.includes(chat.leadId) ? chat.leadId : null
  return chat && coordinator && chat.id !== group.id && !recipients.includes(coordinator) ? { conversationId: chat.id, coordinator } : null
}

/** Who reads a start's raw reason: whoever made it, its group's coordinator, its machine's owner, and a Buddy chat's owner. */
export function readsRawReason(actor: Actor, start: AgentStart, group: Conversation | undefined): boolean {
  if (start.actorKey === actorKey(actor)) return true
  if (actor.kind === 'agent') return !!group?.leadId && group.leadId === actor.agentId
  if (actor.userId === start.machineOwnerId) return true
  // A Buddy chat is read only by its owner (buddies.ts openBuddyChat), so its owner reads why their own Buddy did not
  // start even when an agent made the start for them or the machine belongs to someone else.
  return !!group && isBuddyChat(group) && group.audience?.people.some(p => p.id === actor.userId) === true
}