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.

Harnesses are named by who and when — Codex harness 9-17 15:26 — and nothing is counted

dee2566f06b555d
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 5d4578941..f76ba4b8b 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -41,6 +41,7 @@ import { preTrustClaudeProject, preTrustCodexProject } from './lib/claudeTrust.j
import { projectPreview } from './lib/projectPreview.js'
import { agentFrame, type AgentDshContext, type AgentFrame } from './lib/agentFrame.js'
import { installedDsh } from './dsh/installed.js'
+import { engineLabel } from './lib/agentNames.js'
import { DSH_ID_RE } from './dsh/manifest.js'
import { refreshDshRegistry } from './dsh/catalog.js'
import type { DshInstallProgress } from './dsh/install.js'
@@ -1842,7 +1843,7 @@ export class BackendSocket {
void this.agentCreations.run(creationId, creationFingerprint(projectFolder ? { ...input, projectFolder } : input), async () => {
let preparedFolder: string | undefined
if (projectFolder) {
- try { preparedFolder = await prepareProjectFolder(projectFolder, { namesInUse: registry.agentNamesInUse() }) }
+ try { preparedFolder = await prepareProjectFolder(projectFolder, { label: (dsh ? installedDsh(dsh)?.manifest.name : null) ?? engineLabel(input.engine) }) }
catch (error) {
return { state: 'failed', error: error instanceof ProjectFolderError ? error.code : 'PROJECT_PREPARATION_FAILED',
detail: error instanceof ProjectFolderError ? error.message : 'Could not prepare the project folder.' }
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 021e60368..72c0248c6 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -3920,6 +3920,8 @@ async function runForeground(session: AuthSession): Promise<void> {
// links) and take its env/argv for the launch. Refused, never approximated, when it is not here.
let dshEnv: Record<string, string> | undefined
let dshArgs: string[] = []
+ /** A DSH's own name ("Blender"), which the agent is named after instead of its engine. */
+ let dshLabel: string | undefined
if (dsh) {
const installed = installedDsh(dsh)
if (!installed) return { ok: false, error: 'INVALID_DSH', detail: `${dsh} is not installed on this machine` }
@@ -3953,6 +3955,7 @@ async function runForeground(session: AuthSession): Promise<void> {
const launch = dshLaunch(installed, cwd)
dshEnv = launch.env
dshArgs = launch.args
+ dshLabel = installed.manifest.name
}
// Harness-created sessions are easy to distinguish from a user's organic tmux sessions while
// retaining the engine and a collision-resistant creation suffix for diagnostics. Computed
@@ -4046,6 +4049,7 @@ async function runForeground(session: AuthSession): Promise<void> {
agent,
bypassPermission,
defaultName: name,
+ label: dshLabel,
})
if (!result.ok) return { ok: false, error: result.error, detail: result.detail }
const { spawned, pending } = result
diff --git a/cli/src/lib/agentFrame.ts b/cli/src/lib/agentFrame.ts
index ceff1bda5..f7b053364 100644
--- a/cli/src/lib/agentFrame.ts
+++ b/cli/src/lib/agentFrame.ts
@@ -45,10 +45,10 @@ export type AgentFrame = {
userId: string
name: string
/**
- * What the agent is on, in its own words — the transcript's title (Claude Code's, Codex's),
- * cleaned; null when there is none or it is the name already. Not the name: a created agent
- * keeps its `harness-N` name while its title moves with the work, and a client searching for
- * "board fab check" must find it by this, not by luck in a recap.
+ * What the agent is on, in its own words — the session title (Claude Code's, Codex's), cleaned;
+ * null when there is none or it is the name already. It is usually the name too (registry.ts,
+ * projectDisplayName), but not once the person renames the agent, and a client searching for
+ * "board fab check" must still find it by this, not by luck in a recap.
*/
title: string | null
status: string
diff --git a/cli/src/lib/agentNames.spec.ts b/cli/src/lib/agentNames.spec.ts
new file mode 100644
index 000000000..e8350ecd7
--- /dev/null
+++ b/cli/src/lib/agentNames.spec.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { automaticAgentName, engineLabel, isAutomaticName, projectFolderName } from './agentNames.js'
+import { ENGINES } from '../engines/types.js'
+
+describe('agent names: who and when', () => {
+ it('names every engine the way the app does, and passes an unknown one through', () => {
+ for (const engine of ENGINES) expect(engineLabel(engine)).toMatch(/^[A-Z]/)
+ expect(engineLabel('claude')).toBe('Claude')
+ expect(engineLabel('agy')).toBe('Antigravity')
+ expect(engineLabel('newcomer')).toBe('newcomer')
+ })
+
+ it('writes the name in local time, no zero on month, day or hour, two digits for minutes and seconds', () => {
+ expect(automaticAgentName('Codex', new Date(2026, 8, 17, 15, 26))).toBe('Codex harness 9-17 15:26')
+ expect(automaticAgentName('Blender', new Date(2026, 8, 3, 9, 5, 7))).toBe('Blender harness 9-3 9:05')
+ expect(automaticAgentName('Blender', new Date(2026, 8, 3, 9, 5, 7), true)).toBe('Blender harness 9-3 9:05:07')
+ expect(automaticAgentName('Claude', new Date(2026, 11, 25, 0, 0))).toBe('Claude harness 12-25 0:00')
+ expect(automaticAgentName(' ', new Date(2026, 0, 1, 23, 59))).toBe('Agent harness 1-1 23:59')
+ })
+
+ it('knows a name Harness gave from one somebody chose', () => {
+ for (const name of ['Codex harness 9-17 15:26', 'Blender harness 9-3 9:05:07', 'Autonomous Circuit harness 12-25 0:00', 'harness-43', 'agent-7']) {
+ expect(isAutomaticName(name)).toBe(true)
+ }
+ for (const name of ['Local model', 'My harness', 'Codex harness', 'harness-0', 'harness-4x', 'Codex harness 9-17', '', null, undefined]) {
+ expect(isAutomaticName(name)).toBe(false)
+ }
+ })
+
+ it('writes the folder as a slug and a sortable date and time', () => {
+ expect(projectFolderName('Autonomous Circuit', new Date(2026, 8, 3, 9, 5, 7))).toBe('autonomous-circuit-2026-09-03-09-05')
+ expect(projectFolderName('text-to-cad', new Date(2026, 8, 3, 9, 5, 7), true)).toBe('text-to-cad-2026-09-03-09-05-07')
+ expect(projectFolderName('Café Studio', new Date(2026, 11, 25, 15, 26))).toBe('cafe-studio-2026-12-25-15-26')
+ expect(projectFolderName('***', new Date(2026, 11, 25, 15, 26))).toBe('harness-2026-12-25-15-26')
+ })
+})
diff --git a/cli/src/lib/agentNames.ts b/cli/src/lib/agentNames.ts
new file mode 100644
index 000000000..619f15ce3
--- /dev/null
+++ b/cli/src/lib/agentNames.ts
@@ -0,0 +1,63 @@
+/**
+ * What a harness is called before anything better is known, and what its new project folder is called.
+ *
+ * A harness is named by who it is and when it started — "Codex harness 9-17 15:26", "Blender harness
+ * 9-17 15:30" — and its folder the same way, `~/harnesses/codex-2026-09-17-15-26`. That replaced
+ * `harness-N`, which said nothing and had to be counted: a name and a folder numbered by two counters
+ * drifted apart (a tab named harness-43 over a terminal in harness-42) and stayed apart.
+ *
+ * It is a stand-in. Once the engine titles the session, the title is the name (registry.ts,
+ * projectDisplayName), and a rename fixes a name for good.
+ */
+import type { AgentEngine } from '../engines/types.js'
+
+/** The app's own words for each engine (desktop/lib/widgets/engine_identity.dart). */
+const ENGINE_LABELS: Record<AgentEngine, string> = {
+ claude: 'Claude',
+ codex: 'Codex',
+ cursor: 'Cursor',
+ opencode: 'OpenCode',
+ pi: 'Pi',
+ hermes: 'Hermes',
+ commandcode: 'Command Code',
+ devin: 'Devin',
+ muse: 'Muse',
+ amp: 'Amp',
+ kilo: 'Kilo',
+ grok: 'Grok',
+ agy: 'Antigravity',
+ copilot: 'Copilot',
+}
+
+export function engineLabel(engine: string): string {
+ return ENGINE_LABELS[engine as AgentEngine] ?? engine
+}
+
+const pad = (n: number): string => String(n).padStart(2, '0')
+
+/**
+ * "Codex harness 9-17 15:26" — local time on a 24-hour clock. No zero where it says nothing (month,
+ * day and hour: "9-3 9:05"); minutes and seconds always two digits, as a clock reads.
+ */
+export function automaticAgentName(label: string, at: Date, withSeconds = false): string {
+ const clock = `${at.getHours()}:${pad(at.getMinutes())}${withSeconds ? `:${pad(at.getSeconds())}` : ''}`
+ return `${label.trim() || 'Agent'} harness ${at.getMonth() + 1}-${at.getDate()} ${clock}`
+}
+
+/**
+ * A name Harness gave, as opposed to one somebody chose: `<agent> harness M-D HH:MM[:SS]`, or the
+ * `harness-N` / `agent-N` of earlier daemons. Only these give way to the engine's session title.
+ */
+const AUTOMATIC_NAME_RE = /^(?:(?:harness|agent)-[1-9]\d*|.+ harness \d{1,2}-\d{1,2} \d{1,2}:\d{2}(?::\d{2})?)$/
+
+export function isAutomaticName(name: string | null | undefined): boolean {
+ return !!name && AUTOMATIC_NAME_RE.test(name)
+}
+
+/** "codex-2026-09-03-09-05": the label in lowercase words, then the local date and time, every part
+ * two digits so a folder listing sorts in the order the harnesses were made. */
+export function projectFolderName(label: string, at: Date, withSeconds = false): string {
+ const slug = label.normalize('NFKD').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'harness'
+ const time = `${pad(at.getHours())}-${pad(at.getMinutes())}${withSeconds ? `-${pad(at.getSeconds())}` : ''}`
+ return `${slug}-${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}-${time}`
+}
diff --git a/cli/src/lib/claudeTrust.ts b/cli/src/lib/claudeTrust.ts
index 3082c8741..9bc5c9a90 100644
--- a/cli/src/lib/claudeTrust.ts
+++ b/cli/src/lib/claudeTrust.ts
@@ -1,6 +1,6 @@
/**
* Claude Code asks "do you trust this folder?" the first time it opens a project. For a workspace
- * Harness itself just made — a fresh `~/harnesses/harness-N`, or a harness template it laid out —
+ * Harness itself just made — a fresh `~/harnesses/codex-2026-09-17-15-26`, or a harness template it laid out —
* the answer is the one the person already gave by clicking Create, so the daemon records it the
* way Claude Code does: `projects[<path>].hasTrustDialogAccepted` in `~/.claude.json`.
*
diff --git a/cli/src/lib/createAgentPane.ts b/cli/src/lib/createAgentPane.ts
index 9b5c4d494..33d439a07 100644
--- a/cli/src/lib/createAgentPane.ts
+++ b/cli/src/lib/createAgentPane.ts
@@ -35,12 +35,15 @@ export interface CreateAgentPaneDeps {
agent?: string | null
bypassPermission?: boolean
defaultName?: string | null
+ label?: string | null
}) => RegisteredSession | null }
engine: AgentEngine
cwd?: string | null
bypassPermission?: boolean
- /** The name the creator asked for (`agent_create`'s `name`); the registry numbers the agent without one. */
+ /** The name the creator asked for (`agent_create`'s `name`); without one the registry names the agent. */
defaultName?: string | null
+ /** Who the agent is when a DSH says ("Blender") — the name the registry gives is built from it. */
+ label?: string | null
/** Base tmux session name (`-s`). Retries append `-r<attempt>` — see module doc. */
sessionLabel: string
argv: string[]
@@ -93,6 +96,7 @@ export async function createAndRegisterPane(deps: CreateAgentPaneDeps): Promise<
agent: deps.agent,
bypassPermission: deps.bypassPermission,
defaultName: deps.defaultName,
+ label: deps.label,
})
if (pending) return { ok: true, spawned, pending }
console.warn(`[agent] create ${deps.engine} registration failed · pane ${spawned.runtime.paneId} · `
diff --git a/cli/src/lib/projectFolder.spec.ts b/cli/src/lib/projectFolder.spec.ts
index 8c730873e..756f1cf5c 100644
--- a/cli/src/lib/projectFolder.spec.ts
+++ b/cli/src/lib/projectFolder.spec.ts
@@ -21,26 +21,28 @@ describe('project folder preparation', () => {
expect(() => parseProjectFolder({ projectSource: 'new', repositoryUrl: 'owner/repo' })).toThrow(ProjectFolderError)
})
- it('creates different folders for two deliberate new projects', async () => {
- const folders = await Promise.all([prepareProjectFolder({ source: 'new' }, { root }), prepareProjectFolder({ source: 'new' }, { root })])
- expect(new Set(folders).size).toBe(2)
- expect(new Set(folders)).toEqual(new Set([join(root, 'harness-1'), join(root, 'harness-2')]))
- expect(await readdir(root)).toHaveLength(2)
+ const now = () => new Date(2026, 8, 3, 9, 5, 7)
+
+ it('names a new project after its agent and the time, every part two digits so folders sort', async () => {
+ expect(await prepareProjectFolder({ source: 'new' }, { root, label: 'Codex', now })).toBe(join(root, 'codex-2026-09-03-09-05'))
+ expect(await prepareProjectFolder({ source: 'new' }, { root, label: 'Autonomous Circuit', now })).toBe(join(root, 'autonomous-circuit-2026-09-03-09-05'))
+ expect(await prepareProjectFolder({ source: 'new' }, { root, label: ' ', now })).toBe(join(root, 'harness-2026-09-03-09-05'))
+ expect(await prepareProjectFolder({ source: 'new' }, { root, label: '!!', now })).toBe(join(root, 'harness-2026-09-03-09-05-07'))
})
- it('continues numbering past existing folders and files without changing them', async () => {
- await mkdir(join(root, 'agent-2'))
- await writeFile(join(root, 'agent-4'), 'keep')
- expect(await prepareProjectFolder({ source: 'new' }, { root })).toBe(join(root, 'harness-5'))
- expect(await readFile(join(root, 'agent-4'), 'utf8')).toBe('keep')
+ it('gives two projects in the same minute the seconds, then a suffix, and never takes a file’s name', async () => {
+ await writeFile(join(root, 'codex-2026-09-03-09-05'), 'keep')
+ const folders = await Promise.all([1, 2, 3].map(() => prepareProjectFolder({ source: 'new' }, { root, label: 'Codex', now })))
+ expect(new Set(folders)).toEqual(new Set([
+ join(root, 'codex-2026-09-03-09-05-07'), join(root, 'codex-2026-09-03-09-05-07-2'), join(root, 'codex-2026-09-03-09-05-07-3'),
+ ]))
+ expect(await readFile(join(root, 'codex-2026-09-03-09-05'), 'utf8')).toBe('keep')
+ expect(await readdir(root)).toHaveLength(4)
})
- it('numbers past the agent names in use, so the next agent answers to its own folder', async () => {
- await mkdir(join(root, 'harness-42'))
- // The agent in harness-41 is named harness-42 (the old drift) and one agent was renamed.
- const folder = await prepareProjectFolder({ source: 'new' }, { root, namesInUse: ['harness-42', 'harness-43', 'Lamp', null, undefined, 'agent-7x'] })
- expect(folder).toBe(join(root, 'harness-44'))
- expect(await prepareProjectFolder({ source: 'new' }, { root, namesInUse: [] })).toBe(join(root, 'harness-45'))
+ it('uses the clock when no time is given', async () => {
+ const folder = await prepareProjectFolder({ source: 'new' }, { root, label: 'Pi' })
+ expect(folder).toMatch(/\/pi-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}$/)
})
it('publishes a complete clone and never replaces existing files or starts a second clone', async () => {
diff --git a/cli/src/lib/projectFolder.ts b/cli/src/lib/projectFolder.ts
index 61704ce97..765c0d430 100644
--- a/cli/src/lib/projectFolder.ts
+++ b/cli/src/lib/projectFolder.ts
@@ -1,7 +1,8 @@
import { spawn } from 'node:child_process'
-import { lstat, mkdir, mkdtemp, readdir, rename, rm } from 'node:fs/promises'
+import { lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'
+import { projectFolderName } from './agentNames.js'
export type ProjectFolder = { source: 'new' } | { source: 'remote'; repositoryUrl: string; name: string }
@@ -49,14 +50,9 @@ export async function prepareProjectFolder(
options: {
root?: string
clone?: (url: string, destination: string) => Promise<void>
- /**
- * Agent names already taken on this machine. An agent started in `harness-N` answers to
- * `harness-N` only while that name is free (registry.ts, nextAgentName); numbered from the
- * folders alone, one folder once named off by one kept every later one off by one — the tab said
- * harness-43 over a terminal in ~/harnesses/harness-42. Counting the names too puts the next
- * folder past both, where its agent's name is free and the two agree again.
- */
- namesInUse?: Iterable<string | null | undefined>
+ /** Who the harness is ("Codex", "Blender"): a new project folder is named after it and the time. */
+ label?: string | null
+ now?: () => Date
} = {},
): Promise<string> {
const root = options.root ?? join(homedir(), 'harnesses')
@@ -64,15 +60,17 @@ export async function prepareProjectFolder(
try {
await mkdir(root, { recursive: true })
if (project.source === 'new') {
- const numbers = [...await readdir(root), ...(options.namesInUse ?? [])]
- .map(name => (name ? /^(?:harness|agent)-([1-9]\d*)$/.exec(name)?.[1] : undefined))
- let next = numbers.reduce((max, value) => value && BigInt(value) > max ? BigInt(value) : max, 0n) + 1n
- for (;;) {
- const folder = join(root, `harness-${next++}`)
+ // `codex-2026-09-17-15-26` (agentNames.ts): nothing to count. Two in the same minute take the
+ // seconds; the same second, a suffix. mkdir reserves the name atomically, so simultaneous
+ // desktop and remote creates never share a folder; files and symlinks count as taken.
+ const at = (options.now ?? (() => new Date()))()
+ const label = options.label?.trim() || 'harness'
+ const precise = projectFolderName(label, at, true)
+ for (let attempt = 0; ; attempt++) {
+ const name = attempt === 0 ? projectFolderName(label, at) : attempt === 1 ? precise : `${precise}-${attempt}`
+ const folder = join(root, name)
try { await mkdir(folder); return folder }
catch (error) {
- // mkdir reserves the name atomically, including simultaneous desktop
- // and remote creates. Files and symlinks also count as occupied.
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
}
}
diff --git a/cli/src/lib/registry.spec.ts b/cli/src/lib/registry.spec.ts
index a6183f9fe..606c7c20e 100644
--- a/cli/src/lib/registry.spec.ts
+++ b/cli/src/lib/registry.spec.ts
@@ -1024,72 +1024,85 @@ describe('agent identity: the process owns the agent, the session is bound to it
expect(registry.list()).toHaveLength(1)
})
- it('an agent started in a new project folder harness-N is named harness-N, and a second one there is not', async () => {
- const { registry } = await loadRegistryModule()
- registry.load()
- const early = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%3' }], cwd: '/tmp/elsewhere' })!
- expect(registry.displayName(early)).toBe('harness-1')
- const inFolder = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%4' }], cwd: '/Users/u/harnesses/harness-41' })!
- expect(registry.displayName(inFolder)).toBe('harness-41')
- const sameFolder = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%5' }], cwd: '/Users/u/harnesses/harness-41' })!
- expect(registry.displayName(sameFolder)).toBe('harness-42')
- const named = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%6' }], cwd: '/Users/u/code/harness-app' })!
- expect(registry.displayName(named)).toBe('harness-43')
- })
+ describe('the name Harness gives an agent: who it is and when it started', () => {
+ afterEach(() => { vi.useRealTimers() })
+ const at = (y: number, mo: number, d: number, h: number, mi: number, sec = 0) => {
+ vi.useFakeTimers({ toFake: ['Date'] })
+ vi.setSystemTime(new Date(y, mo - 1, d, h, mi, sec))
+ }
- it('lists every name in use, so a new project folder can be numbered past them', async () => {
- const { registry } = await loadRegistryModule()
- registry.load()
- const a = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%11' }], cwd: '/Users/u/harnesses/harness-41' })!
- registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%12' }], cwd: '/Users/u/harnesses/harness-41' })
- registry.rename(a.agentId, 'Lamp')
- const names = registry.agentNamesInUse()
- expect(names).toEqual(expect.arrayContaining(['harness-41', 'harness-42', 'Lamp']))
- expect(names.every((name) => typeof name === 'string' && name.length > 0)).toBe(true)
- })
+ it('is the engine or DSH name and the local time, with no zero where it says nothing', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ at(2026, 9, 17, 15, 26)
+ const codex = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%3' }], cwd: '/Users/u/harnesses/codex-2026-09-17-15-26' })!
+ expect(registry.displayName(codex)).toBe('Codex harness 9-17 15:26')
+ at(2026, 9, 3, 9, 5)
+ const blender = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%4' }], cwd: '/tmp/b', dsh: 'autonomous/blender', label: ' Blender ' })!
+ expect(registry.displayName(blender)).toBe('Blender harness 9-3 9:05')
+ const claude = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%5' }], cwd: '/tmp/c', label: ' ' })!
+ expect(registry.displayName(claude)).toBe('Claude harness 9-3 9:05')
+ })
- it('gives new agents stable numbered names until their session has a title, and a rename fixes a name', async () => {
- const { registry } = await loadRegistryModule()
- registry.load()
- const first = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: '/tmp/demo' })!
- const second = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/demo' })!
- expect(registry.displayName(first)).toBe('harness-1')
- expect(registry.displayName(second)).toBe('harness-2')
- const bound = registry.register({ engine: 'opencode', sessionId: 'session-numbered', tmuxPane: '%7', title: 'OC | Greeting' })!.entry
- expect(registry.displayName(bound)).toBe('Greeting')
- expect(bound.defaultName).toBe('harness-1')
- registry.updateTitle('session-numbered', 'OC | Plan the launch')
- expect(registry.displayName(bound)).toBe('Plan the launch')
- registry.rename(second.agentId, 'My project')
- registry.updateTitle(second.agentId, 'OC | Something else')
- expect(registry.displayName(registry.byAgent(second.agentId)!)).toBe('My project')
- const { registry: reloaded } = await loadRegistryModule()
- reloaded.load()
- expect(reloaded.displayName(reloaded.byAgent(first.agentId)!)).toBe('Plan the launch')
- expect(reloaded.displayName(reloaded.byAgent(second.agentId)!)).toBe('My project')
- const third = reloaded.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%9' }], cwd: '/tmp/demo' })!
- expect(reloaded.displayName(third)).toBe('harness-3')
- reloaded.rename(third.agentId, 'agent-10') // the old prefix still counts, so a hand-typed agent-10 moves the next default past it
- const fourth = reloaded.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%10' }], cwd: '/tmp/demo' })!
- expect(reloaded.displayName(fourth)).toBe('harness-11')
- })
+ it('takes the seconds when the same agent already has that minute, and counts nothing', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ at(2026, 12, 25, 15, 26, 8)
+ const first = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%6' }], cwd: '/tmp/a' })!
+ const second = registry.openPendingAgent({ engine: 'codex', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: '/tmp/a' })!
+ const other = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/a' })!
+ expect([first, second, other].map((agent) => registry.displayName(agent)))
+ .toEqual(['Codex harness 12-25 15:26', 'Codex harness 12-25 15:26:08', 'Claude harness 12-25 15:26'])
+ expect(registry.agentNamesInUse()).toEqual(expect.arrayContaining(['Codex harness 12-25 15:26', 'Codex harness 12-25 15:26:08']))
+ })
- it('opens a pane under the name its creator asked for, keeps it through binding and reload, and does not spend a number on it', async () => {
- const { registry } = await loadRegistryModule()
- registry.load()
- const named = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: '/tmp/demo', defaultName: ' Local model ' })!
- expect(named.defaultName).toBe('Local model')
- expect(registry.displayName(named)).toBe('Local model')
- // The engine reporting a session title does not retitle a pane that was named at creation.
- const bound = registry.register({ engine: 'opencode', sessionId: 'session-named', tmuxPane: '%7', title: 'OC | Greeting' })!.entry
- expect(registry.displayName(bound)).toBe('Local model')
- // Blank means "number it", the same as absent — and the named agent took no number.
- const numbered = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/demo', defaultName: ' ' })!
- expect(registry.displayName(numbered)).toBe('harness-1')
- const { registry: reloaded } = await loadRegistryModule()
- reloaded.load()
- expect(reloaded.displayName(reloaded.byAgent(named.agentId)!)).toBe('Local model')
- expect(reloaded.displayName(reloaded.byAgent(numbered.agentId)!)).toBe('harness-1')
+ it('gives way to the session’s title, which moves with it, until a rename fixes a name — and survives reload', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ at(2026, 9, 17, 15, 30)
+ const first = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%7' }], cwd: '/tmp/demo' })!
+ const second = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%8' }], cwd: '/tmp/demo' })!
+ expect(registry.displayName(first)).toBe('OpenCode harness 9-17 15:30')
+ const bound = registry.register({ engine: 'opencode', sessionId: 'session-named-by-time', tmuxPane: '%7', title: 'OC | Greeting' })!.entry
+ expect(registry.displayName(bound)).toBe('Greeting')
+ expect(bound.defaultName).toBe('OpenCode harness 9-17 15:30')
+ registry.updateTitle('session-named-by-time', 'OC | Plan the launch')
+ expect(registry.displayName(bound)).toBe('Plan the launch')
+ registry.rename(second.agentId, 'My project')
+ registry.updateTitle(second.agentId, 'OC | Something else')
+ expect(registry.displayName(registry.byAgent(second.agentId)!)).toBe('My project')
+ const { registry: reloaded } = await loadRegistryModule()
+ reloaded.load()
+ expect(reloaded.displayName(reloaded.byAgent(first.agentId)!)).toBe('Plan the launch')
+ expect(reloaded.displayName(reloaded.byAgent(second.agentId)!)).toBe('My project')
+ })
+
+ it('treats a harness-N from an earlier daemon as a name Harness gave, and a title replaces it', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ const legacy = registry.openPendingAgent({ engine: 'claude', runtimes: [{ backend: 'tmux', paneId: '%9' }], cwd: '/tmp/old', defaultName: 'harness-42' })!
+ expect(registry.displayName(legacy)).toBe('harness-42')
+ registry.updateTitle(legacy.agentId, '✳ Unitree Go2 squats and wave')
+ expect(registry.displayName(registry.byAgent(legacy.agentId)!)).toBe('Unitree Go2 squats and wave')
+ })
+
+ it('keeps a name the creator asked for through titles, binding and reload; blank means Harness names it', async () => {
+ const { registry } = await loadRegistryModule()
+ registry.load()
+ at(2026, 9, 17, 16, 0)
+ const named = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%10' }], cwd: '/tmp/demo', defaultName: ' Local model ' })!
+ expect(named.defaultName).toBe('Local model')
+ expect(registry.displayName(named)).toBe('Local model')
+ // The engine reporting a session title does not retitle a pane that was named at creation.
+ const bound = registry.register({ engine: 'opencode', sessionId: 'session-named', tmuxPane: '%10', title: 'OC | Greeting' })!.entry
+ expect(registry.displayName(bound)).toBe('Local model')
+ const unnamed = registry.openPendingAgent({ engine: 'opencode', runtimes: [{ backend: 'tmux', paneId: '%11' }], cwd: '/tmp/demo', defaultName: ' ' })!
+ expect(registry.displayName(unnamed)).toBe('OpenCode harness 9-17 16:00')
+ const { registry: reloaded } = await loadRegistryModule()
+ reloaded.load()
+ expect(reloaded.displayName(reloaded.byAgent(named.agentId)!)).toBe('Local model')
+ expect(reloaded.displayName(reloaded.byAgent(unnamed.agentId)!)).toBe('OpenCode harness 9-17 16:00')
+ })
})
it('keeps the named agent a pane was opened as through binding and reload, and drops one that is not an identifier', async () => {
diff --git a/cli/src/lib/registry.ts b/cli/src/lib/registry.ts
index d3e595606..6873618e5 100644
--- a/cli/src/lib/registry.ts
+++ b/cli/src/lib/registry.ts
@@ -16,6 +16,7 @@
import { DSH_ID_RE } from '../dsh/manifest.js'
import { AGENT_NAME_RE } from './engineLaunch.js'
import { namingTitle } from './sessionTitle.js'
+import { automaticAgentName, engineLabel, isAutomaticName } from './agentNames.js'
import {
closeSync,
constants,
@@ -165,8 +166,9 @@ export interface RegisteredSession {
launcherId?: string
transcriptPath: string | null
projectDir: string
- /** Stable default for agents created by Harness — the next `harness-N`, or the name the creator asked
- * for (`agent_create`'s `name`). Discovered agents keep their existing names. */
+ /** Stable default for agents created by Harness — `<agent> harness M-D H:MM` (agentNames.ts), or the
+ * name the creator asked for (`agent_create`'s `name`). Rows from earlier daemons carry `harness-N`.
+ * Discovered agents keep their existing names. */
defaultName?: string
cwd: string | null
/** Authoritative backend-neutral terminal placements for this one process-owned agent. */
@@ -209,18 +211,16 @@ export interface RegisterInput {
/** Display name for a session's "project" tab/tile. A user rename (persisted override) is
* authoritative and FIXED. Until there is one, a session is called what its engine calls it — the
* conversation title Claude Code puts on its terminal, Codex's thread name (sessionTitle.ts) — which
- * moves as the engine retitles it, and says what the agent is doing where harness-43 does not. The
- * numbered name a harness is created with stands in until the engine has a title, a name its creator
- * chose is kept like a rename, and a discovered session falls back to its folder. */
+ * moves as the engine retitles it, and says what the agent is doing. The name a harness is created
+ * with ("Codex harness 9-17 15:26") stands in until the engine has a title, a name its creator chose
+ * is kept like a rename, and a discovered session falls back to its folder. */
export function projectDisplayName(s: RegisteredSession): string {
- // A name the creator chose ("Local model") is fixed like a rename; only a numbered default gives way.
- const chosen = s.defaultName && !NUMBERED_DEFAULT_NAME.test(s.defaultName) ? s.defaultName : null
+ // A name the creator chose ("Local model") is fixed like a rename; only a name Harness gave gives way.
+ const chosen = s.defaultName && !isAutomaticName(s.defaultName) ? s.defaultName : null
return NAME_OVERRIDES.get(s.sessionId) || NAME_OVERRIDES.get(s.agentId) || chosen
|| sessionDisplayTitle(s) || s.defaultName || defaultProjectDisplayName(s)
}
-/** The names a daemon numbers agents with: `harness-N`, and `agent-N` from before the rename. */
-const NUMBERED_DEFAULT_NAME = /^(?:harness|agent)-[1-9]\d*$/
/** The engine's own name for this session, or null while it has none worth showing. */
export function sessionDisplayTitle(s: RegisteredSession): string | null {
@@ -1067,8 +1067,10 @@ class Registry {
/** The engine's named agent the pane was opened as (`agent_create`'s `agent`), validated upstream. */
agent?: string | null
bypassPermission?: boolean
- /** The name the creator asked for, instead of the next `harness-N`. Blank means "number it". */
+ /** The name the creator asked for. Blank or absent means Harness names it (agentNames.ts). */
defaultName?: string | null
+ /** Who the agent is, for the name Harness gives it: a DSH's own name ("Blender"); the engine's by default. */
+ label?: string | null
}): RegisteredSession | null {
if (this.writeBlocked) return null
const runtimes = normalizedRuntimes(input.runtimes)
@@ -1080,7 +1082,7 @@ class Registry {
schemaVersion: 2,
active: true,
launch: { state: 'starting' },
- defaultName: normalizedDefaultName(input.defaultName) ?? this.nextAgentName(input.cwd),
+ defaultName: normalizedDefaultName(input.defaultName) ?? this.automaticName(input.label?.trim() || engineLabel(input.engine), new Date(now)),
agentId,
sessionId: '',
boundAt: null,
@@ -1123,21 +1125,13 @@ class Registry {
].filter((name): name is string => typeof name === 'string' && name.length > 0)
}
- private nextAgentName(cwd?: string | null): string {
- let next = 1n
- const names = this.agentNamesInUse()
- // A new project is the folder `~/harnesses/harness-N`, numbered by its own counter. An agent
- // started in it answers to the same N rather than to this counter, which drifts from that one
- // (the tab said harness-42 over a terminal in ~/harnesses/harness-41). Taken already — a second
- // agent in the same folder — it falls back to the next free number.
- const folder = cwd ? basename(cwd) : null
- if (folder && /^harness-[1-9]\d*$/.test(folder) && !names.includes(folder)) return folder
- for (const name of names) {
- // `agent-N` is the name this daemon gave sessions before the rename; the count carries on
- const match = name && /^(?:harness|agent)-([1-9]\d*)$/.exec(name)
- if (match && BigInt(match[1]!) >= next) next = BigInt(match[1]!) + 1n
- }
- return `harness-${next}`
+ /**
+ * "Codex harness 9-17 15:26", or with the seconds when that name is already taken — two of the same
+ * agent started in one minute. Nothing is counted, so nothing can drift.
+ */
+ private automaticName(label: string, at: Date): string {
+ const name = automaticAgentName(label, at)
+ return this.agentNamesInUse().includes(name) ? automaticAgentName(label, at, true) : name
}
/** Discovered process agents that have no engine session bound yet. */
diff --git a/desktop/lib/core/project_folder.dart b/desktop/lib/core/project_folder.dart
index 245f12d80..db63f596b 100644
--- a/desktop/lib/core/project_folder.dart
+++ b/desktop/lib/core/project_folder.dart
@@ -18,15 +18,16 @@ class ProjectFolderRequest {
if (repository != null) 'repositoryUrl': repository!.url,
};
- /// [namesInUse] are the names this computer's agents already answer to. The daemon names an agent
- /// started in `harness-N` after its folder only while `harness-N` is free, so folders numbered
- /// from the disk alone drifted: once one agent was named a number ahead, every later tab said
- /// harness-43 over a terminal in ~/harnesses/harness-42. Numbering past the names as well puts
- /// the next folder where its agent's name is free, and the two agree again.
+ /// A new project is named after who it is for and when: [label] ("Codex", "Blender") and the
+ /// local time, `codex-2026-09-03-09-05`, every part two digits so a folder listing sorts in the
+ /// order harnesses were made. Nothing is counted — `harness-N` folders numbered apart from agent
+ /// names drifted from them. Two in the same minute take the seconds, then a suffix. The daemon
+ /// names remote projects the same way (cli/src/lib/agentNames.ts).
Future<String> prepareLocal({
String? projectHome,
RepositoryClone Function()? createClone,
- Iterable<String> namesInUse = const [],
+ String label = 'harness',
+ DateTime Function()? now,
}) async {
final home =
Platform.environment['HOME'] ?? Platform.environment['USERPROFILE'];
@@ -44,21 +45,18 @@ class ProjectFolderRequest {
root.path,
);
}
- var next = BigInt.one;
- final numbered = RegExp(r'^(?:harness|agent)-([1-9]\d*)$');
- void count(String name) {
- final match = numbered.firstMatch(name);
- if (match == null) return;
- final number = BigInt.parse(match.group(1)!);
- if (number >= next) next = number + BigInt.one;
- }
- await for (final entry in root.list(followLinks: false)) {
- count(p.basename(entry.path));
- }
- namesInUse.forEach(count);
- for (;;) {
- final folder = p.join(root.path, 'harness-$next');
- next += BigInt.one;
+ final at = (now ?? DateTime.now)();
+ final base = projectFolderName(label, at);
+ final precise = projectFolderName(label, at, withSeconds: true);
+ for (var attempt = 0; ; attempt++) {
+ final folder = p.join(
+ root.path,
+ attempt == 0
+ ? base
+ : attempt == 1
+ ? precise
+ : '$precise-$attempt',
+ );
// Directory.create accepts an existing directory. The platform mkdir
// command reserves it exclusively, so concurrent creates never share
// a workspace. Paths are arguments, never shell text.
@@ -80,3 +78,19 @@ class ProjectFolderRequest {
}
}
}
+
+/// `codex-2026-09-03-09-05`: [label] in lowercase words, then the local date and time.
+String projectFolderName(
+ String label,
+ DateTime at, {
+ bool withSeconds = false,
+}) {
+ String two(int n) => n.toString().padLeft(2, '0');
+ final slug = label
+ .toLowerCase()
+ .replaceAll(RegExp(r'[^a-z0-9]+'), '-')
+ .replaceAll(RegExp(r'^-+|-+$'), '');
+ final time =
+ '${two(at.hour)}-${two(at.minute)}${withSeconds ? '-${two(at.second)}' : ''}';
+ return '${slug.isEmpty ? 'harness' : slug}-${at.year}-${two(at.month)}-${two(at.day)}-$time';
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 4de5de680..c7c896939 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -4715,8 +4715,8 @@ class AppNotifier extends ChangeNotifier {
/// whether to offer Check status instead of inviting another creation.
Future<String> prepareLocalProjectFolder(
ProjectFolderRequest request, {
- Iterable<String> namesInUse = const [],
- }) => request.prepareLocal(namesInUse: namesInUse);
+ String label = 'harness',
+ }) => request.prepareLocal(label: label);
Future<String?> createAgent(
String machineId, {
@@ -4867,9 +4867,17 @@ class AppNotifier extends ChangeNotifier {
final project = repository is String
? ProjectFolderRequest.remote(GitHubRepository.parse(repository)!)
: const ProjectFolderRequest.newProject();
+ final dshId = choices['dsh'];
creation._preparedFolder ??= await prepareLocalProjectFolder(
project,
- namesInUse: machine.agents.map((agent) => agent.name),
+ // The folder is named after who the harness is: the harness's own name, else the engine's.
+ label: dshId is String && dshId.isNotEmpty
+ ? (machine.dsh.entries
+ .where((entry) => entry.id == dshId)
+ .firstOrNull
+ ?.name ??
+ engineIdentity(dshId).label)
+ : engineIdentity(choices['engine'] as String?).label,
);
} on RepositoryCloneException catch (error) {
return creation._complete(error.message);
diff --git a/desktop/test/new_agent_project_folder_test.dart b/desktop/test/new_agent_project_folder_test.dart
index 5887278be..bb3bed5f8 100644
--- a/desktop/test/new_agent_project_folder_test.dart
+++ b/desktop/test/new_agent_project_folder_test.dart
@@ -62,23 +62,19 @@ class _App extends AppNotifier {
authMode: MachineAuthMode.remote,
);
machineStates['m'] = MachineState(machine)
- ..localOnly = local
- ..agents = [
- Agent(id: 'a1', name: 'harness-42', status: 'idle'),
- Agent(id: 'a2', name: 'Lamp', status: 'idle'),
- ];
+ ..localOnly = local;
}
final prepared = <ProjectFolderRequest>[];
- final namesSeen = <List<String>>[];
+ final labels = <String>[];
@override
Future<void> probeEngines(String machineId, {bool force = false}) async {}
@override
Future<String> prepareLocalProjectFolder(
ProjectFolderRequest request, {
- Iterable<String> namesInUse = const [],
+ String label = 'harness',
}) async {
prepared.add(request);
- namesSeen.add(namesInUse.toList());
+ labels.add(label);
return '/local/Harness Projects/project-test';
}
}
@@ -162,8 +158,8 @@ void main() {
expect(connection.calls.last.$2.containsKey('projectSource'), isFalse);
expect(app.prepared.length, local ? 1 : 0);
if (local) {
- expect(app.namesSeen.single, ['harness-42', 'Lamp'],
- reason: 'the folder is numbered past the names this computer\'s agents answer to');
+ expect(app.labels.single, 'Claude',
+ reason: 'the folder is named after who the harness is');
}
connection.fail();
await tester.pumpAndSettle();
diff --git a/desktop/test/project_folder_test.dart b/desktop/test/project_folder_test.dart
index 464c22966..19434c271 100644
--- a/desktop/test/project_folder_test.dart
+++ b/desktop/test/project_folder_test.dart
@@ -6,54 +6,57 @@ import 'package:harness/core/repository_clone.dart';
import 'package:path/path.dart' as p;
void main() {
- test(
- 'new projects use unique folders and preserve existing projects',
- () async {
- final root = await Directory.systemTemp.createTemp(
- 'harness-new-project-test-',
- );
- addTearDown(() => root.delete(recursive: true));
- final existing = File(p.join(root.path, 'keep.txt'));
- await existing.writeAsString('keep');
- const request = ProjectFolderRequest.newProject();
- final folders = await Future.wait([
- request.prepareLocal(projectHome: root.path),
- request.prepareLocal(projectHome: root.path),
- ]);
- expect(folders.toSet(), hasLength(2));
- expect(folders.map(p.basename).toSet(), {'harness-1', 'harness-2'});
- expect(folders.every((folder) => p.isWithin(root.path, folder)), isTrue);
- expect(await existing.readAsString(), 'keep');
- expect(request.payload, {'projectSource': 'new'});
- await File(p.join(root.path, 'agent-4')).writeAsString('keep');
- expect(
- p.basename(await request.prepareLocal(projectHome: root.path)),
- 'harness-5',
- );
- expect(await File(p.join(root.path, 'agent-4')).readAsString(), 'keep');
- },
- );
- test(
- 'a new project is numbered past the names agents already answer to',
- () async {
- final root = await Directory.systemTemp.createTemp(
- 'harness-new-project-names-test-',
- );
- addTearDown(() => root.delete(recursive: true));
- await Directory(p.join(root.path, 'harness-42')).create();
- const request = ProjectFolderRequest.newProject();
- // The agent in harness-41 answers to harness-42, the one in harness-42 to harness-43.
- final folder = await request.prepareLocal(
- projectHome: root.path,
- namesInUse: const ['harness-42', 'harness-43', 'Lamp', 'agent-7x'],
- );
- expect(p.basename(folder), 'harness-44');
- expect(
- p.basename(await request.prepareLocal(projectHome: root.path)),
- 'harness-45',
- );
- },
- );
+ test('a new project is named after its agent and the time, and two in one minute never share a folder', () async {
+ final root = await Directory.systemTemp.createTemp(
+ 'harness-new-project-test-',
+ );
+ addTearDown(() => root.delete(recursive: true));
+ final existing = File(p.join(root.path, 'keep.txt'));
+ await existing.writeAsString('keep');
+ DateTime at() => DateTime(2026, 9, 3, 9, 5, 7);
+ const request = ProjectFolderRequest.newProject();
+ expect(request.payload, {'projectSource': 'new'});
+ // A file already holding the minute's name is never replaced.
+ await File(p.join(root.path, 'codex-2026-09-03-09-05'))
+ .writeAsString('keep');
+ final folders = await Future.wait([
+ request.prepareLocal(projectHome: root.path, label: 'Codex', now: at),
+ request.prepareLocal(projectHome: root.path, label: 'Codex', now: at),
+ ]);
+ expect(folders.map(p.basename).toSet(), {
+ 'codex-2026-09-03-09-05-07',
+ 'codex-2026-09-03-09-05-07-2',
+ });
+ expect(folders.every((folder) => p.isWithin(root.path, folder)), isTrue);
+ expect(await existing.readAsString(), 'keep');
+ expect(
+ await File(p.join(root.path, 'codex-2026-09-03-09-05')).readAsString(),
+ 'keep',
+ );
+ expect(
+ p.basename(
+ await request.prepareLocal(
+ projectHome: root.path,
+ label: 'Autonomous Circuit',
+ now: at,
+ ),
+ ),
+ 'autonomous-circuit-2026-09-03-09-05',
+ );
+ expect(
+ p.basename(await request.prepareLocal(projectHome: root.path)),
+ matches(RegExp(r'^harness-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}$')),
+ );
+ });
+ test('folder names pad every part and fall back to harness', () {
+ final at = DateTime(2026, 12, 25, 0, 0, 9);
+ expect(projectFolderName('Blender', at), 'blender-2026-12-25-00-00');
+ expect(
+ projectFolderName('text-to-cad', at, withSeconds: true),
+ 'text-to-cad-2026-12-25-00-00-09',
+ );
+ expect(projectFolderName('***', at), 'harness-2026-12-25-00-00');
+ });
test(
'remote repository uses the existing safe clone on this computer',
() async {