@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/feed-broadcast.js

@@ -38,7 +38,8 @@ import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } fro
 import { lookupTransport } from './channels/resolve.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { sendToOwner } from './notify.js';
-import { linearIssueUrl } from './session/linear.js';
+import { linearIssueUrl, linearIssueKeys } from './session/linear.js';
+import { isValidMailboxId } from './mailbox.js';
 import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -145,6 +146,27 @@ export function shortSessionChunk(session) {
     const chunk = hex.replace(/[^a-f0-9]/g, '').slice(0, 8);
     return chunk || undefined;
 }
+/**
+ * Tap-to-view link for the session behind a post: the addressable console page
+ * ({@link https://prix.dev/console/sessions/<id>}, prix/web). The footer already
+ * carries a short session crumb for disambiguation; this rides the link trail so
+ * the owner can open the full transcript straight from an iMessage broadcast
+ * instead of hunting for it in the console.
+ *
+ * Accepts any real, path-safe session id — a Claude/Codex UUID *and* a native
+ * `ses_…` id from OpenCode or another harness. The console shard uploader
+ * (`traces/sync.ts`) syncs sessions with no harness filter, so all of them are
+ * addressable; a UUID-only gate would silently drop the link for every non-Claude
+ * harness (the whole point of the link). Reject only an id that could not resolve:
+ * one with a path separator (URL-unsafe, via {@link isValidMailboxId}) or the bare
+ * 8-char footer crumb (a truncated id that would 404).
+ */
+export function sessionConsoleUrl(session) {
+    const id = session?.trim();
+    if (!id || !isValidMailboxId(id) || /^[0-9a-f]{8}$/i.test(id))
+        return undefined;
+    return `https://prix.dev/console/sessions/${id}`;
+}
 /**
  * Scrub em/en dashes from outbound phone copy (house rule + iMessage readability).
  * Collapses whitespace; does not invent meaning.
@@ -158,6 +180,56 @@ export function scrubOutboundDashes(text) {
         .replace(/[ \t]{2,}/g, ' ')
         .trim();
 }
+/** Slack mrkdwn labeled link: `<url|label>` renders as blue `label` text. */
+function slackLink(url, label) {
+    return `<${url}|${label}>`;
+}
+/**
+ * Only Slack renders `<url|label>`, so it is the one format that gets labeled
+ * links. iMessage / owner-scoped rush / command / desktop sinks stay `plain`
+ * (they can't turn `claude/6fc1db18` blue, and dumping the raw URL is worse than
+ * leaving the crumb unlinked — PHNX-3698).
+ *
+ * The argument is the **resolved provider name**, not the sink's declared
+ * channel: an operator can point an arbitrary channel name at the Slack provider
+ * through `notify.transports` (e.g. `eng-alerts -> slack`), and delivery keys off
+ * that resolved provider (`lookupTransport`), so the format decision must too —
+ * otherwise an aliased Slack sink would compose plain while delivering to Slack,
+ * or a name remapped AWAY from Slack would emit `<url|label>` markup a non-Slack
+ * transport shows literally. {@link resolveSinkProvider} does the mapping.
+ */
+export function sinkMessageFormat(provider) {
+    return provider?.trim().toLowerCase() === 'slack' ? 'mrkdwn' : 'plain';
+}
+/**
+ * The provider a channel name actually delivers through — the same
+ * `notify.transports` remap `lookupTransport` applies at delivery — so the format
+ * decision and the delivery agree on what Slack is. Identity when no mapping
+ * exists (or no `meta`), matching the default name-identity transport rule.
+ */
+function resolveSinkProvider(channel, meta) {
+    return meta?.notify?.transports?.[channel] ?? channel;
+}
+/**
+ * Replace each real Linear key the text NAMES with a Slack labeled link to its
+ * issue — `PHNX-3689` → `<https://linear.app/getrush/issue/PHNX-3689|PHNX-3689>`
+ * — so the key itself turns blue in place (no trailing URL line). Plain format,
+ * or a key the workspace can't resolve, or a denylisted unit string, is left as
+ * the bare key. `linearIssueKeys` is the same canonical detector the trail used,
+ * so mrkdwn linkifies exactly the keys plain leaves as text.
+ */
+function linkifyKeys(text, format) {
+    if (format !== 'mrkdwn' || !text)
+        return text;
+    let out = text;
+    for (const key of linearIssueKeys(text)) {
+        const url = linearIssueUrl(key);
+        if (!url)
+            continue;
+        out = out.replace(new RegExp(`\\b${key}\\b`, 'g'), slackLink(url, key));
+    }
+    return out;
+}
 /**
  * Footer like "Sent from my iPhone" — who posted, a session crumb, which box.
  *
@@ -165,8 +237,13 @@ export function scrubOutboundDashes(text) {
  *
  * Agent name first; session chunk for disambiguation when many groks run;
  * host last. Skip the uninformative default label `agent`.
+ *
+ * In `mrkdwn` the crumb (`agent/short`) becomes a Slack labeled link to the
+ * session's console page, so the human sentence reads identically while the
+ * crumb turns blue and taps through (PHNX-3698). `plain` keeps the bare sentence
+ * — it can't render a labeled link and must not dump the URL.
  */
