runwork 0.9.1 → 0.9.3

package/dist/agents/__tests__/codex-stats.test.js

@@ -13,6 +13,12 @@ vi.mock('os', () => ({
 }));
 vi.mock('child_process', () => ({
     execFileSync: vi.fn(),
+    // detection.ts (transitively imported via codex.ts) wraps execFile through
+    // util.promisify; provide a callback-shaped stub so module load succeeds.
+    execFile: vi.fn((..._args) => {
+        const cb = _args[_args.length - 1];
+        cb(new Error('ENOENT'));
+    }),
 }));
 vi.mock('../../utils/sqlite.js', () => ({
     querySqlite: vi.fn(() => ''),

package/dist/agents/__tests__/detection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/__tests__/detection.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Force a Windows environment for Windows-only detection methods. The
+// `runAgentDetection` function bails out off Windows for `windows-appx` and
+// `windows-start-app`, so we have to pretend.
+vi.mock('os', async () => {
+    const actual = await vi.importActual('os');
+    return { ...actual, platform: vi.fn(() => 'win32') };
+});
+const execBehaviors = [];
+let defaultBehavior = { kind: 'success' };
+vi.mock('child_process', () => ({
+    // promisify(execFile) drives this: the last argument is always the
+    // (err, stdout, stderr) callback regardless of whether options are passed.
+    execFile: (...args) => {
+        const cb = args[args.length - 1];
+        const behavior = execBehaviors.shift() ?? defaultBehavior;
+        const finish = (b) => {
+            if (b.kind === 'success')
+                cb(null, '', '');
+            else if (b.kind === 'fail')
+                cb(new Error('exit 1'), '', '');
+        };
+        if (behavior.kind === 'delay') {
+            setTimeout(() => finish({ kind: behavior.result }), behavior.ms);
+        }
+        else {
+            finish(behavior);
+        }
+    },
+}));
+vi.mock('../../utils/which.js', () => ({
+    whichBinary: vi.fn((name) => (name === 'present-binary' ? `/usr/bin/${name}` : null)),
+}));
+import { runAgentDetection } from '../detection.js';
+beforeEach(() => {
+    vi.clearAllMocks();
+    execBehaviors.length = 0;
+    defaultBehavior = { kind: 'success' };
+});
+describe('runAgentDetection', () => {
+    it('reports binary detection via whichBinary', async () => {
+        expect(await runAgentDetection({ method: 'binary', target: 'present-binary' })).toBe(true);
+        expect(await runAgentDetection({ method: 'binary', target: 'missing-binary' })).toBe(false);
+    });
+    it('reports false when a windows-appx probe exits non-zero', async () => {
+        defaultBehavior = { kind: 'fail' };
+        expect(await runAgentDetection({ method: 'windows-appx', target: 'Some.Package' })).toBe(false);
+    });
+    it('reports true when any windows-appx probe succeeds', async () => {
+        // First two probes fail, third succeeds — the function should still
+        // return true because we union with Promise.all + .some(Boolean).
+        execBehaviors.push({ kind: 'fail' }, { kind: 'fail' }, { kind: 'success' });
+        expect(await runAgentDetection({ method: 'windows-appx', target: ['A', 'B', 'C'] })).toBe(true);
+    });
+    it('runs windows-appx probes in parallel (wall time ≈ slowest probe, not sum)', async () => {
+        // Each probe takes 80ms. Six probes serialized = ~480ms; parallel = ~80ms.
+        // Allow slack for CI noise but enough to catch a regression to sync execution.
+        defaultBehavior = { kind: 'delay', ms: 80, result: 'fail' };
+        const start = Date.now();
+        const result = await runAgentDetection({
+            method: 'windows-appx',
+            target: ['A', 'B', 'C', 'D', 'E', 'F'],
+        });
+        const elapsed = Date.now() - start;
+        expect(result).toBe(false);
+        expect(elapsed).toBeLessThan(300);
+    });
+    it('any combinator returns true on first hit', async () => {
+        expect(await runAgentDetection({
+            method: 'any',
+            target: [
+                { method: 'binary', target: 'missing-binary' },
+                { method: 'binary', target: 'present-binary' },
+            ],
+        })).toBe(true);
+    });
+    it('any combinator returns false when every probe misses', async () => {
+        expect(await runAgentDetection({
+            method: 'any',
+            target: [
+                { method: 'binary', target: 'missing-binary' },
+                { method: 'binary', target: 'also-missing' },
+            ],
+        })).toBe(false);
+    });
+});

package/dist/agents/__tests__/graceful-degradation.test.js

@@ -13,6 +13,12 @@ vi.mock('os', () => ({
 }));
 vi.mock('child_process', () => ({
     execFileSync: vi.fn(() => { throw new Error('ENOENT'); }),
+    // detection.ts wraps execFile via util.promisify; provide the callback
+    // shape so the import doesn't blow up even though no test here exercises it.
+    execFile: vi.fn((..._args) => {
+        const cb = _args[_args.length - 1];
+        cb(new Error('ENOENT'));
+    }),
 }));
 vi.mock('../../utils/sqlite.js', () => ({
     querySqlite: vi.fn(() => ''),

package/dist/agents/detection.d.ts

@@ -9,9 +9,10 @@
  */
 import type { AgentDetection } from './registry-data.js';
 /**
- * Synchronous detection — returns true when the agent is installed according
- * to its registry `detection` rules. Supports every method the desktop app
- * understands: `binary`, `path`, `windows-appx`, `windows-start-app`, and
- * nested `any` combinators. Windows-only methods return false off Windows.
+ * Detection — returns true when the agent is installed according to its
+ * registry `detection` rules. Supports `binary`, `path`, `windows-appx`,
+ * `windows-start-app`, and nested `any` combinators. PowerShell-backed
+ * Windows probes run in parallel so a multi-target `any { windows-appx }`
+ * pays one PowerShell startup, not N.
  */
-export declare function runAgentDetection(detection: AgentDetection): boolean;
+export declare function runAgentDetection(detection: AgentDetection): Promise<boolean>;

package/dist/agents/detection.js

@@ -7,12 +7,14 @@
  * Mirrors the desktop's agent-detection.ts logic but uses Node APIs instead
  * of Tauri plugins.
  */
-import { execFileSync } from 'child_process';
+import { execFile } from 'child_process';
 import { existsSync } from 'fs';
 import { homedir, platform } from 'os';
 import { isAbsolute, join } from 'path';
+import { promisify } from 'util';
 import { whichBinary } from '../utils/which.js';
 import { resolvePlatformString } from './registry.js';
+const execFileAsync = promisify(execFile);
 function isWindows() {
     return platform() === 'win32';
 }
@@ -22,9 +24,9 @@ function powershellQuote(value) {
 function toList(value) {
     return Array.isArray(value) ? value : [value];
 }
-function runPowerShell(script) {
+async function runPowerShell(script) {
     try {
-        execFileSync('powershell', ['-NoProfile', '-Command', script], { stdio: 'pipe' });
+        await execFileAsync('powershell', ['-NoProfile', '-Command', script]);
         return true;
     }
     catch {
@@ -39,33 +41,35 @@ function checkPath(target) {
         return existsSync(resolved);
     return existsSync(join(homedir(), resolved));
 }
-function checkWindowsAppxPackage(target) {
+async function checkWindowsAppxPackage(target) {
     if (!isWindows())
         return false;
-    for (const pkg of toList(target)) {
+    // Probe all candidate package names in parallel; resolve true on first hit.
+    const probes = toList(target).map((pkg) => {
         const script = `$p = Get-AppxPackage -Name ${powershellQuote(pkg)} -ErrorAction SilentlyContinue; if ($null -ne $p) { exit 0 } exit 1`;
-        if (runPowerShell(script))
-            return true;
-    }
-    return false;
+        return runPowerShell(script);
+    });
+    const results = await Promise.all(probes);
+    return results.some(Boolean);
 }
-function checkWindowsStartApp(target) {
+async function checkWindowsStartApp(target) {
     if (!isWindows())
         return false;
-    for (const pattern of toList(target)) {
+    const probes = toList(target).map((pattern) => {
         const script = `$a = Get-StartApps -Name ${powershellQuote(pattern)} -ErrorAction SilentlyContinue | Select-Object -First 1; if ($null -ne $a) { exit 0 } exit 1`;
-        if (runPowerShell(script))
-            return true;
-    }
-    return false;
+        return runPowerShell(script);
+    });
+    const results = await Promise.all(probes);
+    return results.some(Boolean);
 }
 /**
- * Synchronous detection — returns true when the agent is installed according
- * to its registry `detection` rules. Supports every method the desktop app
- * understands: `binary`, `path`, `windows-appx`, `windows-start-app`, and
- * nested `any` combinators. Windows-only methods return false off Windows.
+ * Detection — returns true when the agent is installed according to its
+ * registry `detection` rules. Supports `binary`, `path`, `windows-appx`,
+ * `windows-start-app`, and nested `any` combinators. PowerShell-backed
+ * Windows probes run in parallel so a multi-target `any { windows-appx }`
+ * pays one PowerShell startup, not N.
  */
-export function runAgentDetection(detection) {
+export async function runAgentDetection(detection) {
     switch (detection.method) {
         case 'binary': {
             const target = resolvePlatformString(detection.target);
@@ -77,12 +81,10 @@ export function runAgentDetection(detection) {
             return checkWindowsAppxPackage(detection.target);
         case 'windows-start-app':
             return checkWindowsStartApp(detection.target);
-        case 'any':
-            for (const probe of detection.target) {
-                if (runAgentDetection(probe))
-                    return true;
-            }
-            return false;
+        case 'any': {
+            const probes = await Promise.all(detection.target.map((p) => runAgentDetection(p)));
+            return probes.some(Boolean);
+        }
         default:
             return false;
     }

package/dist/agents/registry-data.d.ts

@@ -9,28 +9,10 @@
  * imports. Node-only path resolvers live next to this file in `./registry.ts`.
  */
 export type AgentCategory = 'cli' | 'ide' | 'desktop' | 'extension';
-/** Platform-specific string. Plain string = same on all platforms. */
-export type PlatformString = string | {
-    default?: string;
-    macos?: string;
-    windows?: string;
-    linux?: string;
-};
-/**
- * Detection strategy for an agent. Supports simple binary/path checks plus
- * richer Windows-specific methods and a nested `any` combinator used by the
- * desktop app to detect agents that ship as both GUI app and CLI binary.
- */
-export type AgentDetection = {
-    method: 'binary' | 'path';
-    target: PlatformString;
-} | {
-    method: 'windows-appx' | 'windows-start-app';
-    target: string | string[];
-} | {
-    method: 'any';
-    target: AgentDetection[];
-};
+export type { PlatformString, Detection, InstallableTool } from '../tools/types.js';
+import type { InstallableTool, Detection, PlatformString } from '../tools/types.js';
+/** @deprecated use `Detection` from ../tools/types — kept as alias for back-compat. */
+export type AgentDetection = Detection;
 export interface AgentLaunch {
     app?: {
         macos?: string;
@@ -70,19 +52,11 @@ export interface AgentManualSetup {
     showAfter?: ManualSetupSlot;
     downloadArtifact?: AgentManualSetupArtifact;
 }
-export interface AgentDefinition {
-    slug: string;
-    name: string;
+export interface AgentDefinition extends InstallableTool {
     aliases?: string[];
-    description: string;
     category: AgentCategory;
-    detection: AgentDetection;
     /** Desktop launch hints (GUI app name, CLI command) */
     launch?: AgentLaunch;
-    /** Logo identifier used by the desktop UI */
-    logo?: string;
-    /** Public download/install URL shown in the desktop onboarding */
-    downloadUrl?: string;
     /** Whether the CLI knows how to auto-install this agent */
     autoInstallable?: boolean;
     /** Skill file directories relative to $HOME (global) or project root (project) */

package/dist/agents/registry-data.js

@@ -316,7 +316,7 @@ const AGENT_REGISTRY = [
         mcpConfigKey: 'mcpServers',
     },
     // === Community agents (from skillshare targets.yaml) ===
-    { slug: 'antigravity', name: 'Antigravity', aliases: ['Antigravity (Google)'], description: "Google's Antigravity AI agent", category: 'cli', detection: { method: 'binary', target: 'antigravity' }, logo: 'antigravity', skillsPaths: { global: '.gemini/antigravity/skills', project: '.agent/skills' } },
+    { slug: 'antigravity', name: 'Antigravity', aliases: ['Antigravity (Google)'], description: "Google's Antigravity AI agent", category: 'cli', detection: { method: 'binary', target: 'antigravity' }, logo: 'antigravity', launch: { cli: 'antigravity' }, skillsPaths: { global: '.gemini/antigravity/skills', project: '.agent/skills' } },
     { slug: 'amp', name: 'Amp', description: 'AI coding agent by Sourcegraph', category: 'cli', detection: { method: 'binary', target: 'amp' }, skillsPaths: { global: '.config/agents/skills', project: '.agents/skills' } },
     { slug: 'adal', name: 'AdaL', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'adal' }, skillsPaths: { global: '.adal/skills', project: '.adal/skills' } },
     { slug: 'astrbot', name: 'AstrBot', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'astrbot' }, skillsPaths: { global: '.astrbot/data/skills', project: 'data/skills' } },
@@ -346,7 +346,7 @@ const AGENT_REGISTRY = [
     { slug: 'neovate', name: 'Neovate', description: 'AI coding agent for Neovim', category: 'extension', detection: { method: 'binary', target: 'neovate' }, skillsPaths: { global: '.neovate/skills', project: '.neovate/skills' } },
     { slug: 'omp', name: 'Oh My Pi', aliases: ['oh-my-pi'], description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'omp' }, skillsPaths: { global: '.omp/agent/skills', project: '.omp/skills' } },
     { slug: 'openclaw', name: 'OpenClaw', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'openclaw' }, skillsPaths: { global: '.openclaw/skills', project: 'skills' } },
-    { slug: 'opencode', name: 'OpenCode', description: 'Open-source AI coding agent', category: 'cli', detection: { method: 'binary', target: 'opencode' }, skillsPaths: { global: '.config/opencode/skills', project: '.opencode/skills' } },
+    { slug: 'opencode', name: 'OpenCode', description: 'Open-source AI coding agent', category: 'cli', detection: { method: 'binary', target: 'opencode' }, launch: { cli: 'opencode' }, skillsPaths: { global: '.config/opencode/skills', project: '.opencode/skills' } },
     { slug: 'openhands', name: 'OpenHands', description: 'Open-source AI coding agent', category: 'cli', detection: { method: 'binary', target: 'openhands' }, skillsPaths: { global: '.openhands/skills', project: '.openhands/skills' } },
     { slug: 'pi', name: 'Pi', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'pi' }, skillsPaths: { global: '.pi/agent/skills', project: '.pi/skills' } },
     { slug: 'pochi', name: 'Pochi', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'pochi' }, skillsPaths: { global: '.pochi/skills', project: '.pochi/skills' } },
@@ -358,7 +358,7 @@ const AGENT_REGISTRY = [
     { slug: 'trae-cn', name: 'Trae CN', description: 'ByteDance AI coding IDE (China)', category: 'ide', detection: { method: 'binary', target: 'trae-cn' }, skillsPaths: { global: '.trae-cn/skills', project: '.trae/skills' } },
     { slug: 'mistral-vibe', name: 'Mistral Vibe', aliases: ['vibe'], description: "Mistral's AI coding agent", category: 'cli', detection: { method: 'binary', target: 'vibe' }, skillsPaths: { global: '.vibe/skills', project: '.vibe/skills' } },
     { slug: 'verdent', name: 'Verdent', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'verdent' }, skillsPaths: { global: '.verdent/skills', project: '.verdent/skills' } },
-    { slug: 'warp', name: 'Warp AI', description: 'AI-powered terminal', category: 'cli', detection: { method: 'path', target: { macos: '/Applications/Warp.app', linux: '/usr/bin/warp-terminal' } }, skillsPaths: { global: '.agents/skills', project: '.agents/skills' } },
+    { slug: 'warp', name: 'Warp Terminal', aliases: ['Warp AI'], description: 'AI-powered terminal', category: 'cli', detection: { method: 'path', target: { macos: '/Applications/Warp.app', linux: '/usr/bin/warp-terminal' } }, launch: { app: { macos: 'Warp', windows: 'Warp' } }, skillsPaths: { global: '.agents/skills', project: '.agents/skills' } },
     { slug: 'witsy', name: 'Witsy', description: 'AI coding agent', category: 'cli', detection: { method: 'binary', target: 'witsy' }, skillsPaths: { global: '.agents/skills', project: '.agents/skills' } },
     { slug: 'xcode-claude', name: 'Xcode Claude', description: 'Claude integration for Xcode', category: 'extension', detection: { method: 'path', target: { macos: 'Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig' } }, logo: 'claude', skillsPaths: { global: 'Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills', project: '.claude/skills' } },
     { slug: 'xcode-codex', name: 'Xcode Codex', description: 'Codex integration for Xcode', category: 'extension', detection: { method: 'path', target: { macos: 'Library/Developer/Xcode/CodingAssistant/codex' } }, logo: 'openai', skillsPaths: { global: 'Library/Developer/Xcode/CodingAssistant/codex/skills', project: '.codex/skills' } },

package/dist/commands/__tests__/sync-redetect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/sync-redetect.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('../../agents/detect.js', () => ({
+    detectAgents: vi.fn(),
+    // getAdapterBySlug is imported by sync.ts at module load; stub it so the
+    // import graph resolves without dragging in real adapter side-effects.
+    getAdapterBySlug: vi.fn(() => undefined),
+}));
+import { detectAgents } from '../../agents/detect.js';
+import { shouldRedetect, refreshConfiguredAgents, REDETECT_TTL_MS, } from '../sync.js';
+const baseOpts = {
+    dryRun: false,
+    pullOnly: false,
+    yes: true,
+};
+function makeState(overrides = {}) {
+    return {
+        workspaceId: 'ws-1',
+        workspaceName: 'Test',
+        configuredAgents: ['claude-code'],
+        scope: 'user',
+        lastSyncAt: '',
+        mcpServers: [],
+        skills: [],
+        skillHashes: {},
+        lastDetectedAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+function fakeAdapter(slug) {
+    return {
+        name: slug,
+        slug,
+        detect: async () => true,
+        writeMcpServers: async () => { },
+        writeSkills: async () => { },
+        writeInstructionHint: async () => { },
+        supportsSkills: () => false,
+        supportsMcpScope: () => false,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe('shouldRedetect', () => {
+    it('returns true when --redetect is passed even on fresh state', () => {
+        expect(shouldRedetect(makeState(), { ...baseOpts, redetect: true })).toBe(true);
+    });
+    it('returns true when configuredAgents is empty (recovery)', () => {
+        expect(shouldRedetect(makeState({ configuredAgents: [] }), baseOpts)).toBe(true);
+    });
+    it('returns true when lastDetectedAt is missing (first sync)', () => {
+        expect(shouldRedetect(makeState({ lastDetectedAt: undefined }), baseOpts)).toBe(true);
+    });
+    it('returns true when lastDetectedAt is unparseable (corrupt state)', () => {
+        expect(shouldRedetect(makeState({ lastDetectedAt: 'not-a-date' }), baseOpts)).toBe(true);
+    });
+    it('returns true when lastDetectedAt is older than the TTL', () => {
+        const stale = new Date(Date.now() - REDETECT_TTL_MS - 1000).toISOString();
+        expect(shouldRedetect(makeState({ lastDetectedAt: stale }), baseOpts)).toBe(true);
+    });
+    it('returns false when lastDetectedAt is fresh (within TTL)', () => {
+        const fresh = new Date(Date.now() - 60_000).toISOString();
+        expect(shouldRedetect(makeState({ lastDetectedAt: fresh }), baseOpts)).toBe(false);
+    });
+});
+describe('refreshConfiguredAgents', () => {
+    it('appends newly-detected agents and returns the diff', async () => {
+        vi.mocked(detectAgents).mockResolvedValue([
+            fakeAdapter('claude-code'),
+            fakeAdapter('codex'),
+            fakeAdapter('cursor'),
+        ]);
+        const state = makeState({ configuredAgents: ['claude-code'], lastDetectedAt: undefined });
+        const added = await refreshConfiguredAgents(state);
+        expect(added.sort()).toEqual(['codex', 'cursor']);
+        expect(state.configuredAgents.sort()).toEqual(['claude-code', 'codex', 'cursor']);
+        expect(state.lastDetectedAt).toBeTruthy();
+    });
+    it('returns empty diff and stamps lastDetectedAt when nothing new is found', async () => {
+        vi.mocked(detectAgents).mockResolvedValue([fakeAdapter('claude-code')]);
+        const state = makeState({ configuredAgents: ['claude-code'], lastDetectedAt: undefined });
+        const added = await refreshConfiguredAgents(state);
+        expect(added).toEqual([]);
+        expect(state.configuredAgents).toEqual(['claude-code']);
+        expect(state.lastDetectedAt).toBeTruthy();
+    });
+    it('never removes agents that are no longer detected', async () => {
+        // A transient PATH glitch or temporarily-unmounted disk shouldn't wipe
+        // an agent the user explicitly configured. Removal is opt-in via setup.
+        vi.mocked(detectAgents).mockResolvedValue([fakeAdapter('claude-code')]);
+        const state = makeState({ configuredAgents: ['claude-code', 'codex', 'cursor'] });
+        const added = await refreshConfiguredAgents(state);
+        expect(added).toEqual([]);
+        expect(state.configuredAgents.sort()).toEqual(['claude-code', 'codex', 'cursor']);
+    });
+});

package/dist/commands/dev.js

@@ -35,6 +35,65 @@ function readConfig() {
     }
     return JSON.parse(readFileSync('.runwork.json', 'utf-8'));
 }
+// Files the CLI cannot function without and which the user did not author.
+// `.runwork.json` is the local app identity; `blueprint.json` is the app's
+// canonical feature definition; `.gitignore` keeps caches out of git. If a
+// sync from the remote silently removes any of these (which has happened
+// when a server-side agent commits with a stale index — see
+// worker/agents/git/git.ts), restoring from a pre-sync snapshot keeps the
+// project usable and unblocks `runwork deploy`.
+const CRITICAL_FILES = ['.runwork.json', 'blueprint.json', '.gitignore'];
+function snapshotCriticalFiles(cwd) {
+    const snapshots = [];
+    for (const rel of CRITICAL_FILES) {
+        const abs = join(cwd, rel);
+        if (!existsSync(abs))
+            continue;
+        try {
+            snapshots.push({ path: rel, contents: readFileSync(abs, 'utf-8') });
+        }
+        catch {
+            // Best-effort: skip unreadable files.
+        }
+    }
+    return snapshots;
+}
+function restoreMissingCriticalFiles(cwd, snapshots) {
+    const restored = [];
+    for (const snap of snapshots) {
+        const abs = join(cwd, snap.path);
+        if (existsSync(abs))
+            continue;
+        try {
+            writeFileSync(abs, snap.contents, 'utf-8');
+            restored.push(snap.path);
+        }
+        catch {
+            // Best-effort: skip files we cannot write back.
+        }
+    }
+    return restored;
+}
+function commitAndPushRestoredFiles(cwd, files) {
+    if (files.length === 0)
+        return false;
+    try {
+        execFileSync('git', ['add', '--', ...files], { cwd, stdio: 'pipe' });
+        execFileSync('git', ['commit', '-m', 'chore: restore critical files removed by sync'], { cwd, stdio: 'pipe' });
+    }
+    catch {
+        return false;
+    }
+    try {
+        execFileSync('git', ['push', 'runwork', 'main'], { cwd, stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        // Push failures are non-fatal: the local copy is restored, and the
+        // restoration commit will be pushed with the next auto-sync cycle.
+        return false;
+    }
+}
 export async function execDev(options) {
     const useJson = options?.json ?? false;
     const config = readConfig();
@@ -108,7 +167,26 @@ export async function execDev(options) {
     // Sync
     if (!useJson)
         console.log(dim('Syncing...'));
+    const criticalSnapshot = snapshotCriticalFiles(cwd);
     const syncResult = syncWithRemote(cwd);
+    const restoredCriticalFiles = restoreMissingCriticalFiles(cwd, criticalSnapshot);
+    if (restoredCriticalFiles.length > 0) {
+        const pushed = commitAndPushRestoredFiles(cwd, restoredCriticalFiles);
+        if (useJson) {
+            jsonLine({
+                event: 'sync_restored_critical_files',
+                files: restoredCriticalFiles,
+                pushed,
+                timestamp: ts(),
+            });
+        }
+        else {
+            console.warn(yellow(`  Sync removed critical file(s); restored: ${restoredCriticalFiles.join(', ')}`));
+            if (!pushed) {
+                console.warn(dim('  Restoration committed locally but not pushed; will retry on next auto-sync.'));
+            }
+        }
+    }
     if (useJson) {
         jsonLine({ event: 'startup', phase: 'sync', status: syncResult.status, pushed: syncResult.pushed, timestamp: ts() });
         if (syncResult.status === 'sync-failed') {

package/dist/commands/setup.js

@@ -110,7 +110,9 @@ export const setupCommand = new Command('setup')
         const chosen = await promptSelect('Configure for:', scopeChoices);
         scope = chosen.value;
     }
-    // 5. Save setup state (minimal, sync populates the rest)
+    // 5. Save setup state (minimal, sync populates the rest).
+    // `lastDetectedAt` is stamped now so the immediate post-setup sync
+    // doesn't waste time re-running detection that just ran.
     const state = {
         workspaceId,
         workspaceName: workspaceName || '',
@@ -121,6 +123,7 @@ export const setupCommand = new Command('setup')
         mcpServers: [],
         skills: [],
         skillHashes: {},
+        lastDetectedAt: new Date().toISOString(),
     };
     const scopes = scope === 'both' ? ['project', 'user'] : [scope];
     for (const s of scopes) {

package/dist/commands/sync.d.ts

@@ -6,6 +6,32 @@ export interface SyncOptions {
     prefer?: 'local' | 'remote';
     yes: boolean;
     verbose?: boolean;
+    /**
+     * Force a fresh agent-installation detection pass and union newly-found
+     * agents into `state.configuredAgents`. Without this, sync only re-detects
+     * when state is empty or `lastDetectedAt` is older than REDETECT_TTL_MS.
+     */
+    redetect?: boolean;
 }
+/**
+ * How long a detection result stays trusted before sync re-runs detection
+ * on its own. Detection is cheap on macOS/Linux but pays a PowerShell
+ * waterfall on Windows, so we cache for a day. Users who just installed
+ * a new agent can shortcut the wait via `--redetect` (or the desktop's
+ * "Rescan" button, which forwards the flag).
+ */
+export declare const REDETECT_TTL_MS: number;
+/**
+ * Decide whether to re-run installation detection for this sync. We always
+ * re-detect on explicit user request, on first sync (no timestamp yet), when
+ * setup ended up with zero agents (recovery), or after the TTL has lapsed.
+ */
+export declare function shouldRedetect(state: SetupState, opts: SyncOptions): boolean;
+/**
+ * Detect installed agents and merge any new slugs into `state.configuredAgents`.
+ * Never removes agents — a transient PATH glitch shouldn't wipe the setup.
+ * Returns the slugs that were newly added (for logging).
+ */
+export declare function refreshConfiguredAgents(state: SetupState): Promise<string[]>;
 export declare function syncFromState(state: SetupState, statePath: string, credentials: Credentials, opts: SyncOptions): Promise<void>;
 export declare const syncCommand: Command;