@shardflux/cli 0.15.2 → 0.17.0

package/dist/update.js

@@ -286,12 +286,23 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
     return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
 }
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
-export function recordInstall(dir, runtime, distribution) {
+export function recordInstall(dir, runtime, distribution, env = {}) {
     let script = runtime.script;
     try {
         script = realpathSync(script);
     }
     catch { /* keep the path */ }
+    // A global install (npm, pnpm, bun, Volta) is what the menu bar runs and updates. A run from a source checkout, a
+    // project's node_modules or npx never replaces a recorded install that still exists, so a one-off run cannot point
+    // the menu bar (and its update button) at it. SHARDFLUX_RECORD_INSTALL=1 records any run (menu bar development).
+    if (env.SHARDFLUX_RECORD_INSTALL !== '1' && !['npm', 'pnpm', 'bun', 'volta'].includes(detectInstall(script, distribution.package).manager)) {
+        try {
+            const recorded = JSON.parse(readFileSync(join(dir, INSTALL_FILE), 'utf8')).script;
+            if (typeof recorded === 'string' && recorded !== script && existsSync(recorded))
+                return;
+        }
+        catch { /* nothing recorded yet: this run is the best there is */ }
+    }
     // The app this CLI's npm package carries (0.15.2+): the menu bar compares itself with it and swaps itself in.
     let menubarApp = packagedAppPath();
     try {

package/dist/wait-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a wait stands (0.16.0+): while a command waits on an operation whose start is queued for capacity, or a call
+ * waits for room (the workspace's host making room to wake it, or a free working slot of the plan), one line on stderr
+ * says so: the queue position, what the pool is doing (a new host starting, when it is expected) and until when the
+ * start holds its place. A line is printed only when it changes; dim on a terminal, plain when piped; never with
+ * --json, where stdout stays one document and stderr is left to the error.
+ */
+import type { ProgressEvent, ProgressListener, RetryRecord } from '@shardflux/sdk';
+import type { Writer } from './commands.js';
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export declare function clockZ(iso: string): string;
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export declare function queueLine(e: Pick<Extract<ProgressEvent, {
+    type: 'phase';
+}>, 'queuePosition' | 'scaleOut' | 'expectedReadyBy' | 'deadlineAt'>): string;
+/** A call waiting to be admitted, in words. */
+export declare function admissionLine(r: Pick<RetryRecord, 'reason' | 'queuePosition'>): string;
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export declare function waitStatusListener(stderr: Writer, json: boolean): ProgressListener;

package/dist/wait-status.js

@@ -0,0 +1,59 @@
+/** `2026-10-09T21:40:12Z` as `21:40Z` (UTC); the input when it is not a timestamp. */
+export function clockZ(iso) {
+    const t = Date.parse(iso);
+    return Number.isFinite(t) ? `${new Date(t).toISOString().slice(11, 16)}Z` : iso;
+}
+/** A queued start in words: `queued for capacity (position 3): a new host is starting, ready by 21:40Z; it holds its place until 21:51Z`. */
+export function queueLine(e) {
+    const position = e.queuePosition ? ` (position ${e.queuePosition})` : '';
+    const pool = e.scaleOut === 'requested'
+        ? `: a new host is starting${e.expectedReadyBy ? `, ready by ${clockZ(e.expectedReadyBy)}` : ''}`
+        : e.scaleOut === 'clamped'
+            ? ': it starts as soon as a host has room'
+            : '';
+    const until = e.deadlineAt ? `; it holds its place until ${clockZ(e.deadlineAt)}` : '';
+    return `queued for capacity${position}${pool}${until}`;
+}
+/** A call waiting to be admitted, in words. */
+export function admissionLine(r) {
+    const position = r.queuePosition ? ` (position ${r.queuePosition})` : '';
+    if (r.reason === 'host_capacity')
+        return `waiting for room on the workspace's host${position}`;
+    if (r.reason === 'concurrent_workspaces')
+        return 'waiting for a free working slot: every workspace the plan lets work at once is busy';
+    return `waiting to be admitted${r.reason ? ` (${r.reason})` : ''}${position}`;
+}
+/**
+ * The client listener that prints where a wait stands. Silent with `json`. A phase other than capacity_pending ends
+ * the queue, so a later queue prints again.
+ */
+export function waitStatusListener(stderr, json) {
+    let last = null;
+    return (e) => {
+        if (json)
+            return;
+        let line;
+        if (e.type === 'retry') {
+            if (!e.retry.admission)
+                return;
+            line = admissionLine(e.retry);
+        }
+        else if (e.type === 'phase') {
+            if (e.phase !== 'capacity_pending') {
+                if (e.action !== 'tool')
+                    last = null;
+                return;
+            }
+            line = queueLine(e);
+        }
+        else {
+            if (e.action !== 'token' && e.action !== 'tool')
+                last = null;
+            return;
+        }
+        if (line === last)
+            return;
+        last = line;
+        stderr.write(stderr.isTTY ? `\x1b[2m· ${line}\x1b[0m\n` : `${line}\n`);
+    };
+}

package/dist/worktree-twin-engine.d.ts

@@ -0,0 +1,125 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+import { TwinLedger } from './worktree-twin.js';
+import type { LandingMode, TwinCell } from './worktree-twin.js';
+export interface TwinAgent {
+    id: string;
+    workspace_id: string;
+    state: 'working' | 'waiting' | 'exited';
+    since: string;
+}
+export type TwinConversation = Conversation & {
+    changes: {
+        files: number;
+        insertions: number;
+        deletions: number;
+        commits: number;
+        uncommitted: boolean;
+    };
+    landed: {
+        how: string;
+        ref: string;
+        at: string;
+    } | null;
+    summary: string;
+    name?: string;
+    join_mode?: string | null;
+    base_branch?: string | null;
+    last_activity_at?: string;
+    repo_remote?: string;
+};
+/** Its VM is gone: the conversation ended (archived after the retention window, or done). */
+export declare const ended: (c: TwinConversation) => boolean;
+export interface EngineDeps {
+    records(): LocalConversation[];
+    conversations(projectId: string): Promise<TwinConversation[]>;
+    agents(projectId: string): Promise<TwinAgent[]>;
+    /** The conversation's VM (woken when suspended), and its release; null when the VM is gone. */
+    cell(c: TwinConversation): Promise<{
+        cell: TwinCell;
+        close(): void;
+    } | null>;
+    /** A VM of the project that reads the project hub (an awake one, else the project's space reader). */
+    hubCell(projectId: string): Promise<{
+        cell: TwinCell;
+        close(): void;
+    }>;
+    /** Restores an ended conversation into a fresh VM (so its agent can resolve a conflict). */
+    resume(c: TwinConversation): Promise<void>;
+    land(c: TwinConversation, action: 'merge' | 'pr', into: string): Promise<void>;
+    message(c: TwinConversation, text: string): Promise<void>;
+    ledger: TwinLedger;
+    stateDir: string;
+    device: string;
+    log(line: string): void;
+    now(): number;
+    hub?: string;
+    vmTmp?: string;
+    quietMs?: number;
+    /**
+     * Long-polls the conversation's next finished turn after `after` (RFC 3339): the turn's conversation and report time,
+     * null when the wait timed out. Throws TurnWaitUnsupported when the API has no turn waits.
+     */
+    waitTurn?(c: TwinConversation, after: string, signal: AbortSignal): Promise<{
+        conversation: TwinConversation;
+        reported_at: string;
+    } | null | 'ended'>;
+}
+/** A turn ended with committed work only; the agent is not asking anything. */
+export declare function finished(c: TwinConversation, agents: TwinAgent[]): TwinAgent | 'state' | null;
+export declare function eligible(c: TwinConversation, ledger: TwinLedger, now: number): boolean;
+export declare function conflictMessage(into: string, files: string[]): string;
+type Ready = {
+    c: TwinConversation;
+    record: LocalConversation;
+    mode: Exclude<LandingMode, 'off'>;
+    agent: TwinAgent | null;
+    at: number;
+};
+/** Refused by an API without turn waits (POST /wait with turn_after, 422): the twin polls instead. */
+export declare class TurnWaitUnsupported extends Error {
+}
+export declare class TwinEngine {
+    #private;
+    constructor(deps: EngineDeps);
+    /** Resolves when a pushed turn is waiting to land (the loop's sleep ends at once). */
+    pushed(): Promise<void>;
+    /** Stops every turn wait. */
+    stop(): void;
+    /**
+     * One pass; returns the suggested wait before the next. Turns pushed by the waits land first, without a listing;
+     * otherwise (and at least every 15 s, or every second when the API has no turn waits) every project is listed.
+     */
+    tick(signal?: AbortSignal): Promise<number>;
+    /** Back online or awake: every conversation's retry backoff is cleared, so the next pass tries all of them. */
+    resetBackoff(): void;
+    landOne(c: TwinConversation, record: LocalConversation, mode: Exclude<LandingMode, 'off'>, agent: TwinAgent | null, signal?: AbortSignal): Promise<number | undefined>;
+    /** Several finished conversations for one branch: merged in their VMs at once, the files written once. */
+    landBatch(items: Ready[], signal?: AbortSignal): Promise<number | undefined>;
+}
+export interface LoopDeps {
+    tick(signal: AbortSignal): Promise<number>;
+    resetBackoff(): void;
+    sleep(ms: number, signal: AbortSignal): Promise<void>;
+    /** Wall-clock and monotonic milliseconds: the monotonic clock stands still while the computer sleeps. */
+    wall(): number;
+    mono(): number;
+    /** The computer's network addresses (any change is a network change). */
+    network(): string;
+    /** Whether the API host answers now (a TCP connect, no request). */
+    reachable(): Promise<boolean>;
+    /** Resolves when a pushed turn waits to land: the loop's sleep ends at once. */
+    kicked?(): Promise<void>;
+    log(line: string): void;
+}
+/**
+ * Runs the twin's passes. A failing pass (offline) backs off up to 5 minutes, but the wait ends at once when the
+ * computer wakes from sleep (the wall clock jumps past the monotonic one), when its network changes, or when the API
+ * host answers again (probed every 5 s while failing); every conversation's retry backoff is then cleared and a pass
+ * runs immediately. The first pass that succeeds after failures clears them too and runs again at once.
+ */
+export declare function runTwinLoop(deps: LoopDeps, signal: AbortSignal): Promise<void>;
+/** The device helper's twin. Nothing here asks the user anything. */
+export declare function runWorktreeTwin(ctx: Ctx, device: string, signal: AbortSignal): Promise<void>;
+export declare const TWIN_HANDLERS: Record<string, Handler>;
+export {};