-export function composeBroadcastFooter(ctx) {
+export function composeBroadcastFooter(ctx, format = 'plain') {
     const agent = ctx.agent?.trim();
     const agentLabel = agent && agent !== 'agent' ? agent : undefined;
     const session = shortSessionChunk(ctx.session);
@@ -178,6 +255,10 @@ export function composeBroadcastFooter(ctx) {
         who = agentLabel;
     else if (session)
         who = session;
+    // The crumb is only a link when the session resolves to a real console page.
+    const consoleUrl = who ? sessionConsoleUrl(ctx.session) : undefined;
+    if (who && format === 'mrkdwn' && consoleUrl)
+        who = slackLink(consoleUrl, who);
     if (who && host)
         return `Sent from ${who} on ${host}`;
     if (who)
@@ -236,16 +317,17 @@ export function truncateBroadcastBody(body) {
         return body;
     return `${out.trimEnd()}\n… (full in feed)`;
 }
-export function composeBroadcastMessage(ctx) {
+export function composeBroadcastMessage(ctx, format = 'plain') {
     const title = scrubOutboundDashes(ctx.title ?? '');
     const body = truncateBroadcastBody(scrubOutboundDashes(ctx.text ?? ''));
     // Title preferred; if an older post has no title, body alone still sends.
-    const head = title || body;
-    const mid = title && body && title !== body ? body : undefined;
-    const footer = composeBroadcastFooter(ctx);
-    const links = [ctx.ticketUrl, ...(ctx.links ?? [])]
-        .filter((l) => !!l && /^https?:\/\//i.test(l))
-        .filter((l, i, all) => all.indexOf(l) === i);
+    // A `TEAM-N` key the human typed is dead text on a phone — in `mrkdwn` the key
+    // itself becomes a Slack labeled link in place, so nothing rides a trailing
+    // naked URL line; `plain` leaves the bare key (iMessage can't render a label,
+    // and dumping the URL is worse than leaving it — PHNX-3698).
+    const head = linkifyKeys(title || body, format);
+    const mid = title && body && title !== body ? linkifyKeys(body, format) : undefined;
+    const footer = composeBroadcastFooter(ctx, format);
     // The action block: the one thing the operator can act on from a phone. Show the
     // choices, then what happens if they do not answer. Deliberately NOT a CLI command
     // (`agents focus <id>` is unusable from a phone) -- the safe default is the real
@@ -259,8 +341,6 @@ export function composeBroadcastMessage(ctx) {
             : `Default: ${scrubOutboundDashes(ctx.safeDefault)}`)
         : undefined;
     const action = [choices, fallback].filter(Boolean).join('\n') || undefined;
-    // Link trail after the "Sent from" footer so the human sentence stays at the top.
-    const trail = [footer, ...links].filter(Boolean);
     const parts = [];
     if (head)
         parts.push(head);
@@ -275,16 +355,22 @@ export function composeBroadcastMessage(ctx) {
             parts.push('');
         parts.push(action);
     }
-    if (trail.length) {
-        // Blank line before the footer block (iPhone "Sent from my iPhone" spacing).
+    if (footer) {
+        // Blank line before the "Sent from" footer (iPhone "Sent from my iPhone" spacing).
+        // The crumb/ticket links are inline (footer + prose) — never a trailing URL line.
         if (parts.length)
             parts.push('');
-        parts.push(trail.join('\n'));
+        parts.push(footer);
     }
     return parts.join('\n').trim();
 }
-/** The values a template may reference, resolved once per post. */
-function templateVars(ctx) {
+/**
+ * The values a template may reference, resolved once per post. `format` decides
+ * how `{message}` surfaces its links — Slack `mrkdwn` (labeled links) vs `plain`
+ * (the human sentence, no URLs). The scalar `{ticket_url}`/`{links}` vars are the
+ * raw URLs a custom `message:` template can place itself, so they are unaffected.
+ */
+function templateVars(ctx, format = 'plain') {
     return {
         title: ctx.title,
         text: ctx.text,
@@ -296,7 +382,7 @@ function templateVars(ctx) {
         session: ctx.session,
         level: ctx.level,
         links: ctx.links?.length ? ctx.links.join(' ') : undefined,
-        message: composeBroadcastMessage(ctx),
+        message: composeBroadcastMessage(ctx, format),
         block: ctx.blockId,
         class: ctx.class,
         cost: ctx.cost,
@@ -330,9 +416,14 @@ export function renderSinkArgv(template, ctx) {
     }
     return argv.length > 0 ? argv : undefined;
 }
-/** Render one channel-message template with the same fail-closed placeholder contract as argv. */
-export function renderSinkMessage(template, ctx) {
-    const vars = templateVars(ctx);
+/**
+ * Render one channel-message template with the same fail-closed placeholder
+ * contract as argv. `format` (Slack `mrkdwn` vs `plain`) flows into the shared
+ * `{message}` var so a Slack sink gets labeled links and an iMessage/owner sink
+ * gets the plain sentence.
+ */
+export function renderSinkMessage(template, ctx, format = 'plain') {
+    const vars = templateVars(ctx, format);
     let missing = false;
     const rendered = template.replace(PLACEHOLDER, (whole, key) => {
         const value = vars[key];
@@ -367,8 +458,12 @@ export function renderSinkMessage(template, ctx) {
  * A `channel:` sink is gated by the same `minLevel` rule as a `command:` sink —
  * one level check for both shapes, so a dry-run plan is truthful regardless of
  * which shape an operator's sink uses.
+ *
+ * `meta` is used only to resolve a channel name to its real provider for the
+ * mrkdwn/plain format decision (`notify.transports`), the same map delivery uses;
+ * it is optional so a test can plan without a config snapshot (identity mapping).
  */
-export function planFeedBroadcast(config, ctx) {
+export function planFeedBroadcast(config, ctx, meta) {
     if (!config)
         return [];
     const planned = [];
@@ -386,7 +481,14 @@ export function planFeedBroadcast(config, ctx) {
             // placeholder below).
             if (!isOwnerAlias(channel) && !sink.to?.trim())
                 continue;
-            const text = renderSinkMessage(sink.message ?? '{message}', ctx);
+            // Slack renders labeled links; every other channel (owner alias, iMessage,
+            // telegram, discord, mailbox, desktop) stays plain (PHNX-3698). The owner
+            // alias is deliberately plain even when it fans out to a Slack destination:
+            // it delivers ONE shared string to every channel in owner.policy.normal, so
+            // mrkdwn markup would corrupt a sibling iMessage copy. Keying on the
+            // resolved provider (not the raw name) matches what delivery does.
+            const provider = isOwnerAlias(channel) ? channel : resolveSinkProvider(channel, meta);
+            const text = renderSinkMessage(sink.message ?? '{message}', ctx, sinkMessageFormat(provider));
             if (!text)
                 continue;
             planned.push({

package/dist/lib/fleet-shared-repo-sync.d.ts

@@ -0,0 +1,36 @@
+export declare const FLEET_SHARED_REPO_SYNC_DEADLINE_MS = 45000;
+export declare const FLEET_SHARED_REPO_KILL_GRACE_MS = 250;
+export interface BoundedProcessResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface FleetSharedRepoSyncOptions {
+    userAgentsDir?: string;
+    device?: string;
+    timeoutMs?: number;
+    /** Test-only redirection for the untracked cross-process lock target. */
+    lockPath?: string;
+}
+export interface FleetSharedRepoSyncResult {
+    success: boolean;
+    committed: boolean;
+    pushed: boolean;
+    commit: string | null;
+    timedOut: boolean;
+    skipped: string | null;
+    error: string | null;
+}
+/** Run one real process asynchronously with a hard wall-clock/process-tree bound. */
+export declare function runBoundedProcess(command: string, args: string[], options: {
+    cwd: string;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<BoundedProcessResult>;
+/**
+ * Commit/pull/push this device's shared state under one cross-process lock.
+ * Callers publish their local fields first and consume peer fields only after
+ * this resolves successfully.
+ */
+export declare function syncFleetSharedStateRepo(options?: FleetSharedRepoSyncOptions): Promise<FleetSharedRepoSyncResult>;

package/dist/lib/fleet-shared-repo-sync.js

@@ -0,0 +1,333 @@
+/**
+ * Automatic transport for the non-secret fleet state stored in the user repo.
+ *
+ * Usage/auth services publish only their own conflict-free
+ * `devices/<device>/daemon-state.json` file. This module commits that one path,
+ * rebases the user repo, and pushes it so peer daemons can read the snapshot
+ * after their own fetch/rebase. Git runs asynchronously under one cross-process
+ * lock; every invocation has a wall-clock deadline and a timed-out process tree
+ * is terminated, including git's ssh child and its remote channel.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { fleetSharedStatePath } from './fleet-shared-state.js';
+import { ensureLockTarget } from './fs-atomic.js';
+import { logAndContinueOnLockCompromised } from './lock-compromise.js';
+import { machineId } from './session/sync/config.js';
+import { getDaemonDir, getUserAgentsDir } from './state.js';
+export const FLEET_SHARED_REPO_SYNC_DEADLINE_MS = 45_000;
+export const FLEET_SHARED_REPO_KILL_GRACE_MS = 250;
+const FLEET_SHARED_REPO_OUTPUT_MAX_BYTES = 1024 * 1024;
+const FLEET_SHARED_REPO_PUSH_ATTEMPTS = 3;
+const FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS = 5_000;
+function signalProcessTree(child, signal) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        // Windows has no process-group signal. taskkill is asynchronous here so a
+        // timeout path cannot replace one event-loop stall with another.
+        const killer = spawn('taskkill', ['/F', '/T', '/PID', String(pid)], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        killer.unref();
+        return;
+    }
+    try {
+        // The child is spawned detached on POSIX, so -pid reaches git plus ssh.
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Run one real process asynchronously with a hard wall-clock/process-tree bound. */
+export function runBoundedProcess(command, args, options) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        let overflow = false;
+        let killTimer = null;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({ code, stdout, stderr, timedOut });
+        };
+        const hardKill = () => {
+            signalProcessTree(child, 'SIGKILL');
+            if (process.platform === 'win32' && !killTimer) {
+                // taskkill owns the descendant cleanup; this fallback only guarantees
+                // the direct child's Promise settles if taskkill itself cannot run.
+                killTimer = setTimeout(() => {
+                    if (!settled) {
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch { /* already gone */ }
+                    }
+                }, FLEET_SHARED_REPO_KILL_GRACE_MS);
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (process.platform === 'win32') {
+                hardKill();
+                return;
+            }
+            signalProcessTree(child, 'SIGTERM');
+            killTimer = setTimeout(() => {
+                if (!settled)
+                    hardKill();
+            }, FLEET_SHARED_REPO_KILL_GRACE_MS);
+        }, Math.max(1, options.timeoutMs));
+        const append = (stream, chunk) => {
+            if (overflow)
+                return;
+            const value = String(chunk);
+            if (Buffer.byteLength(stdout) + Buffer.byteLength(stderr) + Buffer.byteLength(value) > FLEET_SHARED_REPO_OUTPUT_MAX_BYTES) {
+                overflow = true;
+                stderr += '\ngit output exceeded 1 MiB';
+                hardKill();
+                return;
+            }
+            if (stream === 'stdout')
+                stdout += value;
+            else
+                stderr += value;
+        };
+        child.stdout?.on('data', (chunk) => append('stdout', chunk));
+        child.stderr?.on('data', (chunk) => append('stderr', chunk));
+        child.on('error', (err) => {
+            stderr += err.message;
+            finish(null);
+        });
+        child.on('close', (code) => finish(code));
+    });
+}
+function failure(command, result) {
+    const detail = result.timedOut
+        ? `${command} timed out`
+        : result.stderr.trim() || result.stdout.trim() || `${command} exited ${result.code ?? 'without a status'}`;
+    return {
+        success: false,
+        committed: false,
+        pushed: false,
+        commit: null,
+        timedOut: result.timedOut,
+        skipped: null,
+        error: detail,
+    };
+}
+function isPushRace(result) {
+    const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    return text.includes('non-fast-forward') || text.includes('fetch first') || text.includes('[rejected]');
+}
+function createdAutostashObject(result) {
+    return `${result.stdout}\n${result.stderr}`.match(/created autostash:\s*([0-9a-f]+)/i)?.[1] ?? null;
+}
+function retainedAutostash(stashList, objectId) {
+    if (stashList.code === 0) {
+        const entries = stashList.stdout.trim().split('\n').filter(Boolean).map((line) => {
+            const [ref = '', hash = '', ...subject] = line.split('\t');
+            return { ref, hash, subject: subject.join('\t') };
+        });
+        const matched = objectId
+            ? entries.find((entry) => entry.hash.startsWith(objectId) || objectId.startsWith(entry.hash))
+            : entries.find((entry) => /autostash/i.test(entry.subject));
+        if (matched?.ref)
+            return { label: `${matched.ref} (${matched.hash.slice(0, 8)})`, ref: matched.ref };
+    }
+    return {
+        label: objectId ? `autostash object ${objectId}` : 'the retained autostash',
+        ref: null,
+    };
+}
+async function performFleetSharedRepoSync(root, device, timeoutMs) {
+    if (!fs.existsSync(path.join(root, '.git'))) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: `user store is not git-backed: ${root}`,
+            error: null,
+        };
+    }
+    const deadline = Date.now() + timeoutMs;
+    const git = async (args, reserveMs = 0) => {
+        const remaining = deadline - Date.now() - reserveMs;
+        if (remaining <= 0)
+            return { code: null, stdout: '', stderr: '', timedOut: true };
+        return runBoundedProcess('git', args, {
+            cwd: root,
+            timeoutMs: remaining,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+    };
+    const branchResult = await git(['branch', '--show-current']);
+    if (branchResult.code !== 0)
+        return failure('git branch --show-current', branchResult);
+    const branch = branchResult.stdout.trim();
+    if (!branch) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: null,
+            error: 'user store is on a detached HEAD',
+        };
+    }
+    const ownedFile = fleetSharedStatePath(device, root);
+    const relativeOwnedFile = path.relative(root, ownedFile).split(path.sep).join('/');
+    let committed = false;
+    if (fs.existsSync(ownedFile)) {
+        const status = await git(['status', '--porcelain=v1', '--', relativeOwnedFile]);
+        if (status.code !== 0)
+            return failure('git status', status);
+        if (status.stdout.trim()) {
+            const add = await git(['add', '--', relativeOwnedFile]);
+            if (add.code !== 0)
+                return failure('git add', add);
+            const commit = await git([
+                '-c', 'commit.gpgsign=false',
+                'commit', '--no-verify', '-m', `chore(devices): publish ${device} daemon state`,
+                '--', relativeOwnedFile,
+            ]);
+            if (commit.code !== 0)
+                return failure('git commit', commit);
+            committed = true;
+        }
+    }
+    for (let attempt = 1; attempt <= FLEET_SHARED_REPO_PUSH_ATTEMPTS; attempt++) {
+        const fetch = await git(['fetch', 'origin']);
+        if (fetch.code !== 0)
+            return { ...failure('git fetch', fetch), committed };
+        // Keep enough of the same wall-clock bound available to remove a botched
+        // autostash pop from the operator's live checkout before returning.
+        const rebase = await git(['rebase', '--autostash', `origin/${branch}`], FLEET_SHARED_REPO_REBASE_CLEANUP_RESERVE_MS);
+        if (rebase.code !== 0) {
+            // Rebase can leave control files behind even when the child was killed.
+            // Abort is bounded by the same overall deadline and never hides the cause.
+            await git(['rebase', '--abort']);
+            return { ...failure('git rebase', rebase), committed };
+        }
+        // `git rebase --autostash` exits zero when the rebase succeeds but applying
+        // the autostash conflicts. Never push or leave those conflict markers in
+        // the operator's real ~/.agents checkout. Git retains the original changes
+        // in the stash on this path, so reset only the failed pop to rebased HEAD.
+        const unmerged = await git(['ls-files', '--unmerged']);
+        if (unmerged.code !== 0)
+            return { ...failure('git ls-files --unmerged', unmerged), committed };
+        if (unmerged.stdout.trim()) {
+            const autostashObject = createdAutostashObject(rebase);
+            const reset = await git(['reset', '--hard', 'HEAD']);
+            const cleaned = await git(['ls-files', '--unmerged']);
+            const stashList = await git(['stash', 'list', '--format=%gd%x09%H%x09%gs']);
+            const stash = retainedAutostash(stashList, autostashObject);
+            if (reset.code !== 0 || cleaned.code !== 0 || cleaned.stdout.trim()) {
+                const cleanup = reset.code !== 0
+                    ? failure('git reset --hard HEAD', reset).error
+                    : cleaned.code !== 0
+                        ? failure('git ls-files --unmerged', cleaned).error
+                        : 'unmerged index entries remain after git reset --hard HEAD';
+                return {
+                    success: false,
+                    committed,
+                    pushed: false,
+                    commit: null,
+                    timedOut: reset.timedOut || cleaned.timedOut,
+                    skipped: null,
+                    error: `autostash pop conflicted; push refused, but cleanup failed: ${cleanup}. Original tracked changes remain safe in ${stash.label}`,
+                };
+            }
+            return {
+                success: false,
+                committed,
+                pushed: false,
+                commit: null,
+                timedOut: false,
+                skipped: null,
+                error: `autostash pop conflicted; push refused and the worktree was reset to rebased HEAD without conflict markers. Original tracked changes remain safe in ${stash.label}; inspect with ${stash.ref ? `git stash show -p ${stash.ref}` : 'git stash list'}`,
+            };
+        }
+        const push = await git(['push', '--', 'origin', branch]);
+        if (push.code === 0) {
+            const head = await git(['rev-parse', '--short=8', 'HEAD']);
+            return {
+                success: true,
+                committed,
+                pushed: committed || push.stdout.trim().length > 0 || push.stderr.includes('->'),
+                commit: head.code === 0 ? head.stdout.trim() : null,
+                timedOut: false,
+                skipped: null,
+                error: null,
+            };
+        }
+        if (attempt === FLEET_SHARED_REPO_PUSH_ATTEMPTS || !isPushRace(push)) {
+            return { ...failure('git push', push), committed };
+        }
+    }
+    throw new Error('unreachable fleet shared repo push loop');
+}
+/**
+ * Commit/pull/push this device's shared state under one cross-process lock.
+ * Callers publish their local fields first and consume peer fields only after
+ * this resolves successfully.
+ */
+export async function syncFleetSharedStateRepo(options = {}) {
+    const root = options.userAgentsDir ?? getUserAgentsDir();
+    const device = options.device ?? machineId();
+    const timeoutMs = options.timeoutMs ?? FLEET_SHARED_REPO_SYNC_DEADLINE_MS;
+    const lockPath = options.lockPath ?? path.join(getDaemonDir(), 'fleet-shared-repo-sync');
+    ensureLockTarget(lockPath, '');
+    let release = null;
+    try {
+        release = await lockfile.lock(lockPath, {
+            stale: Math.max(10_000, timeoutMs + 5_000),
+            retries: { retries: 20, factor: 1, minTimeout: 100, maxTimeout: 100 },
+            onCompromised: logAndContinueOnLockCompromised('fleet shared repo sync'),
+        });
+        return await performFleetSharedRepoSync(root, device, timeoutMs);
+    }
+    catch (err) {
+        return {
+            success: false,
+            committed: false,
+            pushed: false,
+            commit: null,
+            timedOut: false,
+            skipped: null,
+            error: err.message,
+        };
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch { /* compromised/already released */ }
+        }
+    }
+}

package/dist/lib/fleet-shared-state.d.ts

@@ -0,0 +1,38 @@
+import type { CachedUsageSnapshot } from './accounting/usage.js';
+export declare const FLEET_SHARED_STATE_VERSION = 1;
+export declare const FLEET_SHARED_STATE_FILE = "daemon-state.json";
+export type SharedAuthStatus = 'ready' | 'missing' | 'invalid';
+export interface FleetSharedDeviceState {
+    version: typeof FLEET_SHARED_STATE_VERSION;
+    device: string;
+    usage?: {
+        rows: Record<string, CachedUsageSnapshot>;
+    };
+    auth?: {
+        status: SharedAuthStatus;
+    };
+}
+export interface FleetSharedStatePatch {
+    usage?: FleetSharedDeviceState['usage'];
+    auth?: FleetSharedDeviceState['auth'];
+}
+export interface FleetSharedStateReadResult {
+    states: FleetSharedDeviceState[];
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
+}
+/** Path owned by one device in the conflict-free tracked device-doc tree. */
+export declare function fleetSharedStatePath(device: string, userAgentsDir?: string): string;
+/**
+ * Merge one daemon-owned field into this device's shared file under a real
+ * inter-process lock. Stable serialization avoids dirtying the user repo when
+ * neither usage nor auth state changed.
+ */
+export declare function updateFleetSharedDeviceState(device: string, patch: FleetSharedStatePatch, userAgentsDir?: string): {
+    changed: boolean;
+    path: string;
+};
+/** Read every valid peer-owned state file; malformed peers fail separately. */
+export declare function readFleetSharedDeviceStates(userAgentsDir?: string): FleetSharedStateReadResult;