@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/updater.d.ts

@@ -0,0 +1,15 @@
+export declare function installedSdkVersion(): string;
+export declare const updatesEnabled: () => boolean;
+/** A version waiting for the next start, or '' when none. */
+export declare function pendingUpdate(): string;
+/**
+ * Look for a newer, old-enough release of the same minor and warm the cache for it. Returns the
+ * version now waiting for a restart, or '' when there is nothing new. Never throws: an offline
+ * machine just stays where it is.
+ */
+export declare function checkAndStage(): Promise<string>;
+/**
+ * Called by the launcher before anything is loaded. Installs what was downloaded; on any
+ * failure puts the previous version back and never offers that release again.
+ */
+export declare function applyPendingUpdate(): string;

package/dist/updater.js

@@ -0,0 +1,178 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Keeps the Claude Agent SDK current, the way Claude Code keeps itself current: fetch the new
+ * version in the background, say so in the pane, and switch to it on the next start.
+ *
+ * Never swapped under a running process. The SDK spawns its bundled CLI for every query, so
+ * replacing files mid-run would pair an old wrapper with a new binary. The download only warms
+ * npm's cache and records what is waiting; the launcher installs it before anything is loaded.
+ *
+ * Narrow on purpose: the same 0.minor only (in 0.x the minor is the breaking-change signal),
+ * releases at least two days old (time for a bad or hijacked one to be pulled), a post-install
+ * check, and a rollback that remembers the version it rejected.
+ */
+const PKG = '@anthropic-ai/claude-agent-sdk';
+const MIN_AGE_MS = 2 * 24 * 60 * 60 * 1000;
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const stateFile = () => join(process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config'), 'flaredeck-agent', 'update.json');
+function load() {
+    try {
+        return existsSync(stateFile()) ? JSON.parse(readFileSync(stateFile(), 'utf8')) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function save(s) {
+    mkdirSync(dirname(stateFile()), { recursive: true });
+    writeFileSync(stateFile(), `${JSON.stringify(s, null, 2)}\n`);
+}
+/** The preload in some shells breaks npm; the child never needs it. */
+const childEnv = () => {
+    const env = { ...process.env };
+    delete env['NODE_OPTIONS'];
+    return env;
+};
+export function installedSdkVersion() {
+    try {
+        return JSON.parse(readFileSync(join(ROOT, 'node_modules', PKG, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '';
+    }
+}
+export const updatesEnabled = () => process.env['FLAREDECK_AGENT_NO_UPDATE'] !== '1';
+/** A version waiting for the next start, or '' when none. */
+export function pendingUpdate() {
+    const v = load().pending?.version ?? '';
+    return v && v !== installedSdkVersion() ? v : '';
+}
+const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+function run(args, timeout) {
+    return new Promise((ok, fail) => execFile('npm', args, { cwd: ROOT, env: childEnv(), timeout }, (err) => (err ? fail(err) : ok())));
+}
+/**
+ * Look for a newer, old-enough release of the same minor and warm the cache for it. Returns the
+ * version now waiting for a restart, or '' when there is nothing new. Never throws: an offline
+ * machine just stays where it is.
+ */
+export async function checkAndStage() {
+    if (!updatesEnabled())
+        return '';
+    try {
+        const state = load();
+        const current = installedSdkVersion();
+        const cur = parse(current);
+        if (!cur)
+            return '';
+        const res = await fetch(`https://registry.npmjs.org/${PKG}`, { signal: AbortSignal.timeout(30_000) });
+        if (!res.ok)
+            return '';
+        const doc = (await res.json());
+        const best = Object.keys(doc.versions ?? {})
+            .filter((v) => !state.bad?.includes(v))
+            .map((v) => ({ v, p: parse(v), at: Date.parse(doc.time?.[v] ?? '') }))
+            .filter((x) => !!x.p && Number.isFinite(x.at))
+            .filter((x) => x.p[0] === cur[0] && x.p[1] === cur[1] && x.p[2] > cur[2] && Date.now() - x.at >= MIN_AGE_MS)
+            .sort((a, b) => b.p[2] - a.p[2])[0];
+        state.lastCheck = Date.now();
+        if (!best) {
+            save(state);
+            return state.pending && state.pending.version !== current ? state.pending.version : '';
+        }
+        if (state.pending?.version !== best.v) {
+            await run(['cache', 'add', `${PKG}@${best.v}`], 120_000);
+            state.pending = { version: best.v, at: Date.now() };
+        }
+        save(state);
+        return best.v;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Install `version` here, then prove the SDK still loads, still has what the harness uses, AND can
+ * still start its CLI.
+ *
+ * That last check is not belt-and-braces. From 0.3.289 the SDK ships its CLI as a per-platform
+ * OPTIONAL dependency (`@anthropic-ai/claude-agent-sdk-darwin-arm64` and friends) instead of
+ * vendoring it. An optional dependency that fails to install is not an npm error — it is silently
+ * skipped — and the JS half still imports perfectly, so `query`/`tool`/`createSdkMcpServer` are all
+ * functions and the old check passed. The agent then came up looking healthy and died on the first
+ * question with "Native CLI binary for darwin-arm64 not found", which no rollback caught because
+ * nothing had failed yet.
+ *
+ * So: ask for optional dependencies explicitly, and verify by RUNNING the binary.
+ */
+function installAndVerify(version) {
+    try {
+        execFileSync('npm', [
+            'install',
+            '--no-save',
+            '--no-audit',
+            '--no-fund',
+            // The platform binary is only ever an optional dep; never let npm skip it quietly.
+            '--include=optional',
+            '--engine-strict=false',
+            `${PKG}@${version}`,
+        ], { cwd: ROOT, env: childEnv(), stdio: 'ignore', timeout: 300_000 });
+        execFileSync(process.execPath, [
+            '--input-type=module',
+            '-e',
+            `const m = await import('${PKG}'); for (const k of ['query','createSdkMcpServer','tool']) if (typeof m[k] !== 'function') process.exit(1);`,
+        ], { cwd: ROOT, env: childEnv(), stdio: 'ignore', timeout: 60_000 });
+        if (!cliRuns())
+            return false;
+        return installedSdkVersion() === version;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Can the SDK's CLI for THIS platform actually start? `--version` is enough: it exits non-zero (or
+ * throws ENOENT) when the binary is missing, which is the whole failure this guards against.
+ */
+function cliRuns() {
+    const bin = join(ROOT, 'node_modules', `${PKG}-${process.platform}-${process.arch}`, 'claude');
+    try {
+        execFileSync(bin, ['--version'], { cwd: ROOT, env: childEnv(), stdio: 'ignore', timeout: 60_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Called by the launcher before anything is loaded. Installs what was downloaded; on any
+ * failure puts the previous version back and never offers that release again.
+ */
+export function applyPendingUpdate() {
+    if (!updatesEnabled())
+        return '';
+    const state = load();
+    const target = state.pending?.version;
+    const before = installedSdkVersion();
+    if (!target || !before || target === before)
+        return '';
+    process.stdout.write(`Updating the Claude Agent SDK ${before} → ${target}…\n`);
+    if (installAndVerify(target)) {
+        delete state.pending;
+        save(state);
+        return `SDK updated ${before} → ${target}`;
+    }
+    installAndVerify(before);
+    delete state.pending;
+    state.bad = [...(state.bad ?? []), target];
+    save(state);
+    return `SDK ${target} failed its check — staying on ${before}`;
+}
+//# sourceMappingURL=updater.js.map

package/dist/updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.js","sourceRoot":"","sources":["../src/updater.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,115 @@
+import type { StreamEvent } from './stream.js';
+/**
+ * Which repositories an agent may work in — answered by the directory it was started in, and by
+ * nothing else.
+ *
+ * The rule is the one a person already has in their head when they type the command: start the
+ * agent in a repo and it works that repo; start it in a folder that holds five repos and it works
+ * all five, because that is what choosing that folder meant. There is no list to configure, which
+ * is the point — a config field for this was always half-set, and a stale one silently either
+ * hides a repo the agent should have or hands it one it should not touch.
+ *
+ * Nothing here decides WHICH repo a card belongs to by itself. The card does that: FlareDeck
+ * resolves a branch per repository from the board's config and the card's Component, and
+ * `resolveCheckout` matches those against the checkouts actually on disk. The folder says what is
+ * allowed; the card says where the work goes.
+ */
+export type Checkout = {
+    /** The checkout's path on disk. */
+    path: string;
+    /** Its directory name, which is what a person calls it. */
+    name: string;
+    /** `origin`, or empty for a repo with no remote. */
+    origin: string;
+};
+/** A git URL reduced to host/owner/name, so ssh and https forms of one repo compare equal. */
+/** `owner/name`, which is how a person says which repo they mean. */
+export declare function shortName(url: string): string;
+export declare function repoIdentity(url: string): string;
+/**
+ * The checkouts this agent may work in.
+ *
+ * A repo is itself, and nothing else — a repo that happens to contain a vendored checkout is one
+ * project, not two. Otherwise the immediate children: one level only, because a folder of
+ * projects is the shape people actually have, and recursing would drag in node_modules and the
+ * worktrees this harness creates. Hidden directories are skipped, which is also what keeps
+ * `.worktrees-*` — written beside each repo by `ensureWorktree` — from being mistaken for repos
+ * of their own.
+ *
+ * The directory list is re-read on every call so a repo cloned while the agent runs is simply
+ * there; only the remotes are cached.
+ */
+export declare function checkouts(root: string, allow?: readonly string[]): Promise<Checkout[]>;
+export type RepoChoice = {
+    checkout: Checkout;
+    branch: string;
+    role: string;
+};
+export type Resolved = 
+/** One checkout owns this card. `branch`/`role` come from the board when it said. */
+({
+    kind: 'repo';
+} & RepoChoice)
+/** The workspace holds no git checkout at all: work in place, with no branch and no isolation. */
+ | {
+    kind: 'none';
+}
+/**
+ * The card names repositories, none of which this agent may work in. `notTicked` are the ones
+ * sitting in the folder that were simply not granted at login — a different problem with a
+ * different fix, and telling them apart is the difference between "clone it" and "tick it".
+ */
+ | {
+    kind: 'unknown';
+    wanted: string[];
+    have: Checkout[];
+    notTicked: string[];
+}
+/** Several of this agent's repos are in scope and the card does not say which. */
+ | {
+    kind: 'ambiguous';
+    candidates: RepoChoice[];
+};
+/**
+ * Which checkout this card's work belongs in.
+ *
+ * The card's own answer wins: `baseBranches` carries one entry per repository the card is scoped
+ * to — just the card's Component when it has one, and every repository on the board when it does
+ * not. So a card that names its component resolves to exactly one checkout, and a card that names
+ * nothing on a five-repo board is genuinely unanswered rather than defaulting to whichever repo
+ * the agent happened to start in. Guessing there is how work lands in the wrong repository, and
+ * the whole reason this returns a verdict instead of a path.
+ */
+export declare function resolveCheckout(root: string, event: StreamEvent, allow?: readonly string[]): Promise<Resolved>;
+/**
+ * Break a tie by asking the code. When a card names no component, the files that mention the
+ * card's own words are the best evidence available of where the work is, and it is evidence the
+ * harness can gather for nothing — a local `git grep` per candidate, run only in the rare case
+ * where the board left the question open.
+ *
+ * Returns null rather than a weak winner: a card whose terms appear nowhere, or appear evenly
+ * across repos, is one a person should route. Asking beats committing to the wrong repository.
+ */
+export declare function voteByCode(candidates: RepoChoice[], text: string): Promise<RepoChoice | null>;
+/** What to tell a person when the harness will not choose. */
+export declare function askingForComponent(r: Extract<Resolved, {
+    kind: 'ambiguous' | 'unknown';
+}>): string;
+/**
+ * The layout, for the agent. Told only in a workspace of several repos, where it is the difference
+ * between knowing where you are and finding out by writing somewhere.
+ */
+export declare function workspaceBrief(root: string, list: Checkout[], chosen: Checkout | null): string;
+/**
+ * Which of the repositories in this folder the agent may work in — asked once, at login.
+ *
+ * The folder is still what is on offer; this is only the person narrowing it. A folder of twenty
+ * repos is rarely twenty an agent should be committing to, and the difference between "can read"
+ * and "may change" is worth one deliberate keystroke. A repo with no remote starts unticked — it
+ * cannot be pushed or opened as a pull request, so an agent given a card in one would do work
+ * nobody can receive.
+ *
+ * Returns the directory names, which is what the person just read on screen. Null when there was
+ * nothing to ask about, or when they backed out.
+ */
+export declare function askRepos(root: string, say: (s: string) => void, already?: readonly string[]): Promise<string[] | null>;

package/dist/workspace.js

@@ -0,0 +1,247 @@
+import { spawn } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { codeSearch } from './codesearch.js';
+/** A git URL reduced to host/owner/name, so ssh and https forms of one repo compare equal. */
+/** `owner/name`, which is how a person says which repo they mean. */
+export function shortName(url) {
+    return repoIdentity(url).split('/').slice(-2).join('/') || url;
+}
+export function repoIdentity(url) {
+    return url.trim().toLowerCase()
+        .replace(/^git@([^:]+):/, '$1/')
+        .replace(/^[a-z]+:\/\//, '')
+        .replace(/\.git$/, '')
+        .replace(/\/+$/, '');
+}
+async function git(args, cwd) {
+    return new Promise((resolve) => {
+        const c = spawn('git', args, { cwd });
+        let out = '';
+        c.stdout.on('data', (d) => (out += String(d)));
+        c.on('close', () => resolve(out.trim()));
+        c.on('error', () => resolve(''));
+    });
+}
+/**
+ * A checkout's remote never changes in practice, and a card asks for it on every event, so it is
+ * read once per path per process rather than spawning git on every wake.
+ */
+const remotes = new Map();
+async function originOf(path) {
+    const cached = remotes.get(path);
+    if (cached !== undefined)
+        return cached;
+    const url = await git(['remote', 'get-url', 'origin'], path);
+    remotes.set(path, url);
+    return url;
+}
+/**
+ * A clone of its own, which means `.git` is a DIRECTORY. A linked worktree and a submodule both
+ * have `.git` as a FILE pointing elsewhere, and neither is an independent project: a card must
+ * never be worked in someone's ad-hoc worktree, where the branch is already checked out for
+ * something else. This harness's own worktrees are hidden (`.worktrees-*`) and skipped anyway;
+ * hand-made ones sitting in the open are exactly what this excludes.
+ */
+const isRepo = (path) => statSafe(join(path, '.git'))?.isDirectory() ?? false;
+function statSafe(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The checkouts this agent may work in.
+ *
+ * A repo is itself, and nothing else — a repo that happens to contain a vendored checkout is one
+ * project, not two. Otherwise the immediate children: one level only, because a folder of
+ * projects is the shape people actually have, and recursing would drag in node_modules and the
+ * worktrees this harness creates. Hidden directories are skipped, which is also what keeps
+ * `.worktrees-*` — written beside each repo by `ensureWorktree` — from being mistaken for repos
+ * of their own.
+ *
+ * The directory list is re-read on every call so a repo cloned while the agent runs is simply
+ * there; only the remotes are cached.
+ */
+export async function checkouts(root, allow) {
+    if (isRepo(root))
+        return [{ path: root, name: basename(root), origin: await originOf(root) }];
+    let names;
+    try {
+        names = readdirSync(root, { withFileTypes: true })
+            .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith('.'))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    // A folder of twenty repos is rarely twenty an agent should touch, so login asks once and the
+    // answer narrows what the folder offers. It narrows and never widens: a repo that is not in the
+    // folder cannot be granted by a config file, and a repo removed from the folder is gone whatever
+    // the config still says. An empty or absent list means everything found here — which is what a
+    // config written before this question existed means too.
+    const picked = allow?.length ? new Set(allow) : null;
+    const found = names
+        .filter((name) => !picked || picked.has(name))
+        .map((name) => join(root, name))
+        .filter(isRepo);
+    return Promise.all(found.map(async (path) => ({ path, name: basename(path), origin: await originOf(path) })));
+}
+/**
+ * Which checkout this card's work belongs in.
+ *
+ * The card's own answer wins: `baseBranches` carries one entry per repository the card is scoped
+ * to — just the card's Component when it has one, and every repository on the board when it does
+ * not. So a card that names its component resolves to exactly one checkout, and a card that names
+ * nothing on a five-repo board is genuinely unanswered rather than defaulting to whichever repo
+ * the agent happened to start in. Guessing there is how work lands in the wrong repository, and
+ * the whole reason this returns a verdict instead of a path.
+ */
+export async function resolveCheckout(root, event, allow) {
+    const list = await checkouts(root, allow);
+    if (!list.length)
+        return { kind: 'none' };
+    const entries = (event.baseBranches ?? []).filter((e) => e.repository);
+    if (!entries.length) {
+        // The board declares no repositories. One checkout is then unambiguous; several are not.
+        const only = list[0];
+        return list.length === 1 && only
+            ? { kind: 'repo', checkout: only, branch: '', role: '' }
+            : { kind: 'ambiguous', candidates: list.map((c) => ({ checkout: c, branch: '', role: '' })) };
+    }
+    const hits = [];
+    for (const e of entries) {
+        const id = repoIdentity(e.repository);
+        for (const c of list) {
+            if (!c.origin || repoIdentity(c.origin) !== id)
+                continue;
+            // Two directories can be clones of one remote (a spare checkout, a case-study copy). They
+            // are the same repository, so the card is not ambiguous — prefer the one named after it.
+            const already = hits.find((h) => repoIdentity(h.checkout.origin) === id);
+            if (already) {
+                const wanted = id.split('/').pop() ?? '';
+                if (c.name.toLowerCase() === wanted && already.checkout.name.toLowerCase() !== wanted) {
+                    already.checkout = c;
+                }
+                continue;
+            }
+            hits.push({ checkout: c, branch: e.branch, role: e.role });
+        }
+    }
+    const one = hits[0];
+    if (hits.length === 1 && one)
+        return { kind: 'repo', ...one };
+    if (!hits.length) {
+        // Is it here but ungranted? That is a tick at login, not a clone, and the person should be
+        // told which it is.
+        const everything = allow?.length ? await checkouts(root) : list;
+        const wantedIds = new Set(entries.map((e) => repoIdentity(e.repository)));
+        const notTicked = everything
+            .filter((c) => c.origin && wantedIds.has(repoIdentity(c.origin)) && !list.some((m) => m.path === c.path))
+            .map((c) => c.name);
+        return { kind: 'unknown', wanted: entries.map((e) => shortName(e.repository)), have: list, notTicked };
+    }
+    return { kind: 'ambiguous', candidates: hits };
+}
+/**
+ * Break a tie by asking the code. When a card names no component, the files that mention the
+ * card's own words are the best evidence available of where the work is, and it is evidence the
+ * harness can gather for nothing — a local `git grep` per candidate, run only in the rare case
+ * where the board left the question open.
+ *
+ * Returns null rather than a weak winner: a card whose terms appear nowhere, or appear evenly
+ * across repos, is one a person should route. Asking beats committing to the wrong repository.
+ */
+export async function voteByCode(candidates, text) {
+    if (!text.trim())
+        return null;
+    const scored = await Promise.all(candidates.map(async (c) => {
+        const found = await codeSearch(c.checkout.path, text).catch(() => null);
+        return { c, score: (found?.files ?? []).reduce((n, f) => n + f.score, 0) };
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    const [best, next] = scored;
+    if (!best || best.score <= 0)
+        return null;
+    // Clearly ahead, not merely ahead: a repo that shares a term or two with its neighbour is not
+    // an answer. Twice the runner-up, or the only one with any hits at all.
+    if (next && next.score > 0 && best.score < next.score * 2)
+        return null;
+    return best.c;
+}
+/** What to tell a person when the harness will not choose. */
+export function askingForComponent(r) {
+    if (r.kind === 'unknown') {
+        const mine = r.have.map((c) => c.name).join(', ') || 'no repository';
+        if (r.notTicked.length) {
+            return (`This card is for ${r.wanted.join(', ')}, which is on the machine working it ` +
+                `(${r.notTicked.join(', ')}) but was not granted to this agent. It works in ${mine}. ` +
+                `Run "flaredeck-agent login" in that folder and tick it, or give the card to the agent ` +
+                `that has it.`);
+        }
+        return (`This card is for ${r.wanted.join(', ')}, which is not on the machine working it. This agent ` +
+            `works in ${mine}. Either the card is for another agent, or that repository needs cloning ` +
+            `into the same folder.`);
+    }
+    return (`This card does not say which repository it is for, and this agent works in several: ` +
+        `${r.candidates.map((c) => c.checkout.name).join(', ')}. Set the card's Component and it will ` +
+        `be picked up — nothing else is needed.`);
+}
+/**
+ * The layout, for the agent. Told only in a workspace of several repos, where it is the difference
+ * between knowing where you are and finding out by writing somewhere.
+ */
+export function workspaceBrief(root, list, chosen) {
+    if (list.length < 2)
+        return '';
+    const others = list.filter((c) => c.path !== chosen?.path).map((c) => c.name);
+    return (`\n\n## The workspace\n\n` +
+        `This machine works ${list.length} repositories under ${root}: ${list.map((c) => c.name).join(', ')}.\n` +
+        (chosen
+            ? `This card is in ${chosen.name}, and your checkout for it is below. The others — ` +
+                `${others.join(', ')} — you may READ to understand how things fit together, and must not ` +
+                `change: they are other cards' repositories and other branches, with no worktree of yours ` +
+                `in them. Work that turns out to belong in one of them is a comment on the card saying so, ` +
+                `not an edit made there.`
+            : `No repository is established for this card, so you have NO checkout of your own and must ` +
+                `not change any of these — every one of them is someone's working tree. You can still ` +
+                `read all of them, which is usually enough to answer. If this turn needs a change made, ` +
+                `say on the card which repository it belongs in and leave it to be picked up with that ` +
+                `set: a change made in place here would be lost or would land on someone else's branch.`));
+}
+/**
+ * Which of the repositories in this folder the agent may work in — asked once, at login.
+ *
+ * The folder is still what is on offer; this is only the person narrowing it. A folder of twenty
+ * repos is rarely twenty an agent should be committing to, and the difference between "can read"
+ * and "may change" is worth one deliberate keystroke. A repo with no remote starts unticked — it
+ * cannot be pushed or opened as a pull request, so an agent given a card in one would do work
+ * nobody can receive.
+ *
+ * Returns the directory names, which is what the person just read on screen. Null when there was
+ * nothing to ask about, or when they backed out.
+ */
+export async function askRepos(root, say, already) {
+    const list = await checkouts(root);
+    if (list.length < 2)
+        return null;
+    const prior = already?.length ? new Set(already) : null;
+    const initial = new Set(list.filter((c) => (prior ? prior.has(c.name) : !!c.origin)).map((c) => c.name));
+    // Nothing to ask when there is nobody to answer. A login run from a script or a pipe would
+    // otherwise block forever on a prompt no one can see, which looks exactly like a hang.
+    if (!process.stdin.isTTY) {
+        say(`\nNot a terminal, so nothing was asked — keeping: ${[...initial].join(', ') || 'none'}`);
+        return initial.size === list.length ? [] : [...initial];
+    }
+    const { pickRepos } = await import('./repopicker.js');
+    const picked = await pickRepos(root, list, initial);
+    if (!picked)
+        return null;
+    // Everything ticked is the same as no restriction, and saying so beats a saved list that has to
+    // be maintained in step with the folder.
+    return picked.length === list.length ? [] : picked;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/dist/worktree.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A checkout per card.
+ *
+ * Without this the agent edits the repo it was pointed at — which, on a machine anyone also uses,
+ * means editing a working tree while someone is in it: uncommitted changes colliding, the branch
+ * moving under them. A worktree costs almost nothing (git shares the object store) and makes the
+ * question "what did the agent change?" answerable with one diff.
+ *
+ * It also makes abandoning safe. A stalled card leaves its worktree behind rather than half-edited
+ * files in the checkout someone else is using, so nothing has to be unpicked.
+ */
+export type Worktree = {
+    path: string;
+    branch: string;
+    created: boolean;
+    from?: string;
+};
+export declare function ensureWorktree(repo: string, card: string, onStep: (text: string) => void, 
+/**
+ * Where work is cut FROM, which is not always the repo's default branch. Some projects have agents
+ * branch from `dev` — the lead owns it, agents take the latest and hand a feature branch back.
+ * Cutting from the default instead would base every card on the wrong history, and the merge
+ * would look like a much bigger change than it is.
+ */
+base?: string): Promise<Worktree | null>;
+/** Told to the agent so it knows where it is and what it is on. */
+export declare function worktreeBrief(tree: Worktree | null): string;
+/**
+ * Remove a card's worktree once the card is finished with.
+ *
+ * Worktrees accumulate: one repository here had fourteen, most of them long-done cards, each a
+ * full checkout on disk. But a worktree is also the ONLY copy of anything an agent has committed
+ * and not published, so this refuses far more readily than it deletes.
+ *
+ * It removes only when there is nothing to lose: no uncommitted changes, no untracked files, and
+ * no commit that is not already on the remote. Anything else is left exactly where it is, and the
+ * reason is returned so a person can be told rather than left to find an orphan later.
+ */
+export declare function releaseWorktree(repo: string, card: string, onStep: (text: string) => void): Promise<{
+    removed: boolean;
+    why: string;
+}>;