@shardflux/cli 0.11.1 → 0.13.1

package/dist/agent-config-sync.js

@@ -0,0 +1,366 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parse, stringify } from 'smol-toml';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { UsageError } from "./errors.js";
+import { collectPlugins, collectUserFiles, object, readObject, readOptional, rewritePaths } from "./agent-config-files.js";
+import { digest, prepareMcp } from "./agent-config-mcp.js";
+const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+const markerPath = '.config/shardflux/agent-config.json';
+const safePath = (path) => !path.split('/').some(p => !p || p === '.' || p === '..') &&
+    (/^(?:\.claude\/(?:settings\.json|CLAUDE\.md)|\.codex\/(?:config\.toml|AGENTS\.md))$/.test(path) ||
+        /^\.claude\/(?:skills|commands|agents|output-styles|plugins)\/.+/.test(path) || /^\.codex\/(?:prompts|skills)\/.+/.test(path));
+const key = (ctx, id) => `${ctx.apiUrl}:${id}`;
+export function configManifests(ctx) {
+    const value = object(new AgentStateStore(ctx.store.dir).read().agent_config);
+    for (const [id, raw] of Object.entries(value)) {
+        const m = object(raw);
+        if (m.v !== 1 || typeof m.workspace_id !== 'string' || typeof m.api_url !== 'string' || !Array.isArray(m.mcp) || !Array.isArray(m.skipped))
+            throw new UsageError(`invalid agent config manifest ${id}; preserve agents.json and re-run config sync after repairing it`);
+    }
+    return value;
+}
+/** `like` must not inherit generated MCP secrets restricted to the source workspace. */
+export async function agentConfigLikeSecrets(ctx, reference) {
+    const cloud = ctx.cloud();
+    const source = await cloud.workspaces.findByKey(reference, { includeDeleted: false, signal: ctx.signal }) ?? await cloud.workspaces.get(reference);
+    if (!source.labels.shard_project)
+        return undefined;
+    const bindings = await source.secrets.get();
+    const names = bindings.names.filter(name => !/^SF_MCP_[0-9A-F]{24}$/.test(name));
+    return names.length === bindings.names.length ? undefined : names;
+}
+async function optionalRemote(cell, path) {
+    try {
+        const value = JSON.parse(await cell.files.readText(path));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`invalid remote config ${path}`);
+        return value;
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Scope and consent are workspace-specific; never reuse an unrelated project secret with the same name. */
+async function bindMcpSecret(ctx, ws, secrets, spec) {
+    ctx.addSecret(spec.value);
+    const hash = digest(spec.value);
+    const previous = secrets[spec.name];
+    if (previous?.hash === hash) {
+        const current = await ctx.cloud().secrets.get(previous.id);
+        if (!current.deleted_at && current.name === spec.name && current.current_version === previous.version && current.permissions.allowed_workspace_ids?.length === 1 && current.permissions.allowed_workspace_ids[0] === ws.id &&
+            current.permissions.allowed_tools.length === 2 && current.permissions.allowed_tools.includes('exec') && current.permissions.allowed_tools.includes('pty')) {
+            const bindings = await ws.secrets.get();
+            if (!bindings.names.includes(spec.name))
+                await ws.secrets.set([...bindings.names, spec.name]);
+            return true;
+        }
+    }
+    if (!ctx.input.interactive)
+        return false;
+    const answer = await ctx.input.answer(`Store ${spec.item} as a Shardflux secret for ${ws.key}? [y/N] `);
+    if (!/^y(?:es)?$/i.test(answer?.trim() ?? ''))
+        return false;
+    let id;
+    let version;
+    if (previous) {
+        const metadata = await ctx.cloud().secrets.get(previous.id);
+        if (metadata.deleted_at || metadata.name !== spec.name || metadata.permissions.allowed_workspace_ids?.length !== 1 || metadata.permissions.allowed_workspace_ids[0] !== ws.id)
+            throw new Error(`MCP secret ${spec.name} no longer has its original workspace scope`);
+        const rotated = (await ctx.cloud().secrets.rotate(previous.id, spec.value)).secret;
+        id = rotated.id;
+        version = rotated.current_version;
+    }
+    else {
+        const created = await ctx.cloud().secrets.create(ws.data.project_id, { name: spec.name, value: spec.value,
+            description: 'Agent config MCP credential', allowedWorkspaceIds: [ws.id], allowedTools: ['exec', 'pty'] });
+        id = created.id;
+        version = created.current_version;
+    }
+    if (!Number.isInteger(version) || version < 1)
+        throw new Error('MCP secret response omitted its current version');
+    const bindings = await ws.secrets.get();
+    if (!bindings.names.includes(spec.name))
+        await ws.secrets.set([...bindings.names, spec.name]);
+    secrets[spec.name] = { id, hash, version };
+    // Persist consent immediately: a later file failure must not lose the secret's identity.
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const all = object(doc.agent_config_secrets);
+        all[key(ctx, ws.id)] = { ...object(all[key(ctx, ws.id)]), [spec.name]: { id, hash, version } };
+        doc.agent_config_secrets = all;
+    });
+    ctx.io.stderr.write(`MCP secret bound to ${ws.key}; an already running agent picks it up when restarted.\n`);
+    return true;
+}
+export async function applyConfigFiles(cell, home, files, previous, trustManifest, issues, signal, deleteMissing = true, progress = () => { }) {
+    const next = {};
+    const copied = [], removed = [];
+    for (const [path, file] of files) {
+        signal.throwIfAborted();
+        if (!safePath(path))
+            throw new Error('agent config attempted to write outside its allowlist');
+        const hash = digest(file.content);
+        const old = previous[path];
+        if (trustManifest && old?.hash === hash && old.mode === file.mode) {
+            next[path] = old;
+            continue;
+        }
+        let exists = false, same = false;
+        try {
+            const info = await cell.files.stat(`${home}/${path}`, { revision: true });
+            exists = true;
+            same = info.revision === hash && info.mode === file.mode;
+            if (info.type !== 'file') {
+                issues.push({ item: path, reason: 'remote path is not a regular file' });
+                continue;
+            }
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        if (!same) {
+            await cell.files.write(`${home}/${path}`, file.content, { createParents: true, mode: file.mode });
+            copied.push(path);
+        }
+        next[path] = { hash, mode: file.mode, created: old?.created ?? !exists };
+        progress(path, next[path]);
+    }
+    for (const [path, old] of Object.entries(deleteMissing ? previous : {})) {
+        signal.throwIfAborted();
+        if (files.has(path))
+            continue;
+        if (!safePath(path))
+            throw new Error('agent config manifest contains a path outside its allowlist');
+        if (!old.created)
+            continue;
+        try {
+            const info = await cell.files.stat(`${home}/${path}`, { revision: true });
+            if (info.type !== 'file' || info.revision !== old.hash) {
+                issues.push({ item: path, reason: 'remote file was changed; deletion preserved it' });
+                continue;
+            }
+            await cell.files.remove(`${home}/${path}`);
+            removed.push(path);
+            progress(path, undefined);
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+    }
+    return { files: next, copied, removed };
+}
+export async function syncAgentConfig(ctx, ws) {
+    const home = ctx.io.env.HOME || homedir();
+    const store = new AgentStateStore(ctx.store.dir);
+    const previous = configManifests(ctx)[key(ctx, ws.id)];
+    const issues = [];
+    const files = await collectUserFiles(home, issues);
+    const codexBytes = await readOptional(join(home, '.codex/config.toml'));
+    const claude = await readObject(join(home, '.claude.json'));
+    const hasPlugins = await readOptional(join(home, '.claude/plugins/installed_plugins.json')) || await readOptional(join(home, '.claude/plugins/known_marketplaces.json'));
+    const empty = { workspace_id: ws.id, workspace_key: ws.key, copied: [], removed: [], skipped: issues, mcp: [], synced_at: null };
+    if (!files.size && !codexBytes && !hasPlugins && !Object.keys(object(claude?.mcpServers)).length && !previous)
+        return empty;
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const run = await cell.exec.run(['sh', '-c', 'printf "%s\\n" "$HOME"'], { signal: ctx.signal, timeoutMs: 5000, maxOutputBytes: 4096 });
+    const remoteHome = run.stdout.trim();
+    if (run.exitCode !== 0 || !/^\/(?:[a-zA-Z0-9._-]+\/)*[a-zA-Z0-9._-]+$/.test(remoteHome) || remoteHome.split('/').some(p => p === '..' || p === '.'))
+        throw new Error('agent config could not resolve the VM user home');
+    const skippedPlugins = await collectPlugins(home, remoteHome, files, issues);
+    if (skippedPlugins.size && files.has('.claude/settings.json')) {
+        const file = files.get('.claude/settings.json');
+        const settings = object(JSON.parse(file.content.toString('utf8')));
+        const enabled = object(settings.enabledPlugins);
+        for (const id of skippedPlugins)
+            if (id in enabled)
+                enabled[id] = false;
+        settings.enabledPlugins = enabled;
+        file.content = Buffer.from(JSON.stringify(settings) + '\n');
+    }
+    // Claude settings stay the user's. sf-agent hooks are in /etc/claude-code/managed-settings.json.
+    const secrets = { ...previous?.secrets, ...object(object(store.read().agent_config_secrets)[key(ctx, ws.id)]) };
+    const commandCache = new Map();
+    const exists = async (command) => {
+        if (!commandCache.has(command)) {
+            if (!command || command.includes('\0'))
+                return false;
+            const probe = await cell.exec.run(['sh', '-c', 'command -v -- "$1" >/dev/null 2>&1', 'shard-config', command], { signal: ctx.signal, timeoutMs: 5000, maxOutputBytes: 4096 });
+            commandCache.set(command, probe.exitCode === 0);
+        }
+        return commandCache.get(command);
+    };
+    const mcp = [], tunnels = [];
+    const synced_at = new Date().toISOString();
+    const partial = { v: 1, workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl, home: remoteHome,
+        sync_state: 'applying', remote_hash: previous?.remote_hash, synced_at: previous?.synced_at ?? null, files: { ...previous?.files },
+        claude_mcp: previous?.claude_mcp ?? [], claude_mcp_owned: previous?.claude_mcp_owned, secrets, skipped: issues, mcp: previous?.mcp ?? [], tunnels: previous?.tunnels ?? [] };
+    const savePartial = (path, file) => {
+        if (file)
+            partial.files[path] = file;
+        else
+            delete partial.files[path];
+        store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = partial; doc.agent_config = all; });
+    };
+    const marker = await optionalRemote(cell, `${remoteHome}/${markerPath}`);
+    const trust = marker?.workspace_id === ws.id && typeof previous?.remote_hash === 'string' && marker.manifest_hash === previous.remote_hash;
+    // Stage executable payloads before checking stdio paths. Structured configuration is prepared before transfer.
+    const payload = new Map([...files].filter(([path]) => !/\.(?:json|toml)$/.test(path) && path !== '.claude/settings.json'));
+    const staged = await applyConfigFiles(cell, remoteHome, payload, previous?.files ?? {}, trust, issues, ctx.signal, false, savePartial);
+    const mcpCtx = { home, remoteHome, workspaceId: ws.id, files, issues, env: ctx.io.env, exists, bind: (secret) => bindMcpSecret(ctx, ws, secrets, secret) };
+    // Installed plugins can declare MCP servers inline or in .mcp.json. Treat their env exactly like user MCP env.
+    for (const [path, file] of files) {
+        if (!path.startsWith('.claude/plugins/cache/') || !(path.endsWith('/.mcp.json') || path.endsWith('/.claude-plugin/plugin.json')))
+            continue;
+        const doc = object(JSON.parse(file.content.toString('utf8')));
+        const isManifest = path.endsWith('/plugin.json');
+        const inline = doc.mcpServers;
+        if (isManifest && (typeof inline === 'string' || Array.isArray(inline)))
+            continue; // Referenced .mcp.json files are handled in this same pass.
+        const servers = isManifest || inline ? object(inline) : doc;
+        if (!Object.keys(servers).length)
+            continue;
+        const root = `${remoteHome}/${path.slice(0, path.lastIndexOf(isManifest ? '/.claude-plugin/' : '/'))}`;
+        const pluginCtx = { ...mcpCtx, namespace: path, exists: (command) => exists(command.replaceAll('${CLAUDE_PLUGIN_ROOT}', root)) };
+        const portable = await prepareMcp('claude', servers, pluginCtx, mcp, tunnels);
+        file.content = Buffer.from(JSON.stringify(isManifest || inline ? { ...doc, mcpServers: portable } : portable) + '\n');
+    }
+    const claudeMcp = await prepareMcp('claude', object(claude?.mcpServers), mcpCtx, mcp, tunnels);
+    if (codexBytes) {
+        const config = parse(codexBytes.toString('utf8'));
+        const servers = await prepareMcp('codex', object(config.mcp_servers), mcpCtx, mcp, tunnels);
+        delete config.mcp_servers;
+        const portable = object(rewritePaths(config, home, remoteHome, files, issues, 'codex:config'));
+        if (Object.keys(servers).length || 'mcp_servers' in parse(codexBytes.toString('utf8')))
+            portable.mcp_servers = servers;
+        files.set('.codex/config.toml', { content: Buffer.from(stringify(portable)), mode: '0600' });
+    }
+    // Retain encrypted secret records for later re-use, but stop injecting credentials for removed/skipped servers.
+    const ownedSecrets = Object.keys(secrets);
+    if (ownedSecrets.length) {
+        const references = JSON.stringify(claudeMcp) + [...files.values()].map(f => f.content.toString('utf8')).join('\n');
+        const unused = new Set(ownedSecrets.filter(name => !references.includes(name)));
+        if (unused.size) {
+            const bindings = await ws.secrets.get();
+            const names = bindings.names.filter(name => !unused.has(name));
+            if (names.length !== bindings.names.length)
+                await ws.secrets.set(names);
+        }
+    }
+    const applied = await applyConfigFiles(cell, remoteHome, files, partial.files, trust, issues, ctx.signal, true, savePartial);
+    applied.copied.unshift(...staged.copied);
+    // L2 owns oauthAccount and credentials. Patch just mcpServers under a revision check; preserve every other field.
+    if (Object.keys(claudeMcp).length || previous?.claude_mcp.length) {
+        const path = `${remoteHome}/.claude.json`;
+        let document = {}, revision = 'absent';
+        try {
+            const info = await cell.files.readWithInfo(path);
+            const parsed = JSON.parse(Buffer.from(info.data).toString('utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('Claude config is not an object; refusing an unsafe merge');
+            document = parsed;
+            if (!info.revision)
+                throw new Error('Claude config has no content revision; refusing an unsafe merge');
+            revision = info.revision;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const merged = { ...object(document.mcpServers) };
+        for (const name of previous?.claude_mcp ?? []) {
+            if (name in claudeMcp)
+                continue;
+            const old = previous?.claude_mcp_owned?.[name];
+            if (name in merged && old?.created && digest(JSON.stringify(merged[name])) === old.hash)
+                delete merged[name];
+            else if (name in merged)
+                issues.push({ item: `claude:mcp:${name}`, reason: 'remote MCP entry was pre-existing or changed; removal preserved it' });
+        }
+        const owned = {};
+        for (const [name, value] of Object.entries(claudeMcp))
+            owned[name] = { hash: digest(JSON.stringify(value)), created: previous?.claude_mcp_owned?.[name]?.created ?? !(name in merged) };
+        partial.claude_mcp_owned = owned;
+        Object.assign(merged, claudeMcp);
+        const content = JSON.stringify({ ...document, mcpServers: merged }) + '\n';
+        if (digest(content) !== revision) {
+            await cell.files.patch({ path, content, expectedRevision: revision, createParents: true, mode: '0600' }, { signal: ctx.signal });
+            applied.copied.push('.claude.json:mcpServers');
+        }
+        partial.claude_mcp = Object.keys(claudeMcp);
+        store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = partial; doc.agent_config = all; });
+    }
+    const manifest = { v: 1, workspace_id: ws.id, workspace_key: ws.key, api_url: ctx.apiUrl, home: remoteHome,
+        sync_state: 'synced', synced_at, files: applied.files, claude_mcp: Object.keys(claudeMcp), claude_mcp_owned: partial.claude_mcp_owned, secrets, skipped: issues, mcp, tunnels };
+    manifest.remote_hash = digest(JSON.stringify({ files: applied.files, claude_mcp: claudeMcp, mcp, tunnels }));
+    if (marker?.workspace_id !== ws.id || marker.manifest_hash !== manifest.remote_hash)
+        await cell.files.write(`${remoteHome}/${markerPath}`, JSON.stringify({ workspace_id: ws.id, manifest_hash: manifest.remote_hash }) + '\n', { createParents: true, mode: '0600' });
+    store.update(doc => { const all = object(doc.agent_config); all[key(ctx, ws.id)] = manifest; doc.agent_config = all; });
+    const result = { ...empty, copied: applied.copied, removed: applied.removed, skipped: issues, mcp, synced_at };
+    if (!ctx.json) {
+        for (const issue of issues)
+            ctx.io.stderr.write(`Config skipped ${issue.item}: ${issue.reason}\n`);
+        for (const server of mcp)
+            if (server.status !== 'copied')
+                ctx.io.stderr.write(`MCP ${server.app}/${server.name}: ${server.status}${server.reason ? ` (${server.reason})` : ''}\n`);
+    }
+    return result;
+}
+/** Tunnels are owned by the attachment, and close even if the terminal fails or the user detaches. */
+export async function startAgentConfigTunnels(ctx, ws) {
+    const owned = [];
+    const tunnels = configManifests(ctx)[key(ctx, ws.id)]?.tunnels ?? [];
+    const stop = async () => {
+        const closed = await Promise.allSettled(owned.map(t => t.close()));
+        const failure = closed.find(r => r.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+    };
+    try {
+        for (const tunnel of tunnels) {
+            const handle = await ws.tunnels.reverse({ remotePort: tunnel.remote_port, target: tunnel.target, bindAddress: '127.0.0.1', signal: ctx.signal });
+            // A failed tunnel is shown immediately; its rejection must never become an unhandled promise.
+            void handle.closed.catch(() => { ctx.io.stderr.write(`MCP tunnel to ${tunnel.target} closed; attach again to reconnect.\n`); });
+            owned.push(handle);
+        }
+        return { stop };
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+}
+export const AGENT_CONFIG_HANDLERS = {
+    'agents config status'(ctx, values) {
+        const workspace = typeof values.workspace === 'string' ? values.workspace : undefined;
+        const manifests = Object.values(configManifests(ctx)).filter(m => m.api_url === ctx.apiUrl && (!workspace || m.workspace_id === workspace || m.workspace_key === workspace));
+        const report = { observation: 'last sync on this machine', workspaces: manifests };
+        ctx.io.stdout.write(ctx.json ? JSON.stringify(report, null, 2) + '\n' : manifests.length ? manifests.map(m => `${m.workspace_key}: ${Object.keys(m.files).length} files; ${m.sync_state === 'synced' ? `last sync ${m.synced_at}` : 'sync interrupted; run config sync again'}\n` +
+            m.skipped.map(s => `  skipped ${s.item}: ${s.reason}\n`).join('') +
+            m.mcp.map(s => `  MCP ${s.app}/${s.name}: ${s.status}${s.reason ? ` (${s.reason})` : ''}\n`).join('')).join('') : 'No agent config has been synced on this machine.\n');
+        return Promise.resolve(0);
+    },
+    async 'agents config sync'(ctx, values) {
+        const workspace = typeof values.workspace === 'string' ? values.workspace : undefined;
+        const cloud = ctx.cloud();
+        const targets = [];
+        if (workspace) {
+            const ws = await cloud.workspaces.findByKey(workspace, { includeDeleted: false, signal: ctx.signal });
+            targets.push(ws ?? await cloud.workspaces.get(workspace));
+        }
+        else
+            for await (const ws of cloud.workspaces.listAll()) {
+                if (ws.labels.shard_project && ws.mode === 'processful')
+                    targets.push(ws);
+            }
+        const results = [];
+        for (const ws of targets)
+            results.push(await syncAgentConfig(ctx, ws));
+        ctx.io.stdout.write(ctx.json ? JSON.stringify({ workspaces: results }, null, 2) + '\n' : results.length ? results.map(r => r.synced_at === null ? `${r.workspace_key}: no local agent config found\n` : `${r.workspace_key}: ${r.copied.length} files copied, ${r.removed.length} removed\n`).join('') : 'No agent workspaces found.\n');
+        return 0;
+    },
+};

package/dist/agent-credentials.d.ts

@@ -0,0 +1,14 @@
+import type { AgentCredentialApp, AgentCredentialFile, Shardflux } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+export interface CredentialSources {
+    home?: string;
+    redact?: (value: string) => void;
+}
+/** Codex copies refresh independently. Claude uses its account's cloud login. */
+export declare function readAgentCredentials(opts?: CredentialSources): Promise<Array<{
+    app: AgentCredentialApp;
+    files: AgentCredentialFile[];
+}>>;
+/** Reusable by the path launcher (L4). Returns metadata only. */
+export declare function syncAgentCredentials(cloud: Shardflux, opts?: CredentialSources): Promise<import("@shardflux/sdk").AgentCredentialMetadata[]>;
+export declare const AGENT_CREDENTIAL_HANDLERS: Record<string, Handler>;

package/dist/agent-credentials.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { json } from "./format.js";
+import { UsageError } from "./errors.js";
+import { loginClaudeInWorkspace, requireClaudeTerminal, cloudClaudeLogin } from "./claude-cloud-login.js";
+import { resolveWorkspace } from "./commands.js";
+import { projectIdentity, projectLabels } from "./project-identity.js";
+async function optionalFile(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw new UsageError('Could not read local agent credentials.');
+    }
+}
+function object(raw, redact) {
+    redact?.(raw);
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError('Local agent credentials contain invalid JSON.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new UsageError('Local agent credentials must be a JSON object.');
+    const hide = (v) => {
+        if (typeof v === 'string')
+            redact?.(v);
+        else if (Array.isArray(v))
+            v.forEach(hide);
+        else if (v && typeof v === 'object')
+            Object.values(v).forEach(hide);
+    };
+    hide(value);
+    return value;
+}
+function file(path, value, redact) {
+    const content = JSON.stringify(value);
+    const content_b64 = Buffer.from(content).toString('base64');
+    redact?.(content);
+    redact?.(content_b64);
+    return { path, content_b64, mode: '0600' };
+}
+/** Codex copies refresh independently. Claude uses its account's cloud login. */
+export async function readAgentCredentials(opts = {}) {
+    const home = opts.home ?? homedir();
+    const out = [];
+    const codex = await optionalFile(join(home, '.codex', 'auth.json'));
+    if (codex)
+        out.push({ app: 'codex', files: [file('~/.codex/auth.json', object(codex, opts.redact), opts.redact)] });
+    return out;
+}
+/** Reusable by the path launcher (L4). Returns metadata only. */
+export async function syncAgentCredentials(cloud, opts = {}) {
+    const sessions = await readAgentCredentials(opts);
+    const metadata = [];
+    for (const session of sessions)
+        metadata.push(await cloud.agentCredentials.put(session.app, session.files));
+    return metadata;
+}
+function output(ctx, value) {
+    ctx.io.stdout.write(ctx.json ? json(value) : `${JSON.stringify(value, null, 2)}\n`);
+}
+export const AGENT_CREDENTIAL_HANDLERS = {
+    'agents credentials login': async (ctx, values, [app]) => {
+        if (app !== 'claude')
+            throw new UsageError('Cloud sign-in supports claude; use agents credentials sync for Codex.');
+        const existing = await cloudClaudeLogin(ctx);
+        if (existing) {
+            output(ctx, existing);
+            return 0;
+        }
+        requireClaudeTerminal(ctx);
+        const project = projectIdentity('./');
+        const ws = typeof values.workspace === 'string' ? await resolveWorkspace(ctx, values.workspace)
+            : await ctx.cloud().workspaces.open({ key: `${project.slug}/main`, template: 'coding', labels: projectLabels(project, 'main', 'claude'), wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        output(ctx, await loginClaudeInWorkspace(ctx, ws));
+        return 0;
+    },
+    'agents credentials sync': async (ctx) => { output(ctx, await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME ?? ctx.io.env.USERPROFILE, redact: (value) => ctx.addSecret(value) })); return 0; },
+    'agents credentials status': async (ctx) => { output(ctx, await ctx.cloud().agentCredentials.list()); return 0; },
+    'agents credentials forget': async (ctx) => {
+        const cloud = ctx.cloud();
+        for (const app of ['claude', 'codex'])
+            await cloud.agentCredentials.forget(app);
+        output(ctx, { forgotten: ['claude', 'codex'] });
+        return 0;
+    },
+};

package/dist/agent-git-commands.d.ts

@@ -0,0 +1,10 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+type HousekeepingCtx = Pick<Ctx, 'io' | 'apiUrl' | 'signal' | 'store' | 'cloud'>;
+export { needsGitSeed, seedAgentRepository } from './agent-repository.js';
+export declare function rememberGitAgent(ctx: Ctx, ws: Workspace, folder: string): Promise<void>;
+export declare const AGENT_GIT_HANDLERS: Record<string, Handler>;
+/** No Git or network work when no records are due. Active passes are bounded and never infer deletion from an error. */
+export declare function housekeeping(ctx: HousekeepingCtx, now?: () => number, budgetMs?: number): Promise<void>;
+/** Help/version starts also clean saved work, without requiring credentials when nothing is due. */
+export declare function startupHousekeeping(ctx: Pick<Ctx, 'io' | 'store' | 'signal'>): Promise<void>;