@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/automode.js

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { configPath } from './config.js';
+export const DEFAULT_ENVIRONMENT = {
+    organization: 'Phiresky / FlareDeck',
+    trustedDomains: ['mcp.flaredeck.app', 'app.flaredeck.app', '*.googleapis.com', 'registry.npmjs.org'],
+    sensitiveTargets: ['prod', 'preprod', 'production branches and any Firebase project named phireboard'],
+    sandboxed: true,
+};
+function environmentEntries(env) {
+    return [
+        '$defaults',
+        `Organization: ${env.organization}. Primary use: software development — an unattended agent ` +
+            `working tickets from a Kanban board, editing code, running tests, and pushing branches.`,
+        ...(env.sandboxed
+            ? [
+                // "Host containment" is the slot the docs name for containers and VMs. Until it says
+                // what this box is, the classifier assumes a developer laptop on the open internet and
+                // treats routine disposable-environment work as risky.
+                'Host containment: a dedicated machine that does nothing but run this agent. Its ' +
+                    'checkout, its database and its local services are disposable and are rebuilt from ' +
+                    'scratch routinely, so destructive local operations — dropping and recreating the ' +
+                    'local database, deleting worktrees, killing local servers — are ordinary work here ' +
+                    'and not a loss of anything. There are no neighbouring workloads to disturb.',
+            ]
+            : []),
+        `Trusted internal domains: ${env.trustedDomains.join(', ')}`,
+        'Key internal services: FlareDeck at mcp.flaredeck.app is this agent\'s own task tracker. ' +
+            'Reading cards and posting comments, claims and status changes there is its normal work, ' +
+            'not data leaving the organisation. A card\'s fields — Environment, Component, lane, ' +
+            'assignee, labels, notes — are metadata on a ticket: setting a card\'s Environment to ' +
+            '"Production" records where a bug was seen and deploys nothing, touches no server and no ' +
+            'database. Only commands and scripts aimed at the targets below are production operations.',
+        `Sensitive remote targets: ${env.sensitiveTargets.join('; ')}. Treat anything else as ` +
+            `ordinary development infrastructure.`,
+    ];
+}
+/**
+ * The settings the agent runs under, written OUTSIDE the repo on purpose.
+ *
+ * The classifier deliberately refuses to read `autoMode` from a repo's `.claude/settings.json`,
+ * "so a checked-in repo or a build step could not otherwise inject its own allow rules". The same
+ * reasoning applies here with more force: the agent can edit its own checkout, so any policy kept
+ * there is policy the agent could rewrite. Keeping it beside the agent's config means the thing
+ * being governed cannot reach the thing governing it.
+ */
+export function writeAutoModeSettings(config, env = DEFAULT_ENVIRONMENT) {
+    const path = join(dirname(configPath(config.repo)), 'auto-mode.json');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({
+        autoMode: { environment: environmentEntries(env) },
+        // No memory on this machine. The CLI would otherwise read and write
+        // ~/.claude/projects/<cwd>/memory — a file keyed to a directory on one box, which is
+        // exactly what an agent that must behave the same wherever it starts cannot depend on.
+        // Its memory lives on its FlareDeck account instead (see `remember`), and the brief says so.
+        autoMemoryEnabled: false,
+        permissions: {
+            // Evaluated BEFORE the classifier and always prompt, even in auto mode — which in this
+            // harness means they reach canUseTool, and so the team lead. These are the calls worth
+            // a person's attention rather than a judgement in the moment.
+            ask: ['Bash(git push *)', 'Bash(gh pr create *)'],
+            // Evaluated before the classifier too, and nothing can override them — not the
+            // classifier, not stated intent, not a hook.
+            deny: [`Edit(//${'**'}/.flaredeck/**)`],
+        },
+    }, null, 2)}\n`, 'utf8');
+    return path;
+}
+//# sourceMappingURL=automode.js.map

package/dist/automode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automode.js","sourceRoot":"","sources":["../src/automode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAwBtD,MAAM,CAAC,MAAM,mBAAmB,GAAgB;IAC9C,YAAY,EAAE,sBAAsB;IACpC,cAAc,EAAE,CAAC,mBAAmB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,CAAC;IACpG,gBAAgB,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,+DAA+D,CAAC;IACtG,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF,SAAS,kBAAkB,CAAC,GAAgB;IAC1C,OAAO;QACL,WAAW;QACX,iBAAiB,GAAG,CAAC,YAAY,4DAA4D;YAC3F,yFAAyF;QAC3F,GAAG,CAAC,GAAG,CAAC,SAAS;YACf,CAAC,CAAC;gBACE,qFAAqF;gBACrF,uFAAuF;gBACvF,uDAAuD;gBACvD,kFAAkF;oBAChF,oFAAoF;oBACpF,mFAAmF;oBACnF,qFAAqF;oBACrF,6EAA6E;aAChF;YACH,CAAC,CAAC,EAAE,CAAC;QACP,6BAA6B,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC5D,2FAA2F;YACzF,0FAA0F;YAC1F,sFAAsF;YACtF,uFAAuF;YACvF,0FAA0F;YAC1F,2FAA2F;QAC7F,6BAA6B,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B;YACrF,sCAAsC;KACzC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,MAAmB,mBAAmB;IAC1F,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACtE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CACX,IAAI,EACJ,GAAG,IAAI,CAAC,SAAS,CACf;QACE,QAAQ,EAAE,EAAE,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAAE;QAClD,oEAAoE;QACpE,qFAAqF;QACrF,uFAAuF;QACvF,6FAA6F;QAC7F,iBAAiB,EAAE,KAAK;QACxB,WAAW,EAAE;YACX,uFAAuF;YACvF,uFAAuF;YACvF,8DAA8D;YAC9D,GAAG,EAAE,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;YACjD,+EAA+E;YAC/E,6CAA6C;YAC7C,IAAI,EAAE,CAAC,UAAU,IAAI,iBAAiB,CAAC;SACxC;KACF,EACD,IAAI,EACJ,CAAC,CACF,IAAI,EACL,MAAM,CACP,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/branches.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which branch this machine works from.
+ *
+ * Asked once at login, from the repo's actual branches, rather than left to a project file
+ * somebody has to know exists. Getting it wrong is quiet and expensive: every card would be cut
+ * from the wrong history and every pull request would target the wrong place, and both look
+ * fine until a merge is enormous.
+ */
+export type RemoteBranch = {
+    name: string;
+    when: string;
+};
+/**
+ * The remote's branches, most recently changed first, each with how long ago that was.
+ *
+ * Alphabetical was useless on a real repo: 350 branches, and the one that mattered somewhere
+ * past "CST-679". The branch work merges into is the one people are committing to, so the order
+ * that answers the question is by last commit — and the date beside each name is what lets a
+ * person tell a live branch from a dead one with the same kind of name.
+ *
+ * Needs the remote-tracking refs to be current, so it fetches first. On a repo with no fetch
+ * possible it falls back to the remote's plain list, undated and unsorted, rather than nothing.
+ */
+export declare function remoteBranches(repo: string): Promise<RemoteBranch[]>;
+export declare function askBaseBranch(repo: string, say: (s: string) => void): Promise<string | null>;

package/dist/branches.js

@@ -0,0 +1,81 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+function git(args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, { cwd });
+        let out = '';
+        child.stdout.on('data', (d) => (out += String(d)));
+        child.on('close', (code) => resolve(code === 0 ? out : ''));
+        child.on('error', () => resolve(''));
+    });
+}
+/**
+ * The remote's branches, most recently changed first, each with how long ago that was.
+ *
+ * Alphabetical was useless on a real repo: 350 branches, and the one that mattered somewhere
+ * past "CST-679". The branch work merges into is the one people are committing to, so the order
+ * that answers the question is by last commit — and the date beside each name is what lets a
+ * person tell a live branch from a dead one with the same kind of name.
+ *
+ * Needs the remote-tracking refs to be current, so it fetches first. On a repo with no fetch
+ * possible it falls back to the remote's plain list, undated and unsorted, rather than nothing.
+ */
+export async function remoteBranches(repo) {
+    await git(['fetch', '--prune', '--quiet', 'origin'], repo);
+    const dated = await git(
+    // The full ref, not the short form: origin/HEAD shortens to a branch called "origin".
+    ['for-each-ref', '--sort=-committerdate', '--format=%(refname)\t%(committerdate:relative)', 'refs/remotes/origin/'], repo);
+    const fromRefs = dated
+        .split('\n')
+        .map((l) => l.split('\t'))
+        .filter((p) => p.length === 2 && !!p[0])
+        .map(([ref, when]) => ({ name: ref.replace(/^refs\/remotes\/origin\//, ''), when }))
+        .filter((b) => b.name !== 'HEAD');
+    if (fromRefs.length)
+        return fromRefs;
+    const plain = await git(['ls-remote', '--heads', 'origin'], repo);
+    const names = plain
+        .split('\n')
+        .map((l) => l.split('refs/heads/')[1]?.trim())
+        .filter((n) => !!n);
+    return [...new Set(names)].map((name) => ({ name, when: '' }));
+}
+/** The usual names for the branch work merges into — pulled forward, but only when recent. */
+const LIKELY = ['dev', 'develop', 'development', 'main', 'master', 'trunk'];
+export async function askBaseBranch(repo, say) {
+    const branches = await remoteBranches(repo);
+    const all = branches.map((b) => b.name);
+    if (all.length === 0) {
+        say('Could not read the remote branches, so nothing to choose from.');
+        return null;
+    }
+    // Most recently changed first — that is the order that answers the question. The usual names
+    // are only pulled forward when they are themselves recent; a stale "development" nobody has
+    // touched in a year is not the usual answer, whatever it is called.
+    const recent = branches.slice(0, 12);
+    const likely = recent.filter((b) => LIKELY.includes(b.name));
+    const offered = [...likely, ...recent.filter((b) => !likely.includes(b))].slice(0, 12);
+    say('\nWhich branch does work start from, and merge back into? (most recently changed first)');
+    const width = Math.max(...offered.map((b) => b.name.length));
+    offered.forEach((b, i) => say(`  ${String(i + 1).padStart(2)}. ${b.name.padEnd(width)}${b.when ? `   ${b.when}` : ''}`));
+    if (all.length > offered.length)
+        say(`  … and ${all.length - offered.length} more`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`\nNumber, or type a branch name [${offered[0]?.name}]: `)).trim();
+        if (!answer)
+            return offered[0]?.name ?? null;
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= offered.length)
+            return offered[n - 1].name;
+        // A typed name is taken at its word only if it exists — a typo here is silent otherwise.
+        if (all.includes(answer))
+            return answer;
+        say(`There is no branch called "${answer}" on origin.`);
+        return offered[0]?.name ?? null;
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=branches.js.map

package/dist/branches.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// A thin launcher: it must run BEFORE the SDK is loaded, because an SDK downloaded in the
+// background can only be swapped in while nothing has it open. Everything else is main.ts.
+import { applyPendingUpdate } from './updater.js';
+const first = process.argv[2];
+if (!first || first === 'serve' || first.startsWith('--')) {
+    const note = applyPendingUpdate();
+    if (note)
+        process.env['FLAREDECK_AGENT_UPDATED'] = note;
+}
+await import('./main.js');
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,0FAA0F;AAC1F,2FAA2F;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9B,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1D,MAAM,IAAI,GAAG,kBAAkB,EAAE,CAAC;IAClC,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,GAAG,IAAI,CAAC;AAC1D,CAAC;AACD,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/codesearch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where in the repo a card's work probably lives, worked out with grep rather than a model.
+ *
+ * A card almost always names something: a handler, an endpoint path, an error string, a file.
+ * Those names are searched for across the checkout and the files are ranked by how many of
+ * them they mention. It is not understanding — it is a map with the likely places circled —
+ * and it saves the working agent the first few tool calls of every card, which on a large repo
+ * are the expensive ones. No model, no network; a second or two of `git grep`.
+ */
+export type Candidate = {
+    path: string;
+    score: number;
+    terms: string[];
+};
+export type CodeSearch = {
+    terms: string[];
+    files: Candidate[];
+    ms: number;
+};
+/**
+ * Identifiers worth searching for, from the card's text. Specific beats common: a CamelCase name
+ * with three humps is a better lead than a word that happens to be capitalised.
+ */
+export declare function searchTerms(text: string): string[];
+/** Files ranked by how many of the card's names they mention. Empty when the repo is not git or nothing matched. */
+export declare function codeSearch(repo: string, text: string): Promise<CodeSearch>;
+export declare function codeSearchText(cs: CodeSearch | null): string;

package/dist/codesearch.js

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+const MAX_TERMS = 24;
+const MAX_FILES = 12;
+const TIMEOUT_MS = 12_000;
+/** Words that look like identifiers but point nowhere: the tools, the products, the ceremony. */
+const NOISE = new Set([
+    'FlareDeck', 'Flaredeck', 'GitHub', 'GitLab', 'JavaScript', 'TypeScript',
+    'OpenAI', 'ChatGPT', 'MySQL', 'PostgreSQL', 'MongoDB', 'GraphQL', 'WebVTT', 'macOS', 'iPhone', 'iOS', 'JSON', 'HTML', 'HTTP', 'HTTPS',
+    'README', 'TODO', 'FIXME', 'PRODUCTION', 'NOTE', 'SELECT', 'UPDATE', 'DELETE', 'INSERT', 'WHERE', 'FROM', 'JOIN', 'COUNT',
+    'Production', 'Development', 'Backlog', 'Released', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday',
+]);
+/**
+ * Identifiers worth searching for, from the card's text. Specific beats common: a CamelCase name
+ * with three humps is a better lead than a word that happens to be capitalised.
+ */
+export function searchTerms(text) {
+    const found = new Map();
+    const add = (t, weight) => {
+        const k = t.trim();
+        if (k.length < 4 || k.length > 80 || NOISE.has(k))
+            return;
+        found.set(k, Math.max(found.get(k) ?? 0, weight));
+    };
+    // CamelCase and PascalCase identifiers: GetCompletionRateQueryHandler, learnerCourseId.
+    for (const m of text.matchAll(/\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+){1,}\b|\b[a-z]+(?:[A-Z][a-z0-9]+){2,}\b/g))
+        add(m[0], 3);
+    // snake_case and SCREAMING_CASE with at least one underscore inside.
+    for (const m of text.matchAll(/\b[a-z]+(?:_[a-z0-9]+){1,}\b|\b[A-Z]{2,}(?:_[A-Z0-9]+){1,}\b/g))
+        add(m[0], 2);
+    // Code spans: `whatever is quoted like this`.
+    for (const m of text.matchAll(/`([^`\n]{4,60})`/g))
+        add(m[1], 3);
+    // File names with an extension.
+    for (const m of text.matchAll(/\b[\w.-]+\.(?:cs|ts|tsx|js|jsx|py|go|rb|java|kt|swift|sql|scss|css|html|vue|json|yaml|yml)\b/g))
+        add(m[0], 4);
+    // API paths: the last two segments of /api/learning/mine are what the code names.
+    for (const m of text.matchAll(/\/api\/[\w\-/{}.]+/g)) {
+        const parts = m[0].split('/').filter((p) => p && !/^[{}]|^\d+$|^[0-9a-f-]{20,}$/i.test(p));
+        const tail = parts.slice(-2).join('/');
+        if (tail)
+            add(tail, 3);
+        const last = parts[parts.length - 1];
+        if (last)
+            add(last, 2);
+    }
+    // Quoted error strings: "Commands out of sync".
+    for (const m of text.matchAll(/["“']([A-Z][^"”'\n]{8,70})["”']/g))
+        add(m[1], 2);
+    return [...found.entries()]
+        .sort((a, b) => b[1] - a[1] || b[0].length - a[0].length)
+        .slice(0, MAX_TERMS)
+        .map(([t]) => t);
+}
+function gitGrepCount(repo, term) {
+    return new Promise((resolve) => {
+        execFile('git', ['grep', '-I', '-c', '-F', '-e', term, '--', '.', ':!*.min.*', ':!*.map', ':!*.lock', ':!package-lock.json', ':!yarn.lock', ':!*.svg'], { cwd: repo, timeout: TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+            const out = new Map();
+            if (err && !stdout)
+                return resolve(out); // exit 1 = no matches; anything else = treat as none
+            for (const line of String(stdout).split('\n')) {
+                const i = line.lastIndexOf(':');
+                if (i <= 0)
+                    continue;
+                const n = Number(line.slice(i + 1));
+                if (Number.isFinite(n) && n > 0)
+                    out.set(line.slice(0, i), n);
+            }
+            resolve(out);
+        });
+    });
+}
+/** Files ranked by how many of the card's names they mention. Empty when the repo is not git or nothing matched. */
+export async function codeSearch(repo, text) {
+    const started = Date.now();
+    const terms = searchTerms(text);
+    if (!terms.length || !existsSync(repo))
+        return { terms, files: [], ms: Date.now() - started };
+    const results = await Promise.all(terms.map((t) => gitGrepCount(repo, t)));
+    const score = new Map();
+    results.forEach((hits, i) => {
+        const term = terms[i];
+        // A name in two thousand files is not a lead; one in a dozen is.
+        if (hits.size === 0 || hits.size > 60)
+            return;
+        const specificity = 1 + Math.log(60 / hits.size);
+        for (const [path, n] of hits) {
+            const c = score.get(path) ?? { path, score: 0, terms: [] };
+            c.score += specificity * (1 + Math.log(n));
+            c.terms.push(term);
+            score.set(path, c);
+        }
+    });
+    const files = [...score.values()]
+        // Tests and generated files are real matches but rarely where the fix goes; nudge them down, keep them.
+        .map((c) => (/(^|\/)(tests?|__tests__|spec|specs|migrations|generated|dist|build)\//i.test(c.path) || /\.(spec|test)\./.test(c.path) ? { ...c, score: c.score * 0.6 } : c))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, MAX_FILES);
+    return { terms, files, ms: Date.now() - started };
+}
+export function codeSearchText(cs) {
+    if (!cs || !cs.files.length)
+        return '';
+    return [
+        '',
+        'Candidate files (ranked by how many names from the card they mention — a map, not an answer):',
+        ...cs.files.map((f) => `  - ${f.path}  (${f.terms.slice(0, 4).join(', ')}${f.terms.length > 4 ? `, +${f.terms.length - 4}` : ''})`),
+        `  searched for: ${cs.terms.slice(0, 12).join(', ')}${cs.terms.length > 12 ? ', …' : ''}`,
+    ].join('\n');
+}
+//# sourceMappingURL=codesearch.js.map

package/dist/codesearch.js.map

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

package/dist/concurrency.d.ts

@@ -0,0 +1,14 @@
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * Cap how many sub-agents run at once.
+ *
+ * Sub-agents are where an environment gets contended: two testing the API is fine, a third
+ * starting its own copy is not. Leasing ports per job would be the thorough answer, but a cap is
+ * most of the benefit for a fraction of the machinery — with a known ceiling you can size the
+ * environment for it and stop thinking about it.
+ *
+ * Done as a PreToolUse hook rather than a prompt instruction because hooks run before every other
+ * permission step and a hook deny holds even in bypassPermissions. A limit the model can talk
+ * itself past is not a limit.
+ */
+export declare function subagentLimit(max: number, onNote: (text: string) => void): Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/concurrency.js

@@ -0,0 +1,52 @@
+/**
+ * Cap how many sub-agents run at once.
+ *
+ * Sub-agents are where an environment gets contended: two testing the API is fine, a third
+ * starting its own copy is not. Leasing ports per job would be the thorough answer, but a cap is
+ * most of the benefit for a fraction of the machinery — with a known ceiling you can size the
+ * environment for it and stop thinking about it.
+ *
+ * Done as a PreToolUse hook rather than a prompt instruction because hooks run before every other
+ * permission step and a hook deny holds even in bypassPermissions. A limit the model can talk
+ * itself past is not a limit.
+ */
+export function subagentLimit(max, onNote) {
+    let running = 0;
+    return {
+        PreToolUse: [
+            {
+                // Only the tool that spawns them; everything else is untouched.
+                matcher: 'Agent',
+                hooks: [
+                    async () => {
+                        if (running >= max) {
+                            onNote(`held back a sub-agent — ${running}/${max} already running`);
+                            return {
+                                decision: 'block',
+                                reason: `${running} sub-agents are already running and the limit is ${max}. Wait for one ` +
+                                    `to finish before starting another, or do this part yourself. Starting more would ` +
+                                    `have them competing for the same ports, database and dev server.`,
+                            };
+                        }
+                        running += 1;
+                        return { continue: true };
+                    },
+                ],
+            },
+        ],
+        PostToolUse: [
+            {
+                matcher: 'Agent',
+                hooks: [
+                    async () => {
+                        // Never below zero: a hook that missed its pair would otherwise leak capacity upward
+                        // and quietly remove the limit.
+                        running = Math.max(0, running - 1);
+                        return { continue: true };
+                    },
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,MAA8B;IACvE,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,OAAO;QACL,UAAU,EAAE;YACV;gBACE,gEAAgE;gBAChE,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,KAAK,IAAI,EAAE;wBACT,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;4BACnB,MAAM,CAAC,2BAA2B,OAAO,IAAI,GAAG,kBAAkB,CAAC,CAAC;4BACpE,OAAO;gCACL,QAAQ,EAAE,OAAO;gCACjB,MAAM,EACJ,GAAG,OAAO,oDAAoD,GAAG,iBAAiB;oCAClF,mFAAmF;oCACnF,kEAAkE;6BACrE,CAAC;wBACJ,CAAC;wBACD,OAAO,IAAI,CAAC,CAAC;wBACb,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;oBAC5B,CAAC;iBACF;aACF;SACF;QACD,WAAW,EAAE;YACX;gBACE,OAAO,EAAE,OAAO;gBAChB,KAAK,EAAE;oBACL,KAAK,IAAI,EAAE;wBACT,qFAAqF;wBACrF,gCAAgC;wBAChC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;wBACnC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;oBAC5B,CAAC;iBACF;aACF;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,106 @@
+import type { Tokens } from './oauth.js';
+/**
+ * What this machine's agent is, and where it works.
+ *
+ * Deliberately thin. Anything that describes a PROJECT (boards, lanes, build commands, territories)
+ * belongs in that project's own `.flaredeck/agent.yaml`, so one agent binary serves any repo.
+ * Anything that describes the agent's POWERS lives in Flaredeck against its account, so copying
+ * this file to another box grants nothing.
+ */
+export type Config = {
+    /**
+     * Where this agent was started — a repo, or a folder of them. The directory is the declaration
+     * of what it may touch; see workspace.ts.
+     */
+    repo: string;
+    /**
+     * In a folder of several repos, the ones ticked at login. Directory names, because that is what
+     * was on screen. It only ever NARROWS what the folder holds — a name here that is not in the
+     * folder grants nothing — and empty or absent means every repo found there.
+     */
+    repos?: string[];
+    /**
+     * Which model actually runs a turn. Per-repo, so one machine can run some agents on Claude and
+     * some on Gemini and compare them on the same board. `FLAREDECK_AGENT_ENGINE` overrides it for
+     * one run without editing anything, which is how you try the other one on a card and put it
+     * back. Absent means claude.
+     */
+    engine?: 'claude' | 'antigravity';
+    /** MCP server name registered with the Claude CLI — also the `mcp__<name>__` tool prefix. */
+    mcpServerName: string;
+    mcpUrl: string;
+    /**
+     * The harness's OWN FlareDeck credentials, separate from the model's MCP login. The supervisor
+     * has to be able to post and read an approval even when the model is wedged, so it cannot go
+     * through the model's tools. Key comes from Integrations → API in FlareDeck.
+     */
+    tenantId?: string;
+    apiKey?: string;
+    /**
+     * The harness's OWN FlareDeck OAuth tokens — not Claude Code's. This is what makes it a
+     * first-class client rather than a passenger on the model's session: it can listen, post and
+     * call tools while the model is busy, wedged, or not running at all.
+     */
+    oauth?: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresAt: number;
+        clientId: string;
+        clientSecret?: string;
+    };
+    /**
+     * GitHub, held by the HARNESS. The agent has publishing tools and no `gh`, so it cannot read
+     * this even from a shell — the credential is out of its reach rather than off-limits by rule.
+     */
+    github?: {
+        accessToken: string;
+        refreshToken?: string;
+        expiresAt?: number;
+    };
+    /**
+     * Where work is cut from and merged back into. Chosen at login from the repo's real branches,
+     * because asking once beats a project file someone has to know to write. A repo that declares
+     * `branches.base` in .flaredeck/agent.yaml overrides this — that one is reviewed and shared.
+     */
+    baseBranch?: string;
+    /** Where the event stream and /notify live. */
+    agentServiceUrl?: string;
+    /**
+     * Production targets the HARNESS may run an approved script against — see runs.ts. Configured
+     * on the machine, by a person, never by the agent: the command is what runs, the agent only
+     * supplies the script that goes into it.
+     */
+    runs?: Record<string, RunTarget>;
+};
+export type RunTarget = {
+    /** Program and arguments. `{script}` marks where the script goes; without it, stdin. */
+    command: string[];
+    cwd?: string;
+    /** Shown to the agent in the tool description. */
+    about?: string;
+    /** Who may approve a run against this target — emails or user keys. Empty: whoever owns the card. */
+    approvers?: string[];
+};
+export declare const DEFAULTS: {
+    readonly mcpServerName: "flaredeck";
+    readonly mcpUrl: "https://mcp.flaredeck.app/mcp";
+    readonly agentServiceUrl: "https://flaredeck-agent-861259873190.us-central1.run.app";
+};
+/**
+ * Config per REPO, not per machine.
+ *
+ * One machine runs several agents — a worker on one project, a lead on another, or simply two
+ * checkouts. With a single file they shared an identity: starting the agent in a second repo
+ * picked up the first one's account and listened on its queue, which looks like it is working
+ * and is entirely the wrong agent.
+ *
+ * Keyed by path, so `cd` into a repo and run it and you get that repo's agent.
+ */
+export declare const configPath: (repo: string) => string;
+export declare function loadConfig(repo?: string): Config | null;
+export declare function saveConfig(config: Config): string;
+export declare function loadMe(): Tokens | null;
+export declare function saveMe(tokens: Tokens): string;
+export declare function forgetConfig(repo: string): boolean;
+/** Config with defaults filled in — for commands that can run before `login` has written one. */
+export declare function configOrDefaults(repo?: string): Config;