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
import { execFile } from 'node:child_process'
import { readFile, realpath, stat } from 'node:fs/promises'
import { homedir } from 'node:os'
import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
import { promisify } from 'node:util'
import { isGitHubHost, safeSshAlias } from './githubRepository.js'
import { insideGitCheckout } from './gitProject.js'
import { resolveHost } from './sshHosts.js'
const exec = promisify(execFile)
export type AgentProject = {
name: string
cwd: string
root: string | null
remote: string | null
/** The repository [remote] stands for when its host is an SSH alias (`git@gh-work:acme/api` is `github.com/acme/api`),
* so the same repo is one project on every computer (task #2476). Absent when [remote] names its real host. */
repository?: string
branch: string | null
/** Inside a linked worktree rather than the repository's own checkout. */
worktree?: true
/** The branch still has the name Harness made up at Start; the session's replaces it. */
branchPending?: true
}
/** Compare remote repositories without publishing embedded credentials or transport syntax. */
export function canonicalRepository(raw: string | null): string | null {
if (!raw) return null
const scp = /^(?:[^@/\s]+@)?([^:/\s]+):([^\s]+)$/.exec(raw)
try {
const url = new URL(scp && !raw.includes('://') ? `ssh://${scp[1]}/${scp[2]}` : raw)
if (!['ssh:', 'https:', 'http:', 'git:'].includes(url.protocol) || !url.hostname) return null
let path = url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '')
if (!path || /[\x00-\x20]/.test(path)) return null
const host = url.hostname.toLowerCase()
if (host === 'github.com' || host === 'bitbucket.org') path = path.toLowerCase()
const defaultPort = url.protocol === 'ssh:' ? '22' : url.protocol === 'git:' ? '9418' : ''
const port = url.port === defaultPort ? '' : url.port
return `${host}${port ? `:${port}` : ''}/${path}`
} catch { return null }
}
/** What `ssh -G` said each alias names, for five minutes: every agent's folder is read again each minute, and a
* person's SSH configuration rarely changes. At most 64 names are kept. */
const hostCache = new Map<string, { at: number; value: Promise<string | null> }>()
function cachedHost(alias: string): Promise<string | null> {
const now = Date.now()
const found = hostCache.get(alias)
if (found && now - found.at < 5 * 60_000) return found.value
const value = resolveHost(alias)
hostCache.delete(alias)
hostCache.set(alias, { at: now, value })
if (hostCache.size > 64) hostCache.delete(hostCache.keys().next().value!)
return value
}
/** The repository an SSH remote's host alias stands for, in [canonicalRepository]'s form: `git@gh-work:Acme/Api.git`
* is `github.com/acme/api` when `Host gh-work` has `HostName github.com`, and GitHub's SSH host `ssh.github.com` is
* GitHub. Null when the remote names its real host, is not ssh (only ssh reads ~/.ssh/config), or ssh cannot say. A
* name ssh could read as an option is never asked. */
export async function aliasRepository(raw: string | null, resolve: (alias: string) => Promise<string | null> = cachedHost): Promise<string | null> {
const remote = canonicalRepository(raw)
if (!raw || !remote) return null
const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(raw.trim())?.[1]?.toLowerCase()
if (scheme !== undefined && scheme !== 'ssh') return null
const slash = remote.indexOf('/')
const host = remote.slice(0, slash).replace(/:\d+$/, '')
if (host === 'github.com' || !safeSshAlias(host)) return null
let named: string | null
try { named = (await resolve(host))?.toLowerCase() ?? null } catch { return null }
if (!named) return null
const target = isGitHubHost(named) ? 'github.com' : named
// The alias's port, if any, is the configuration's business, not the repository's.
return target === host ? null : canonicalRepository(`ssh://${target}${remote.slice(slash)}`)
}
/** Bounded subprocesses, no shell, network, or repository mutation. */
async function runGit(cwd: string, args: string[]): Promise<string | null> {
// Every agent's folder is read here as it starts, and a fresh Mac's first harness runs in a
// folder with no `.git`: git's own answer there (exit 128), without running Apple's git stub.
if (!(await insideGitCheckout(cwd))) throw Object.assign(new Error('not a Git checkout'), { code: 128 })
const environment = { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' }
for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_NAMESPACE', 'GIT_PREFIX']) delete (environment as NodeJS.ProcessEnv)[key]
const { stdout } = await exec('git', ['-C', cwd, ...args], {
timeout: 1500, maxBuffer: 16 * 1024, encoding: 'utf8',
env: environment,
})
return stdout.trim() || null
}
async function git(cwd: string, args: string[]): Promise<string | null> {
return runGit(cwd, args).catch(() => null)
}
/** Read the two config values in one Git process. Git still resolves includes,
* worktree config and precedence; the last matching value wins, as with --get. */
async function projectConfig(cwd: string, branch: string | null) {
const marker = branch && !branch.startsWith('Detached ') ? `branch.${branch}.harness` : null
const keys = ['remote.origin.url', ...(marker ? [marker] : [])]
const pattern = `^(${keys.map(key => key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`
let output: string | null
try { output = await runGit(cwd, ['config', '--null', '--get-regexp', pattern]) }
catch (error) {
if ((error as { code?: string | number }).code === 1) return { remote: null, pending: false }
// A large set of duplicate values can exceed the combined output bound.
// Keep the individual reads as a fallback so metadata remains available.
return { remote: await git(cwd, ['config', '--get', 'remote.origin.url']),
pending: marker !== null && await git(cwd, ['config', '--get', marker]) === 'placeholder' }
}
const values = new Map<string, string | null>()
for (const record of output?.split('\0') ?? []) {
if (!record) continue
// -z separates records with NUL and each key from its value with a newline.
// A valueless entry has no newline and overrides an earlier value too.
const separator = record.indexOf('\n')
const key = separator < 0 ? record : record.slice(0, separator)
values.set(key, separator < 0 ? null : record.slice(separator + 1).trim() || null)
}
return { remote: values.get('remote.origin.url') ?? null, pending: marker !== null && values.get(marker) === 'placeholder' }
}
/** Read paths and a resolved branch in one process. Absolute output preserves
* linked worktree names even when cwd is a subdirectory or a symlink. */
async function repositoryPaths(cwd: string): Promise<{ root: string; common: string | null; branch?: string | null } | null> {
try {
if (!(await stat(cwd)).isDirectory()) return null
} catch (error) {
// Historical sessions can point at deleted temporary folders. Other stat
// failures still defer to Git rather than asserting that a checkout is gone.
if (['ENOENT', 'ENOTDIR'].includes((error as NodeJS.ErrnoException).code ?? '')) return null
}
let output: string | null
let resolved = true
try {
output = await runGit(cwd, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir', '--abbrev-ref=loose', 'HEAD'])
} catch (error) {
const failed = error as { code?: number | string; stdout?: string }
// An unborn HEAD exits 128 after printing the two valid paths and HEAD.
// Keep those paths, then let symbolic-ref read the unborn branch as before.
output = failed.code === 128 && typeof failed.stdout === 'string' ? failed.stdout.trim() || null : null
resolved = false
}
if (!output) return null
const paths = output.split('\n')
// Ambiguous HEAD names can omit the ref while still exiting successfully.
if (resolved && paths.length === 2 && paths.every(isAbsolute)) return { root: paths[0], common: paths[1] }
if (paths.length === 3 && paths.slice(0, 2).every(isAbsolute) && (resolved || paths[2] === 'HEAD')) {
// A resolved literal HEAD is detached; undefined means symbolic-ref is
// still needed (unborn, ambiguous, or the compatibility path below).
return { root: paths[0], common: paths[1], ...(resolved ? { branch: paths[2] === 'HEAD' ? null : paths[2] } : {}) }
}
// Older Git prints an unrecognised --path-format flag literally. Ambiguous
// output (including a newline in a physical path) retains the separate reads.
const root = await git(cwd, ['rev-parse', '--show-toplevel'])
return root ? { root, common: await git(root, ['rev-parse', '--git-common-dir']) } : null
}
// Only four folders run Git at once, including cache refreshes.
let running = 0
const waiting: Array<() => void> = []
async function inspect(cwd: string): Promise<AgentProject> {
if (running >= 4) await new Promise<void>(resolve => waiting.push(resolve))
else running++
try {
const paths = await repositoryPaths(cwd)
if (!paths) return { name: basename(cwd) || cwd, cwd, root: null, remote: null, branch: null }
const { root, common } = paths
// A checkout on no branch still says where it is, as the desktop's own reader does.
const branch = (paths.branch === undefined
? await git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']) : paths.branch)
?? await git(cwd, ['rev-parse', '--short', 'HEAD']).then(sha => sha && `Detached ${sha}`)
const { remote, pending } = await projectConfig(cwd, branch)
// A linked worktree is named for its repository, not its folder.
const main = common && basename(common) === '.git' ? dirname(resolve(root, common)) : root
const repository = await aliasRepository(remote)
return {
name: basename(main), cwd, root, remote: canonicalRepository(remote), ...(repository ? { repository } : {}), branch,
...(main !== root ? { worktree: true as const } : {}), ...(pending ? { branchPending: true as const } : {}),
}
} finally {
const next = waiting.shift()
if (next) next()
else running--
}
}
/** Cheap freshness check for known Git metadata, including linked worktrees and
* nested repositories created under a previously inspected directory. Git still
* resolves all values; these stamps only avoid repeating it when nothing moved.
* Untracked config includes are covered by the bounded full-refresh interval. */
async function metadataStamp(cwd: string, project: AgentProject): Promise<string | null> {
try {
if (project.root && !project.branch) return null
const physical = await realpath(cwd)
const directory = await stat(physical)
if (!directory.isDirectory()) return null
const paths = new Set<string>()
for (let path = physical, depth = 0; depth < 128; depth++) {
paths.add(join(path, '.git'))
if (path === project.root || dirname(path) === path) break
path = dirname(path)
}
const smallFile = async (path: string): Promise<string | null> => {
paths.add(path)
const info = await stat(path).catch(error => {
if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
throw error
})
if (!info) return null
if (!info.isFile() || info.size > 16 * 1024) throw new Error('Uncacheable Git metadata')
return (await readFile(path, 'utf8')).trim()
}
if (project.root) {
const marker = join(project.root, '.git')
const info = await stat(marker)
let gitDir = marker
if (!info.isDirectory()) {
const markerText = await smallFile(marker)
if (!markerText?.startsWith('gitdir: ')) return null
gitDir = resolve(project.root, markerText.slice(8))
}
paths.add(join(gitDir, 'HEAD'))
paths.add(join(gitDir, 'config'))
paths.add(join(gitDir, 'config.worktree'))
const common = await smallFile(join(gitDir, 'commondir'))
if (common) paths.add(join(resolve(gitDir, common), 'config'))
}
paths.add(process.env.GIT_CONFIG_GLOBAL || join(homedir(), '.gitconfig'))
paths.add(join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'git', 'config'))
paths.add(process.env.GIT_CONFIG_SYSTEM || '/etc/gitconfig')
const stamps = await Promise.all([...paths].map(async path => {
const info = await stat(path).catch(error => {
if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
throw error
})
// Index/lock activity changes the .git directory's mtime without changing
// this projection. Its identity, HEAD and config are the relevant inputs.
return [path, !info ? null : info.isDirectory()
? [info.dev, info.ino, 'directory']
: [info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs]]
}))
// A visible .git marker with no resolved repository can mean an unavailable
// checkout or a failed Git process, not a stable non-repository folder.
if (!project.root && stamps.some(([path, stamp]) => typeof path === 'string' && path.endsWith('/.git') && stamp !== null)) return null
return JSON.stringify([physical, directory.dev, directory.ino, stamps])
} catch { return null }
}
/** A `cwd` worth running Git in: absolute, bounded, printable. Exported for the SCM seam
* (`scm/scmProjects.ts`), which must answer null for exactly the folders this does. */
export function validProjectCwd(cwd: string | null | undefined): cwd is string {
return !!cwd && isAbsolute(cwd) && cwd.length <= 4096 && !/[\x00-\x1f\x7f]/.test(cwd)
}
export function createAgentProjectReader(lookup: (cwd: string) => Promise<AgentProject> = inspect) {
type Entry = { at: number; gitAt: number; pending: boolean; stamp: string | null; value: Promise<AgentProject> }
const cache = new Map<string, Entry>()
const trim = () => {
// Pending work must survive both expiry and eviction, otherwise a slow
// queue creates duplicate Git subprocesses for the same directory.
for (const [key, entry] of cache) {
if (cache.size <= 1024) break
if (!entry.pending) cache.delete(key)
}
}
const read = (cwd: string | null, now = Date.now()): Promise<AgentProject | null> => {
if (!validProjectCwd(cwd)) return Promise.resolve(null)
const found = cache.get(cwd)
if (found && (found.pending || now - found.at < 15_000)) {
cache.delete(cwd)
cache.set(cwd, found)
return found.value
}
const started = Date.now()
const entry: Entry = { at: now, gitAt: found?.gitAt ?? now, pending: true, stamp: null, value: null! }
entry.value = (async () => {
const previous = found ? await found.value : null
const before = previous ? await metadataStamp(cwd, previous) : null
if (found?.stamp && before === found.stamp && now - found.gitAt < 60_000) {
entry.stamp = before
return previous!
}
const value = await lookup(cwd)
const after = await metadataStamp(cwd, value)
// Only reuse a snapshot if its inputs stayed stable across the Git read.
// A first lookup has no resolved Git directory yet and warms this on the
// next refresh; a checkout racing a lookup never becomes a cached fact.
entry.stamp = before && before === after ? after : null
entry.gitAt = now + Math.max(0, Date.now() - started)
return value
})().finally(() => {
entry.pending = false
entry.at = now + Math.max(0, Date.now() - started)
trim()
})
cache.delete(cwd)
cache.set(cwd, entry)
trim()
return entry.value
}
return { read, forget: (cwd: string) => { cache.delete(cwd) } }
}
// Agent lists and push frames share this reader. Branch changes still become
// visible within 15 seconds; unchanged historical paths do not fork Git again.
const projects = createAgentProjectReader()
export const agentProject = projects.read
/** Forget what was read for `cwd`, as after renaming its branch. */
export const forgetAgentProject = projects.forget