@shardflux/cli 0.11.1 → 0.13.1

package/dist/agent-git-commands.js

@@ -0,0 +1,294 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Shardflux, ShardfluxApiError } from '@shardflux/sdk';
+import { out, resolveWorkspace, str } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { resolveApiUrl } from "./args.js";
+import { AgentGit, agentName } from "./agent-git.js";
+import { shardRemote } from "./git-remote.js";
+import { projectIdentity } from "./project-identity.js";
+import { UsageError } from "./errors.js";
+import { workspaceRepositoryPath } from "./agent-repository.js";
+const execute = promisify(execFile);
+const DAY = 86_400_000;
+const missing = (error) => error instanceof ShardfluxApiError && error.status === 404;
+export { needsGitSeed, seedAgentRepository } from "./agent-repository.js";
+export async function rememberGitAgent(ctx, ws, folder) {
+    if (!ws.labels.agent || ws.labels.agent === 'main')
+        return;
+    const project = projectIdentity(folder);
+    if (ws.labels.repo_remote && ws.labels.repo_remote !== project.remote)
+        return;
+    let git;
+    try {
+        git = await AgentGit.open(folder, new AgentStateStore(ctx.store.dir), { ...process.env, ...ctx.io.env }, ctx.signal);
+    }
+    catch (error) {
+        if (error.code === 128)
+            return;
+        throw error;
+    }
+    await git.locked(() => git.track(agentName(ws.labels.agent || ws.key.split('/').at(-1)), {
+        workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl,
+        remote_path: workspaceRepositoryPath(ws), next_check: Date.now() + 60_000,
+    }));
+}
+async function selection(ctx, ref, folder) {
+    const store = new AgentStateStore(ctx.store.dir);
+    const repos = (store.read().git_repositories ?? {});
+    const matches = Object.values(repos).filter(repo => Object.entries(repo.agents).some(([name, entry]) => entry.api_url === ctx.apiUrl && (entry.workspace_key === ref || entry.workspace_id === ref || !ref.includes('/') && name === ref)));
+    const env = { ...process.env, ...ctx.io.env, SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_CONFIG_DIR: ctx.store.dir };
+    let git;
+    try {
+        git = await AgentGit.open(folder ?? './', store, env, ctx.signal);
+    }
+    catch (error) {
+        if (folder || !ref.includes('/') || matches.length !== 1)
+            throw error;
+        git = await AgentGit.open(matches[0].root, store, env, ctx.signal);
+    }
+    if (!folder && ref.includes('/') && matches.length === 1 && !Object.values(git.entries()).some(entry => entry.workspace_key === ref || entry.workspace_id === ref))
+        git = await AgentGit.open(matches[0].root, store, env, ctx.signal);
+    const found = Object.entries(git.entries()).find(([name, entry]) => entry.api_url === ctx.apiUrl && (entry.workspace_key === ref || entry.workspace_id === ref || name === ref));
+    const name = agentName(found?.[0] ?? ref.split('/').at(-1));
+    const key = found?.[1].workspace_key ?? (ref.includes('/') ? ref : `${projectIdentity(git.root).slug}/${name}`);
+    if (name === 'main')
+        throw new UsageError('finish an extra agent; the project main workspace is preserved');
+    return { git, name, key };
+}
+async function workspace(ctx, git, name, key) {
+    const ws = await resolveWorkspace(ctx, key);
+    if (ws.data.deleted_at)
+        throw new UsageError(`workspace ${key} is gone; use shard agents restore ${name} if it was archived`);
+    const project = projectIdentity(git.root);
+    if (ws.labels.repo_remote && ws.labels.repo_remote !== project.remote)
+        throw new UsageError('agent repository does not match this local repository');
+    const saved = git.entries()[name];
+    if (saved && saved.workspace_id !== ws.id)
+        throw new UsageError('workspace identity changed; saved work belongs to the previous agent');
+    await git.track(name, { workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl, remote_path: workspaceRepositoryPath(ws), next_check: Date.now() + 60_000 });
+    return ws;
+}
+async function fetch(ctx, git, name, ws, path) {
+    const entry = git.entries()[name];
+    const remotePath = path ?? entry.remote_path;
+    shardRemote(entry.workspace_key, remotePath);
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    try {
+        const status = await cell.exec.run(['git', '-C', remotePath, 'status', '--porcelain', '--untracked-files=all'], { timeoutMs: 15_000, signal: ctx.signal });
+        if (status.exitCode !== 0)
+            throw new UsageError(`cannot read the agent repository at ${remotePath}: ${status.stderr.trim()}`);
+        if (status.stdout.trim())
+            throw new UsageError('agent repository has uncommitted files; commit them in the agent before fetching its work');
+    }
+    finally {
+        cell.close();
+    }
+    await git.fetch(name, shardRemote(entry.workspace_key, remotePath));
+    git.save(name, { ...entry, remote_path: remotePath });
+}
+async function deleteWorkspace(ctx, entry) {
+    let ws;
+    try {
+        ws = await ctx.cloud().request('GET', `/v1/workspaces/${encodeURIComponent(entry.workspace_id)}`, { signal: ctx.signal });
+    }
+    catch (error) {
+        if (missing(error))
+            return;
+        throw error;
+    }
+    if (ws.id !== entry.workspace_id || ws.workspace_key !== entry.workspace_key)
+        throw new UsageError('workspace identity changed; cleanup preserved the saved work');
+    if (!ws.deleted_at) {
+        if (entry.disposition !== 'discard' && ws.agents?.some(agent => agent.state === 'working'))
+            throw new UsageError('agent is working; park it before finishing cleanup');
+        const result = await ctx.cloud().request('DELETE', `/v1/workspaces/${encodeURIComponent(entry.workspace_id)}`, { signal: ctx.signal });
+        if (!result.workspace || result.workspace.id !== entry.workspace_id || !result.workspace.deleted_at)
+            throw new Error('workspace deletion returned no tombstone receipt; saved work was preserved');
+    }
+}
+function finishHandler(action) {
+    return async (ctx, values, [ref]) => {
+        if (!ref)
+            throw new UsageError(`agents ${action} requires an agent`);
+        const { git, name, key } = await selection(ctx, ref, str(values.path));
+        return git.locked(async () => {
+            let entry = git.entries()[name];
+            if (!entry) {
+                await workspace(ctx, git, name, key);
+                entry = git.entries()[name];
+            }
+            if (entry.archived_at !== undefined && action !== 'discard')
+                throw new UsageError(`agent ${name} is archived; restore it first`);
+            if (!entry.disposition && action !== 'discard') {
+                const ws = await workspace(ctx, git, name, key);
+                if (ws.data.agents?.some(agent => agent.state === 'working'))
+                    throw new UsageError('agent is working; park it before merging or keeping its work');
+                await fetch(ctx, git, name, ws, str(values['remote-path']));
+            }
+            let pr;
+            const push = action === 'keep' && values.push === true ? async (branch) => {
+                await git.run(['push', '--set-upstream', 'origin', `refs/heads/${branch}:refs/heads/${branch}`]);
+                // A missing gh is fine; an installed but failing gh leaves the agent intact for a retry.
+                try {
+                    await execute('gh', ['--version'], { timeout: 5000 });
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return;
+                    throw error;
+                }
+                try {
+                    pr = (await execute('gh', ['pr', 'view', branch, '--json', 'url', '--jq', '.url'], { cwd: git.root, timeout: 30_000, env: { ...process.env, GH_PROMPT_DISABLED: '1' } })).stdout.trim();
+                }
+                catch {
+                    pr = (await execute('gh', ['pr', 'create', '--head', branch, '--fill'], { cwd: git.root, timeout: 30_000, env: { ...process.env, GH_PROMPT_DISABLED: '1' } })).stdout.trim();
+                }
+            } : undefined;
+            const result = await git.finish(name, action, entry => deleteWorkspace(ctx, entry), push);
+            out(ctx, `${action === 'merge' ? 'Merged' : action === 'keep' ? 'Kept' : 'Discarded'} ${key}${result.branch ? ` as ${result.branch}` : ''}${pr ? `: ${pr}` : ''}\n`, { agent: key, action, ...result, ...(pr ? { pr } : {}) });
+            return 0;
+        });
+    };
+}
+export const AGENT_GIT_HANDLERS = {
+    'agents merge': finishHandler('merge'), 'agents keep': finishHandler('keep'), 'agents discard': finishHandler('discard'),
+    async 'agents worktree'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('agents worktree requires an agent');
+        const { git, name, key } = await selection(ctx, ref, str(values.path));
+        return git.locked(async () => {
+            const ws = await workspace(ctx, git, name, key);
+            await fetch(ctx, git, name, ws, str(values['remote-path']));
+            const path = await git.openWorktree(name);
+            out(ctx, `${path}\n`, { agent: key, path, ref: git.ref(name) });
+            return 0;
+        });
+    },
+    async 'agents restore'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('agents restore requires an agent');
+        const { git, name, key } = await selection(ctx, ref, str(values.path));
+        return git.locked(async () => {
+            const branch = await git.restore(name);
+            out(ctx, `Restored ${key} as ${branch}\n`, { agent: key, branch });
+            return 0;
+        });
+    },
+};
+/** No Git or network work when no records are due. Active passes are bounded and never infer deletion from an error. */
+export async function housekeeping(ctx, now = Date.now, budgetMs = 1500) {
+    const store = new AgentStateStore(ctx.store.dir);
+    const repos = (store.read().git_repositories ?? {});
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), budgetMs);
+    const signal = AbortSignal.any([ctx.signal, controller.signal]);
+    const bounded = { ...ctx, signal };
+    try {
+        for (const [common, repo] of Object.entries(repos)) {
+            if (!Object.values(repo.agents).some(e => e.api_url === ctx.apiUrl && e.next_check <= now()))
+                continue;
+            if (signal.aborted)
+                break;
+            const opened = await AgentGit.open(repo.root, store, { ...process.env, ...ctx.io.env }, signal);
+            if (opened.common !== common)
+                throw new UsageError('saved repository identity changed; housekeeping preserved its records');
+            const git = new AgentGit(repo.root, common, store, opened.run, now);
+            await git.locked(async () => {
+                for (const [name, entry] of Object.entries(git.entries())) {
+                    if (signal.aborted)
+                        break;
+                    if (entry.api_url !== ctx.apiUrl || entry.next_check > now() || entry.disposition)
+                        continue;
+                    if (entry.delete_pending) {
+                        const pending = await bounded.cloud().request('GET', `/v1/workspaces/${encodeURIComponent(entry.workspace_id)}`, { signal }).catch(error => { if (missing(error))
+                            return undefined; throw error; });
+                        if (pending && !pending.deleted_at && (pending.observed_state !== 'suspended' || pending.desired_state !== 'suspended' || pending.active_operation || pending.agents?.some(agent => agent.state === 'working'))) {
+                            git.save(name, { ...entry, next_check: now() + 60_000 });
+                            continue;
+                        }
+                        await deleteWorkspace(bounded, entry);
+                        const archived = { ...entry };
+                        delete archived.delete_pending;
+                        git.save(name, { ...archived, next_check: archived.archived_at + 30 * DAY });
+                        continue;
+                    }
+                    if (entry.archived_at !== undefined) {
+                        await git.removeWorktree(name);
+                        await git.run(['update-ref', '-d', git.ref(name)]);
+                        if (now() >= entry.archived_at + 30 * DAY) {
+                            await git.run(['update-ref', '-d', git.ref(name, true)]);
+                            git.save(name);
+                        }
+                        else
+                            git.save(name, { ...entry, next_check: entry.archived_at + 30 * DAY });
+                        continue;
+                    }
+                    let ws;
+                    try {
+                        ws = await bounded.cloud().request('GET', `/v1/workspaces/${encodeURIComponent(entry.workspace_id)}`, { signal });
+                    }
+                    catch (error) {
+                        if (!missing(error))
+                            throw error;
+                    }
+                    if (ws && (ws.id !== entry.workspace_id || ws.workspace_key !== entry.workspace_key))
+                        throw new UsageError('workspace identity changed; housekeeping preserved saved work');
+                    if (!ws || ws.deleted_at) {
+                        await git.archive(name);
+                        continue;
+                    }
+                    const deleteAt = ws.retention?.delete_at ? Date.parse(ws.retention.delete_at) : NaN;
+                    if (Number.isFinite(deleteAt) && deleteAt <= now() && ws.observed_state === 'suspended' && ws.desired_state === 'suspended' && !ws.active_operation && !ws.agents?.some(agent => agent.state === 'working')) {
+                        await git.assertCleanWorktree(name);
+                        // Retention owns deletion. Archive first so a transient delete failure cannot lose saved commits.
+                        if (!await git.archive(name)) {
+                            try {
+                                await deleteWorkspace(bounded, entry);
+                            }
+                            catch (error) {
+                                git.save(name, { ...entry, next_check: now() + 60_000 });
+                                throw error;
+                            }
+                            continue;
+                        }
+                        git.save(name, { ...git.entries()[name], delete_pending: true, next_check: now() + 60_000 });
+                        await deleteWorkspace(bounded, entry);
+                        const archived = { ...git.entries()[name] };
+                        delete archived.delete_pending;
+                        git.save(name, { ...archived, next_check: archived.archived_at + 30 * DAY });
+                    }
+                    else
+                        git.save(name, { ...entry, next_check: now() + 60_000 });
+                }
+                await git.run(['worktree', 'prune']);
+            });
+        }
+    }
+    catch (error) {
+        if (!controller.signal.aborted && !ctx.signal.aborted)
+            ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export async function startupHousekeeping(ctx) {
+    try {
+        const state = new AgentStateStore(ctx.store.dir).read();
+        if (!state.git_repositories || !Object.keys(state.git_repositories).length)
+            return;
+        const apiUrl = resolveApiUrl(undefined, ctx.io.env.SHARDFLUX_API_URL ?? ctx.io.env.SHARDFLUX_BASE_URL);
+        let cloud;
+        await housekeeping({ ...ctx, apiUrl, cloud: () => {
+                const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() || ctx.store.profile(apiUrl).api_key?.token;
+                if (!key)
+                    throw new UsageError('saved agents need a project key for housekeeping; run shard setup');
+                return cloud ??= new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
+            } });
+    }
+    catch (error) {
+        ctx.io.stderr.write(`shard housekeeping: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}

package/dist/agent-git.d.ts

@@ -0,0 +1,47 @@
+import { AgentStateStore } from './agent-state.js';
+export interface GitAgent {
+    workspace_id: string;
+    workspace_key: string;
+    remote_path: string;
+    api_url: string;
+    next_check: number;
+    archived_at?: number;
+    delete_pending?: boolean;
+    disposition?: 'merge' | 'keep' | 'discard';
+    branch?: string;
+}
+export interface GitRepository {
+    root: string;
+    agents: Record<string, GitAgent>;
+}
+export type GitRepositories = Record<string, GitRepository>;
+export type GitRun = (args: string[]) => Promise<string>;
+export declare function gitRunner(root: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): GitRun;
+export declare function agentName(name: string): string;
+export declare class AgentGit {
+    readonly root: string;
+    readonly common: string;
+    readonly store: AgentStateStore;
+    readonly run: GitRun;
+    readonly now: () => number;
+    constructor(root: string, common: string, store: AgentStateStore, run?: GitRun, now?: () => number);
+    static open(folder: string, store: AgentStateStore, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<AgentGit>;
+    repositories(): GitRepositories;
+    entries(): Record<string, GitAgent>;
+    save(name: string, entry?: GitAgent): void;
+    locked<T>(fn: () => Promise<T>): Promise<T>;
+    ref(name: string, archive?: boolean): string;
+    worktree(name: string): string;
+    oid(ref: string): Promise<string | undefined>;
+    track(name: string, entry: GitAgent): Promise<void>;
+    fetch(name: string, remote: string): Promise<void>;
+    assertCleanWorktree(name: string): Promise<void>;
+    assertOwnedWorktree(name: string): Promise<void>;
+    openWorktree(name: string): Promise<string>;
+    removeWorktree(name: string, force?: boolean): Promise<void>;
+    finish(name: string, action: 'merge' | 'keep' | 'discard', removeWorkspace: (entry: GitAgent) => Promise<void>, push?: (branch: string) => Promise<void>): Promise<{
+        branch?: string;
+    }>;
+    archive(name: string, archivedAt?: number): Promise<boolean>;
+    restore(name: string): Promise<string>;
+}

package/dist/agent-git.js

@@ -0,0 +1,285 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { UsageError } from "./errors.js";
+import { AgentStateStore } from "./agent-state.js";
+import { gitPath } from "./git-remote-helper.js";
+const execute = promisify(execFile);
+const DAY = 86_400_000;
+export function gitRunner(root, env = process.env, signal) {
+    return async (args) => {
+        const result = await execute('git', ['--no-pager', '-C', root, ...args], {
+            env: { ...env, PATH: gitPath(env), GIT_TERMINAL_PROMPT: '0', GIT_MERGE_AUTOEDIT: 'no' },
+            timeout: 120_000, maxBuffer: 4 * 1024 * 1024, signal,
+        });
+        return result.stdout.trim();
+    };
+}
+export function agentName(name) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(name) || name.includes('..') || name.endsWith('.') || name.endsWith('.lock') || name === 'archive')
+        throw new UsageError('agent name is not valid for a Git ref');
+    return name;
+}
+export class AgentGit {
+    root;
+    common;
+    store;
+    run;
+    now;
+    constructor(root, common, store, run = gitRunner(root), now = Date.now) {
+        this.root = root;
+        this.common = common;
+        this.store = store;
+        this.run = run;
+        this.now = now;
+    }
+    static async open(folder, store, env, signal) {
+        const run = gitRunner(folder, env, signal);
+        const root = realpathSync(await run(['rev-parse', '--show-toplevel']));
+        const common = realpathSync(resolve(folder, await run(['rev-parse', '--git-common-dir'])));
+        return new AgentGit(root, common, store, gitRunner(root, env, signal));
+    }
+    repositories() { return (this.store.read().git_repositories ?? {}); }
+    entries() { return this.repositories()[this.common]?.agents ?? {}; }
+    save(name, entry) {
+        this.store.update(state => {
+            const repos = (state.git_repositories ?? {});
+            const repo = repos[this.common] ?? { root: this.root, agents: {} };
+            if (entry)
+                repo.agents[name] = entry;
+            else
+                delete repo.agents[name];
+            if (Object.keys(repo.agents).length)
+                repos[this.common] = repo;
+            else
+                delete repos[this.common];
+            state.git_repositories = repos;
+        });
+    }
+    async locked(fn) {
+        const file = join(this.common, 'shard-agents.lock');
+        try {
+            writeFileSync(file, String(process.pid), { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const pid = Number(readFileSync(file, 'utf8'));
+            try {
+                process.kill(pid, 0);
+            }
+            catch (probe) {
+                if (probe.code === 'ESRCH') {
+                    rmSync(file);
+                    return this.locked(fn);
+                }
+            }
+            throw new UsageError('another shard Git action is running in this repository');
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            rmSync(file, { force: true });
+        }
+    }
+    ref(name, archive = false) { return `refs/shard/${archive ? 'archive/' : ''}${agentName(name)}`; }
+    worktree(name) { return join(this.repositories()[this.common]?.root ?? this.root, '.shard', 'worktrees', agentName(name)); }
+    async oid(ref) {
+        try {
+            return await this.run(['rev-parse', '--verify', `${ref}^{commit}`]);
+        }
+        catch (error) {
+            if (error.code === 128)
+                return undefined;
+            throw error;
+        }
+    }
+    async track(name, entry) {
+        agentName(name);
+        const prior = this.entries()[name];
+        if (prior?.archived_at || prior?.disposition || prior && prior.workspace_id !== entry.workspace_id)
+            throw new UsageError(`agent ${name} already has saved work; restore or discard it before reusing the name`);
+        const head = await this.oid('HEAD');
+        if (head && !await this.oid(this.ref(name)))
+            await this.run(['update-ref', this.ref(name), head]);
+        this.save(name, { ...prior, ...entry });
+    }
+    async fetch(name, remote) {
+        await this.run(['fetch', '--no-tags', '--no-write-fetch-head', remote, `+HEAD:${this.ref(name)}`]);
+        // Detached editor commits are also work. Keep them if they extend the fetched tip; refuse divergence.
+        const path = this.worktree(name);
+        if (existsSync(path)) {
+            const local = await this.run(['-C', path, 'rev-parse', 'HEAD']);
+            const fetched = await this.oid(this.ref(name));
+            if (local !== fetched) {
+                try {
+                    await this.run(['merge-base', '--is-ancestor', this.ref(name), local]);
+                }
+                catch {
+                    try {
+                        await this.run(['merge-base', '--is-ancestor', local, this.ref(name)]);
+                        return;
+                    }
+                    catch {
+                        throw new UsageError(`local editor and cloud work diverged for ${name}; merge or push the editor commits before finishing`);
+                    }
+                }
+                await this.run(['update-ref', this.ref(name), local]);
+            }
+        }
+    }
+    async assertCleanWorktree(name) {
+        const path = this.worktree(name);
+        if (existsSync(path))
+            await this.assertOwnedWorktree(name);
+        if (existsSync(path) && await this.run(['-C', path, 'status', '--porcelain', '--untracked-files=all']))
+            throw new UsageError(`local worktree ${path} has uncommitted files; commit or save them before cleanup`);
+    }
+    async assertOwnedWorktree(name) {
+        const path = this.worktree(name);
+        const common = realpathSync(resolve(path, await this.run(['-C', path, 'rev-parse', '--git-common-dir'])));
+        const registered = (await this.run(['worktree', 'list', '--porcelain'])).split('\n').includes(`worktree ${path}`);
+        if (common !== this.common || !registered)
+            throw new UsageError(`${path} is not this repository's managed worktree`);
+    }
+    async openWorktree(name) {
+        const path = this.worktree(name);
+        const excluded = join(this.common, 'info', 'exclude');
+        mkdirSync(dirname(excluded), { recursive: true });
+        const text = existsSync(excluded) ? readFileSync(excluded, 'utf8') : '';
+        if (!text.split('\n').some(line => line === '.shard/' || line === '/.shard/'))
+            writeFileSync(excluded, `${text}${text && !text.endsWith('\n') ? '\n' : ''}/.shard/\n`);
+        if (!existsSync(path)) {
+            mkdirSync(dirname(path), { recursive: true });
+            await this.run(['worktree', 'add', '--detach', path, this.ref(name)]);
+        }
+        else {
+            const listed = (await this.run(['worktree', 'list', '--porcelain'])).split('\n').includes(`worktree ${path}`);
+            if (!listed)
+                throw new UsageError(`${path} exists but is not this repository's worktree`);
+            const head = await this.run(['-C', path, 'rev-parse', 'HEAD']);
+            const tip = await this.oid(this.ref(name));
+            if (head !== tip) {
+                await this.assertCleanWorktree(name);
+                await this.run(['merge-base', '--is-ancestor', head, this.ref(name)]);
+                await this.run(['-C', path, 'reset', '--hard', this.ref(name)]);
+            }
+        }
+        return path;
+    }
+    async removeWorktree(name, force = false) {
+        const path = this.worktree(name);
+        if (existsSync(path)) {
+            await this.assertOwnedWorktree(name);
+            await this.run(['worktree', 'remove', ...(force ? ['--force'] : []), path]);
+        }
+        await this.run(['worktree', 'prune']);
+    }
+    async finish(name, action, removeWorkspace, push) {
+        const entry = this.entries()[name];
+        if (!entry)
+            throw new UsageError(`no saved agent ${name}`);
+        if (entry.disposition && entry.disposition !== action)
+            throw new UsageError(`agent ${name} has a pending ${entry.disposition}; repeat that command to finish cleanup`);
+        if (action !== 'discard')
+            await this.assertCleanWorktree(name);
+        else if (existsSync(this.worktree(name)))
+            await this.assertOwnedWorktree(name);
+        let branch = entry.branch;
+        if (!entry.disposition) {
+            if (action === 'merge') {
+                const current = await this.run(['symbolic-ref', '--quiet', 'HEAD']).catch(() => '');
+                if (!current)
+                    throw new UsageError('merge requires a current local branch');
+                if (await this.run(['status', '--porcelain', '--untracked-files=all']))
+                    throw new UsageError('commit or stash local changes before merging an agent');
+                try {
+                    await this.run(['merge', '--no-edit', this.ref(name)]);
+                }
+                catch (error) {
+                    throw new UsageError(`agent merge stopped: ${error instanceof Error ? error.message : String(error)}\nResolve with normal Git commands or git merge --abort. The agent, hidden ref and worktree are preserved.`);
+                }
+            }
+            else if (action === 'keep') {
+                branch = `shard/${agentName(name)}`;
+                const existing = await this.oid(`refs/heads/${branch}`);
+                const head = await this.oid(this.ref(name));
+                if (!head)
+                    throw new UsageError(`agent ${name} has no fetched commit`);
+                if (existing && existing !== head)
+                    throw new UsageError(`branch ${branch} already exists with different work`);
+                if (!existing)
+                    await this.run(['branch', branch, this.ref(name)]);
+            }
+            this.save(name, { ...entry, disposition: action, ...(branch ? { branch } : {}) });
+        }
+        if (push && branch)
+            await push(branch);
+        await removeWorkspace(this.entries()[name]);
+        await this.removeWorktree(name, action === 'discard');
+        await this.run(['update-ref', '-d', this.ref(name)]);
+        await this.run(['update-ref', '-d', this.ref(name, true)]);
+        this.save(name);
+        return branch ? { branch } : {};
+    }
+    async archive(name, archivedAt = this.now()) {
+        const entry = this.entries()[name];
+        if (!entry)
+            return false;
+        await this.assertCleanWorktree(name);
+        let head = await this.oid(this.ref(name));
+        if (existsSync(this.worktree(name))) {
+            const local = await this.run(['-C', this.worktree(name), 'rev-parse', 'HEAD']);
+            if (!head)
+                head = local;
+            else if (local !== head) {
+                try {
+                    await this.run(['merge-base', '--is-ancestor', head, local]);
+                    head = local;
+                }
+                catch {
+                    try {
+                        await this.run(['merge-base', '--is-ancestor', local, head]);
+                    }
+                    catch {
+                        throw new UsageError(`local editor and saved cloud work diverged for ${name}; preserve both before archiving`);
+                    }
+                }
+            }
+        }
+        if (!head) {
+            await this.removeWorktree(name);
+            await this.run(['update-ref', '-d', this.ref(name)]);
+            this.save(name);
+            return false;
+        }
+        await this.run(['update-ref', this.ref(name, true), head]);
+        // Persist the timestamp before removing the active ref; a crash never restarts the 30-day clock.
+        this.save(name, { ...entry, archived_at: archivedAt, next_check: this.now() });
+        await this.removeWorktree(name);
+        await this.run(['update-ref', '-d', this.ref(name)]);
+        this.save(name, { ...entry, archived_at: archivedAt, next_check: archivedAt + 30 * DAY });
+        return true;
+    }
+    async restore(name) {
+        const entry = this.entries()[name];
+        if (entry?.delete_pending)
+            throw new UsageError(`agent ${name} still has workspace deletion pending; run shard again to finish housekeeping`);
+        if (entry?.archived_at === undefined || this.now() >= entry.archived_at + 30 * DAY)
+            throw new UsageError(`agent ${name} has no archive within the 30-day restore window`);
+        const head = await this.oid(this.ref(name, true));
+        if (!head)
+            throw new UsageError(`archive ${name} has no saved commit`);
+        const branch = `shard/${agentName(name)}`;
+        const existing = await this.oid(`refs/heads/${branch}`);
+        if (existing && existing !== head)
+            throw new UsageError(`branch ${branch} already exists with different work`);
+        if (!existing)
+            await this.run(['branch', branch, head]);
+        await this.run(['update-ref', '-d', this.ref(name, true)]);
+        this.save(name);
+        return branch;
+    }
+}

package/dist/agent-reachability.d.ts

@@ -0,0 +1,4 @@
+import type { Values } from './args.js';
+export declare function agentReachability(values: Values): {
+    agentReachableSeconds?: number;
+};

package/dist/agent-reachability.js

@@ -0,0 +1,13 @@
+import { parseDuration } from "./args.js";
+import { UsageError } from "./errors.js";
+export function agentReachability(values) {
+    const text = values.reachable;
+    if (text === undefined)
+        return {};
+    if (typeof text !== 'string')
+        throw new UsageError('--reachable requires a duration');
+    const ms = /^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()) ? 0 : parseDuration(text, 'reachable');
+    if (ms % 1000 !== 0 || ms > 86_400_000)
+        throw new UsageError('--reachable must be whole seconds from 0 to 24h (e.g. 30m; 0 off)');
+    return { agentReachableSeconds: ms / 1000 };
+}

package/dist/agent-repository.d.ts

@@ -0,0 +1,13 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare function projectWorkspacePath(project: {
+    slug: string;
+}): string;
+/** New workspaces label this path explicitly; custom remote paths remain available to Git callers. */
+export declare function workspaceRepositoryPath(ws: Pick<Workspace, 'labels' | 'key'>): string;
+export declare function needsGitSeed(ctx: Ctx, ws: Workspace): boolean;
+/** One history seed for C5 and C11. Bundles use the bounded files path, without a Git helper or second connection. */
+export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: string, options?: {
+    root?: string;
+    populate?: boolean;
+}): Promise<void>;