@ashlr/hub 3.10.0 → 3.11.0

package/dist/core/cloud/backlog.js

@@ -0,0 +1,177 @@
+/**
+ * Self-improvement backlog (unit C1): built-in items (improvement-backlog.ts)
+ * plus operator/Leader items at `<cloudHome>/backlog.json`. An item is
+ * "claimed" by its newest task; it becomes available again 3 days after
+ * that task ends closed/failed/expired, never after merged.
+ *
+ * File: `{ "v": 1, "items": CloudBacklogItem[] }`, 0600, at most
+ * CLOUD_BACKLOG_MAX_USER_ITEMS items. Readers validate every item and skip
+ * the bad ones, so one hand-mangled entry cannot hide the rest.
+ */
+import { join } from 'node:path';
+import { readPrivateFileCapped, writePrivateFileAtomic } from '../verse/preferences.js';
+import { BUILTIN_IMPROVEMENT_BACKLOG } from './improvement-backlog.js';
+import { CLOUD_REPO_PATTERN, cloudHome, ensureCloudDirectory, listCloudTasks } from './store.js';
+import { CLOUD_PROMPT_MAX_CHARS } from './types.js';
+export const CLOUD_BACKLOG_FILE = 'backlog.json';
+export const CLOUD_BACKLOG_MAX_USER_ITEMS = 200;
+/** A closed/failed/expired item is retried after this long (a merged one never is). */
+export const CLOUD_BACKLOG_RETRY_MS = 3 * 24 * 60 * 60 * 1000;
+const BACKLOG_VERSION = 1;
+/** 200 items × a 20 000-char prompt, with room for JSON escaping. */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/;
+const MAX_TITLE_CHARS = 200;
+const MAX_AREA_CHARS = 40;
+const RETRYABLE = ['closed', 'failed', 'expired'];
+export function cloudBacklogPath() {
+    return join(cloudHome(), CLOUD_BACKLOG_FILE);
+}
+/** A clean copy of a valid item, or null. Titles and areas are trimmed; nothing else is rewritten. */
+export function validBacklogItem(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const r = value;
+    const id = r['id'];
+    const title = typeof r['title'] === 'string' ? r['title'].trim() : '';
+    const prompt = typeof r['prompt'] === 'string' ? r['prompt'] : '';
+    const area = typeof r['area'] === 'string' ? r['area'].trim() : '';
+    const priority = r['priority'];
+    const repo = r['repo'];
+    if (typeof id !== 'string' || !ID_RE.test(id))
+        return null;
+    if (title === '' || title.length > MAX_TITLE_CHARS)
+        return null;
+    if (prompt.trim() === '' || prompt.length > CLOUD_PROMPT_MAX_CHARS)
+        return null;
+    if (area === '' || area.length > MAX_AREA_CHARS)
+        return null;
+    if (priority !== 1 && priority !== 2 && priority !== 3)
+        return null;
+    if (repo !== undefined && (typeof repo !== 'string' || !CLOUD_REPO_PATTERN.test(repo)))
+        return null;
+    return { id, title, prompt, area, priority, ...(repo !== undefined ? { repo } : {}) };
+}
+/** Dedupe key for titles: case, punctuation and spacing do not make an item new. */
+export function normaliseBacklogTitle(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+/** The operator/Leader items on disk, validated, deduped, capped. Total: any bad file reads as empty. */
+export function readUserBacklogItems() {
+    const file = readPrivateFileCapped(cloudBacklogPath(), MAX_FILE_BYTES);
+    if (!file || file.truncated)
+        return [];
+    let value;
+    try {
+        value = JSON.parse(file.text);
+    }
+    catch {
+        return [];
+    }
+    // A bare array is accepted too: it is what an operator writes by hand.
+    const raw = Array.isArray(value) ? value
+        : value !== null && typeof value === 'object' && Array.isArray(value['items'])
+            ? value['items']
+            : [];
+    const ids = new Set(BUILTIN_IMPROVEMENT_BACKLOG.map((item) => item.id));
+    const titles = new Set(BUILTIN_IMPROVEMENT_BACKLOG.map((item) => normaliseBacklogTitle(item.title)));
+    const items = [];
+    for (const entry of raw) {
+        if (items.length >= CLOUD_BACKLOG_MAX_USER_ITEMS)
+            break;
+        const item = validBacklogItem(entry);
+        if (!item || ids.has(item.id) || titles.has(normaliseBacklogTitle(item.title)))
+            continue;
+        ids.add(item.id);
+        titles.add(normaliseBacklogTitle(item.title));
+        items.push(item);
+    }
+    return items;
+}
+/** Built-in first, then user items, each in file order: the tie-break after priority. */
+function allItems() {
+    return [...BUILTIN_IMPROVEMENT_BACKLOG, ...readUserBacklogItems()];
+}
+/** Newest task per backlog item id. */
+function newestTaskByItem(tasks) {
+    const newest = new Map();
+    for (const task of tasks) {
+        if (!task.backlogItemId)
+            continue;
+        const seen = newest.get(task.backlogItemId);
+        if (!seen || Date.parse(task.createdAt) > Date.parse(seen.createdAt))
+            newest.set(task.backlogItemId, task);
+    }
+    return newest;
+}
+function claimOf(task, nowMs) {
+    if (!task)
+        return { claimedBy: null, lastState: null };
+    if (RETRYABLE.includes(task.state)) {
+        // updatedAt is when the task last changed — for a terminal task, when it ended.
+        const endedAt = Date.parse(task.updatedAt);
+        const released = Number.isFinite(endedAt) && nowMs - endedAt >= CLOUD_BACKLOG_RETRY_MS;
+        return { claimedBy: released ? null : task.id, lastState: task.state };
+    }
+    // Non-terminal: in progress. Merged: done for good.
+    return { claimedBy: task.id, lastState: task.state };
+}
+function ordered(items) {
+    return items.map((item, index) => ({ item, index }))
+        .sort((a, b) => a.item.priority - b.item.priority || a.index - b.index)
+        .map(({ item }) => item);
+}
+export function readCloudBacklog(tasks, now) {
+    const newest = newestTaskByItem(tasks);
+    const nowMs = now.getTime();
+    const items = ordered(allItems()).map((item) => ({ ...item, ...claimOf(newest.get(item.id), nowMs) }));
+    return { items, nextUp: items.find((item) => item.claimedBy === null)?.id ?? null };
+}
+/** Next unclaimed item for `repo`, highest priority first, then built-in order. */
+export function nextBacklogItem(tasks, repo, now) {
+    const newest = newestTaskByItem(tasks);
+    const nowMs = now.getTime();
+    const target = repo.toLowerCase();
+    // An item without a repo targets whichever repo self-improvement is pointed at.
+    const match = ordered(allItems()).find((item) => (item.repo === undefined || item.repo.toLowerCase() === target) && claimOf(newest.get(item.id), nowMs).claimedBy === null);
+    return match ?? null;
+}
+/** Adds items (dedupe by id and by normalised title); returns how many were new. Leader/operator entry point. */
+export function appendUserBacklogItems(items) {
+    if (!Array.isArray(items) || items.length === 0)
+        return 0;
+    let existing = readUserBacklogItems();
+    const ids = new Set([...BUILTIN_IMPROVEMENT_BACKLOG, ...existing].map((item) => item.id));
+    const titles = new Set([...BUILTIN_IMPROVEMENT_BACKLOG, ...existing].map((item) => normaliseBacklogTitle(item.title)));
+    const fresh = [];
+    for (const entry of items) {
+        const item = validBacklogItem(entry);
+        if (!item || ids.has(item.id) || titles.has(normaliseBacklogTitle(item.title)))
+            continue;
+        ids.add(item.id);
+        titles.add(normaliseBacklogTitle(item.title));
+        fresh.push(item);
+    }
+    if (fresh.length === 0)
+        return 0;
+    if (existing.length + fresh.length > CLOUD_BACKLOG_MAX_USER_ITEMS) {
+        // Make room by retiring items that are finished for good (their newest
+        // task merged), oldest first — never an item still waiting to run.
+        const newest = newestTaskByItem(listCloudTasks());
+        let excess = existing.length + fresh.length - CLOUD_BACKLOG_MAX_USER_ITEMS;
+        existing = existing.filter((item) => {
+            if (excess > 0 && newest.get(item.id)?.state === 'merged') {
+                excess -= 1;
+                return false;
+            }
+            return true;
+        });
+    }
+    const accepted = fresh.slice(0, Math.max(0, CLOUD_BACKLOG_MAX_USER_ITEMS - existing.length));
+    if (accepted.length === 0)
+        return 0;
+    ensureCloudDirectory();
+    writePrivateFileAtomic(cloudBacklogPath(), `${JSON.stringify({ v: BACKLOG_VERSION, items: [...existing, ...accepted] }, null, 2)}\n`);
+    return accepted.length;
+}
+//# sourceMappingURL=backlog.js.map

package/dist/core/cloud/backlog.js.map

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

package/dist/core/cloud/budget.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Budget view + gates (unit C1). Spend = creditsSpentAdjustmentUsd + sum of
+ * estimatedCostUsd over tasks that reached `running` or later (failed
+ * launches cost nothing). "Today" = the operator's local calendar day.
+ *
+ * Pure: no clock, no disk — the caller passes the tasks, the budget and now.
+ */
+import { type CloudBudgetV1, type CloudBudgetView, type CloudTaskV1 } from './types.js';
+/**
+ * Whether a task consumed a session. A session id is the proof; the states
+ * cover a task recorded without one. A `closed` task with no session is a
+ * dismissed failure, not spend.
+ */
+export declare function taskConsumedSession(task: CloudTaskV1): boolean;
+/** `YYYY-MM-DD` of the operator's local calendar day. */
+export declare function localDayKey(date: Date): string;
+/** `$3`, `$2.50`, `$1,234` — whole dollars without cents. */
+export declare function formatUsd(value: number): string;
+export declare function cloudBudgetView(tasks: readonly CloudTaskV1[], budget: CloudBudgetV1, now: Date): CloudBudgetView;

package/dist/core/cloud/budget.js

@@ -0,0 +1,99 @@
+/**
+ * Budget view + gates (unit C1). Spend = creditsSpentAdjustmentUsd + sum of
+ * estimatedCostUsd over tasks that reached `running` or later (failed
+ * launches cost nothing). "Today" = the operator's local calendar day.
+ *
+ * Pure: no clock, no disk — the caller passes the tasks, the budget and now.
+ */
+import { CLOUD_BALANCE_URL } from './types.js';
+const OK = Object.freeze({ ok: true, reason: null });
+const refuse = (reason) => ({ ok: false, reason });
+/**
+ * Whether a task consumed a session. A session id is the proof; the states
+ * cover a task recorded without one. A `closed` task with no session is a
+ * dismissed failure, not spend.
+ */
+export function taskConsumedSession(task) {
+    return task.sessionId !== null || task.state === 'running' || task.state === 'pr-open' || task.state === 'merged' || task.state === 'expired';
+}
+/** In flight: accepted and not yet resolved into a session or a failure. Counts toward the daily caps so a burst cannot overshoot them. */
+const inFlight = (task) => task.state === 'queued' || task.state === 'launching';
+/** `YYYY-MM-DD` of the operator's local calendar day. */
+export function localDayKey(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+/** `$3`, `$2.50`, `$1,234` — whole dollars without cents. */
+export function formatUsd(value) {
+    const rounded = Math.round(value * 100) / 100;
+    const whole = Number.isInteger(rounded);
+    return `$${rounded.toLocaleString('en-US', { minimumFractionDigits: whole ? 0 : 2, maximumFractionDigits: whole ? 0 : 2 })}`;
+}
+const plural = (n, one, many) => (n === 1 ? one : many);
+export function cloudBudgetView(tasks, budget, now) {
+    const today = localDayKey(now);
+    let spent = budget.creditsSpentAdjustmentUsd;
+    let sessionsToday = 0;
+    let selfImproveToday = 0;
+    let running = 0;
+    let queued = 0;
+    for (const task of tasks) {
+        const consumed = taskConsumedSession(task);
+        if (consumed)
+            spent += task.estimatedCostUsd;
+        if (task.state === 'launching' || task.state === 'running')
+            running += 1;
+        if (task.state === 'queued')
+            queued += 1;
+        if (!consumed && !inFlight(task))
+            continue;
+        const at = Date.parse(task.launchedAt ?? task.createdAt);
+        if (!Number.isFinite(at) || localDayKey(new Date(at)) !== today)
+            continue;
+        sessionsToday += 1;
+        if (task.origin === 'self-improve')
+            selfImproveToday += 1;
+    }
+    const estimatedSpentUsd = Math.round(spent * 100) / 100;
+    const estimatedRemainingUsd = Math.max(0, Math.round((budget.creditsTotalUsd - estimatedSpentUsd) * 100) / 100);
+    const cost = budget.estimatedCostPerSessionUsd;
+    let canLaunch = OK;
+    if (estimatedRemainingUsd < cost || (cost === 0 && estimatedRemainingUsd <= 0)) {
+        canLaunch = refuse(`About ${formatUsd(estimatedRemainingUsd)} of estimated credits is left — not enough for another session at ${formatUsd(cost)} each.`);
+    }
+    else if (sessionsToday >= budget.maxSessionsPerDay) {
+        canLaunch = refuse(`${sessionsToday} of ${budget.maxSessionsPerDay} cloud ${plural(budget.maxSessionsPerDay, 'session', 'sessions')} used today.`);
+    }
+    else if (running + queued >= budget.maxConcurrent) {
+        // Queued tasks are about to launch, so they hold a slot: otherwise two
+        // launches accepted back to back (different repos) could both pass a cap of one.
+        canLaunch = refuse(`${running + queued} of ${budget.maxConcurrent} cloud ${plural(budget.maxConcurrent, 'session is', 'sessions are')} already running.`);
+    }
+    let canSelfImprove = canLaunch;
+    if (canLaunch.ok) {
+        if (!budget.selfImprove.enabled) {
+            canSelfImprove = refuse('Self-improvement is turned off.');
+        }
+        else if (selfImproveToday >= budget.selfImprove.maxPerDay) {
+            canSelfImprove = refuse(`${selfImproveToday} of ${budget.selfImprove.maxPerDay} self-improvement ${plural(budget.selfImprove.maxPerDay, 'launch', 'launches')} used today.`);
+        }
+        else if (estimatedRemainingUsd - cost < budget.selfImprove.reserveUsd) {
+            // The reserve is kept for the operator's own tasks: self-improvement
+            // stops BEFORE a launch would take the estimate below it.
+            canSelfImprove = refuse(`Another self-improvement session would take estimated credits below the ${formatUsd(budget.selfImprove.reserveUsd)} reserve.`);
+        }
+    }
+    return {
+        creditsTotalUsd: budget.creditsTotalUsd,
+        estimatedSpentUsd,
+        estimatedRemainingUsd,
+        sessionsToday,
+        selfImproveToday,
+        running,
+        canLaunch,
+        canSelfImprove,
+        estimateNote: `Estimated at ${formatUsd(cost)} per session — Claude doesn't expose the credit balance. Check it on claude.ai and adjust here.`,
+        balanceUrl: CLOUD_BALANCE_URL,
+        budget,
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/cloud/budget.js.map

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

package/dist/core/cloud/checkout.d.ts

@@ -0,0 +1,41 @@
+export type CloudCheckoutResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    failure: 'no-remote' | 'checkout-failed';
+    message: string;
+};
+export interface CloudCheckoutDeps {
+    git?: (args: string[], opts: {
+        cwd: string;
+        timeoutMs: number;
+    }) => Promise<{
+        ok: boolean;
+        stdout: string;
+        stderr: string;
+    }>;
+    originUrlFor?: (repo: string) => string;
+}
+export declare const CLOUD_CHECKOUTS_DIR = "checkouts";
+/**
+ * In-process FIFO mutex keyed by string. Two `--cloud` runs (or a fetch and
+ * a launch) in one folder would race on the checked-out branch, so every
+ * user of a folder queues here. The map entry is dropped when the last
+ * waiter finishes, so it never grows with the number of repos ever used.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** True while any caller holds or waits for `key` (tests, diagnostics). */
+    busy(key: string): boolean;
+}
+/**
+ * A branch name git accepts that also cannot be read as an option or escape
+ * the ref namespace. Stricter than check-ref-format on purpose: base
+ * branches are human names like `main` or `v3110-cloud`.
+ */
+export declare function isSafeBranchName(branch: string): boolean;
+/** Lower-cased: GitHub names are case-insensitive, and so is the default macOS filesystem — one repo, one folder, one lock. */
+export declare function cloudCheckoutPath(repo: string): string;
+export declare function ensureCloudCheckout(repo: string, branch: string, deps?: CloudCheckoutDeps): Promise<CloudCheckoutResult>;

package/dist/core/cloud/checkout.js

@@ -0,0 +1,168 @@
+/**
+ * Isolated launch checkouts (unit C1): `<cloudHome>/checkouts/<owner>__<name>`,
+ * a shallow single-branch clone of https://github.com/<owner>/<name>.git
+ * using the operator's normal git credentials. Before each launch:
+ * `git fetch --depth 1 origin <branch>` then `git checkout -B <branch>
+ * FETCH_HEAD` with upstream set, so the CLI sees a pushed branch. Never
+ * touches the operator's own clones or fleet mirrors. Serialise per path.
+ *
+ * WHY a checkout of our own: `claude --cloud` clones the cwd's origin at the
+ * cwd's CURRENT branch. Launching from the operator's working copy would pin
+ * the session to whatever branch they happen to have checked out (possibly
+ * unpushed); a private checkout pinned to the requested base makes the
+ * session start exactly where the task says.
+ */
+import { lstatSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultGitRunner } from '../verse/git-ops.js';
+import { CLOUD_REPO_PATTERN, cloudHome, ensureCloudDirectory } from './store.js';
+export const CLOUD_CHECKOUTS_DIR = 'checkouts';
+const CLONE_TIMEOUT_MS = 180_000;
+const GIT_TIMEOUT_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Per-key mutex
+// ---------------------------------------------------------------------------
+/**
+ * In-process FIFO mutex keyed by string. Two `--cloud` runs (or a fetch and
+ * a launch) in one folder would race on the checked-out branch, so every
+ * user of a folder queues here. The map entry is dropped when the last
+ * waiter finishes, so it never grows with the number of repos ever used.
+ */
+export class KeyedMutex {
+    tails = new Map();
+    async run(key, fn) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => current);
+        this.tails.set(key, tail);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        }
+    }
+    /** True while any caller holds or waits for `key` (tests, diagnostics). */
+    busy(key) {
+        return this.tails.has(key);
+    }
+}
+const checkoutMutex = new KeyedMutex();
+// ---------------------------------------------------------------------------
+// Checkout
+// ---------------------------------------------------------------------------
+/**
+ * A branch name git accepts that also cannot be read as an option or escape
+ * the ref namespace. Stricter than check-ref-format on purpose: base
+ * branches are human names like `main` or `v3110-cloud`.
+ */
+export function isSafeBranchName(branch) {
+    return typeof branch === 'string'
+        && branch.length > 0 && branch.length <= 200
+        && /^[A-Za-z0-9._/-]+$/.test(branch)
+        && !branch.startsWith('-') && !branch.startsWith('/') && !branch.endsWith('/')
+        && !branch.endsWith('.') && !branch.endsWith('.lock')
+        && !branch.includes('..') && !branch.includes('//') && !branch.includes('/.');
+}
+/** Lower-cased: GitHub names are case-insensitive, and so is the default macOS filesystem — one repo, one folder, one lock. */
+export function cloudCheckoutPath(repo) {
+    const [owner, name] = repo.toLowerCase().split('/');
+    return join(cloudHome(), CLOUD_CHECKOUTS_DIR, `${owner}__${name}`);
+}
+const defaultOriginUrl = (repo) => `https://github.com/${repo}.git`;
+async function defaultGit(args, opts) {
+    const result = await defaultGitRunner('git', args, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+    return { ok: result.code === 0 && !result.timedOut, stdout: result.stdout, stderr: result.missing ? 'git is not installed' : result.stderr };
+}
+/** git's words for "that repo or branch is not on GitHub (or not reachable with these credentials)". */
+function isMissingRemote(stderr) {
+    return /couldn't find remote ref|remote branch .* not found|repository not found|could not read from remote repository|could not read username|authentication failed|does not appear to be a git repository/i.test(stderr);
+}
+function failed(repo, branch, stderr) {
+    if (isMissingRemote(stderr)) {
+        return { ok: false, failure: 'no-remote', message: `Couldn't find branch ${branch} of ${repo} on GitHub. Check the repo name, that the branch is pushed, and that git can reach it.` };
+    }
+    return { ok: false, failure: 'checkout-failed', message: `Couldn't prepare a checkout of ${repo} at ${branch} for the cloud launch.` };
+}
+function isGitCheckout(path) {
+    try {
+        const dir = lstatSync(path);
+        if (!dir.isDirectory() || dir.isSymbolicLink())
+            return false;
+        return lstatSync(join(path, '.git')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function prepare(repo, branch, deps) {
+    const git = deps.git ?? defaultGit;
+    const url = (deps.originUrlFor ?? defaultOriginUrl)(repo);
+    let parent;
+    try {
+        parent = ensureCloudDirectory(CLOUD_CHECKOUTS_DIR);
+    }
+    catch {
+        return { ok: false, failure: 'checkout-failed', message: "Couldn't create the private folder for cloud checkouts." };
+    }
+    const path = cloudCheckoutPath(repo);
+    if (!isGitCheckout(path)) {
+        // Anything else at our own path is a clone that died half-way (or was
+        // tampered with); it is ours to replace, and git refuses a non-empty target.
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch { /* clone below reports it */ }
+        const clone = await git(['clone', '--depth', '1', '--single-branch', '--no-tags', '--branch', branch, '--', url, path], { cwd: parent, timeoutMs: CLONE_TIMEOUT_MS });
+        if (!clone.ok) {
+            try {
+                rmSync(path, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+            return failed(repo, branch, clone.stderr);
+        }
+    }
+    const steps = [
+        // The origin URL is re-asserted every time so a checkout can never launch
+        // against a remote other than the one the task names.
+        ['remote', 'set-url', 'origin', url],
+        // A single-branch clone only maps its first branch to a remote-tracking
+        // ref; git refuses an upstream (and cannot resolve @{u}) for any other
+        // base until the remote's fetch refspec covers it.
+        ['remote', 'set-branches', 'origin', '*'],
+        // An explicit refspec keeps a remote-tracking ref even in a single-branch
+        // clone, which is what the upstream below points at.
+        ['fetch', '--depth', '1', '--no-tags', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`],
+        ['checkout', '--force', '-B', branch, 'FETCH_HEAD'],
+        ['branch', `--set-upstream-to=origin/${branch}`, branch],
+        // Nothing a previous launch left behind may ride along into the next session.
+        ['clean', '-ffdx'],
+    ];
+    for (const args of steps) {
+        const step = await git(args, { cwd: path, timeoutMs: args[0] === 'fetch' ? CLONE_TIMEOUT_MS : GIT_TIMEOUT_MS });
+        if (!step.ok)
+            return failed(repo, branch, step.stderr);
+    }
+    return { ok: true, path };
+}
+export async function ensureCloudCheckout(repo, branch, deps = {}) {
+    if (typeof repo !== 'string' || !CLOUD_REPO_PATTERN.test(repo)) {
+        return { ok: false, failure: 'checkout-failed', message: 'The repo must look like owner/name.' };
+    }
+    if (!isSafeBranchName(branch)) {
+        return { ok: false, failure: 'checkout-failed', message: `"${String(branch).slice(0, 80)}" isn't a branch name the cloud lane accepts.` };
+    }
+    return checkoutMutex.run(cloudCheckoutPath(repo), async () => {
+        try {
+            return await prepare(repo, branch, deps);
+        }
+        catch {
+            return { ok: false, failure: 'checkout-failed', message: `Couldn't prepare a checkout of ${repo} at ${branch} for the cloud launch.` };
+        }
+    });
+}
+//# sourceMappingURL=checkout.js.map

package/dist/core/cloud/checkout.js.map

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

package/dist/core/cloud/cloud-api.d.ts

@@ -0,0 +1,86 @@
+import type { ApiModule } from '../verse/api-modules.js';
+import { type NeedsYouItem } from '../verse/workbench-types.js';
+import { type CloudBudgetUpdate, type CloudLaunchRequest, type CloudTaskV1 } from './types.js';
+/** Same shape the service validates (spec C1); checked here too so bad input is a 400, not a failed task. */
+export declare const CLOUD_REPO_PATTERN: RegExp;
+export declare class CloudInputError extends Error {
+}
+export declare function isValidCloudRepo(value: unknown): value is string;
+export declare function isValidBranchName(value: unknown): value is string;
+/** Strict parse of a launch body; throws CloudInputError with a plain sentence. `origin` defaults to operator. */
+export declare function parseCloudLaunchBody(body: Record<string, unknown>): CloudLaunchRequest;
+/**
+ * Strict parse of a budget update: types and signs only. Clamping to sane
+ * maxima is the store's job (updateCloudBudget), so the two never disagree
+ * about what "sane" means.
+ */
+export declare function parseCloudBudgetBody(body: Record<string, unknown>): CloudBudgetUpdate;
+export declare function parseCloudImproveBody(body: Record<string, unknown>): {
+    count: number;
+};
+export declare const CLOUD_DISMISS_REASON = "Dismissed in Verse.";
+export type CloudDismissResult = {
+    ok: true;
+    task: CloudTaskV1;
+} | {
+    ok: false;
+    status: 404 | 409;
+    error: string;
+};
+/**
+ * Mark a task `closed` with "Dismissed in Verse." — idempotent for a task
+ * already closed. Refused for a MERGED task (closing it would rewrite what
+ * happened) and while a launch is still in flight (the service would then
+ * overwrite the dismissal with `running`).
+ */
+export declare function dismissCloudTask(id: string, now?: Date): CloudDismissResult;
+/** Failed launches stay in Needs-you this long (spec C2). */
+export declare const CLOUD_FAILED_WINDOW_MS: number;
+/**
+ * PURE: the Needs-you items for `tasks` at `now`.
+ *
+ * WHY THESE SOURCES AND KINDS: the Needs-you contract (workbench-types.ts
+ * §2) has a closed set of sources and kinds, and the web drawer and the
+ * desktop shell switch on both exhaustively, so a new one is not additive.
+ * A cloud PR is exactly an `owner-lane-pr` — a PR that is never merged
+ * automatically and waits for Mason — filed under `fleet`, the source the
+ * drawer already reads for that kind. A failed launch is a failed piece of
+ * work the operator started (often from a chat's "Run in cloud"), so it is a
+ * `chats` / `chat-failed` item with no session to open.
+ */
+export declare function cloudNeedsYouItems(tasks: readonly CloudTaskV1[], now: Date): NeedsYouItem[];
+/**
+ * Needs-you producer (activity-api.ts calls it on every poll). Returns the
+ * cached items in O(1) and, when the cache is stale, rebuilds it on a later
+ * tick — the task store is file I/O and never runs on the poll's stack. The
+ * first call answers [] (cloud items are additive to sources that vouch for
+ * themselves) and has the real answer ready for the next poll.
+ */
+export declare function needsYouItems(): NeedsYouItem[];
+/** Test seam: replace the task reader (null restores) and drop the cache. */
+export declare function setCloudNeedsYouReaderForTest(read: (() => readonly CloudTaskV1[]) | null): void;
+export declare function refreshCloudTasksGuarded(): Promise<{
+    checked: number;
+    updated: number;
+}>;
+export declare const CLOUD_REFRESH_EVERY_MS: number;
+export declare const CLOUD_IMPROVE_EVERY_MS: number;
+export declare const CLOUD_IMPROVE_FIRST_DELAY_MS: number;
+/** Why this process must not run the scheduler; null when it may. */
+export declare function cloudSchedulerRefusal(env?: NodeJS.ProcessEnv): string | null;
+export interface CloudSchedulerDeps {
+    refresh?: () => Promise<unknown>;
+    improve?: () => Promise<unknown>;
+    log?: (message: string) => void;
+}
+/**
+ * Start the process-wide scheduler once (idempotent, never throws). True when
+ * it runs. Jobs are guarded against overlapping runs — a tick that finds its
+ * previous run still going is skipped, not queued — and a failure is logged
+ * once per DISTINCT error, then stays quiet until it changes or clears.
+ */
+export declare function startCloudScheduler(env?: NodeJS.ProcessEnv, deps?: CloudSchedulerDeps): boolean;
+/** Stop the scheduler (tests, shutdown). Safe to call when it never started. */
+export declare function stopCloudScheduler(): void;
+export declare function cloudSchedulerRunning(): boolean;
+export declare const handleCloudApi: ApiModule;