runwork 0.14.0 → 0.15.0

package/dist/__tests__/install-scripts.test.js

@@ -165,6 +165,39 @@ describe('install.sh (end-to-end)', () => {
         const defaultBinary = join(workDir, '.runwork', 'bin', 'runwork');
         expect(existsSync(defaultBinary)).toBe(true);
     });
+    it('persists ~/.runwork/bin to a shell profile, idempotently, on a default install', async () => {
+        const linkDir = join(workDir, 'link');
+        const exportLine = 'export PATH="$HOME/.runwork/bin:$PATH"';
+        const marker = '# Added by Runwork CLI installer';
+        const profiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((p) => join(workDir, p));
+        const read = (p) => (existsSync(p) ? readFileSync(p, 'utf-8') : '');
+        // First install with the default install dir ($HOME/.runwork/bin) triggers
+        // PATH persistence.
+        const r1 = await runInstallSh(envFor({ RUNWORK_BIN_LINK_DIR: linkDir }));
+        expect(r1.status, `installer failed:\n${r1.stdout}\n${r1.stderr}`).toBe(0);
+        const written = profiles.filter((p) => read(p).includes(exportLine));
+        expect(written.length, 'expected the export line in at least one profile').toBeGreaterThan(0);
+        expect(profiles.some((p) => read(p).includes(marker))).toBe(true);
+        // Re-running must NOT append a second time (guarded on .runwork/bin).
+        const r2 = await runInstallSh(envFor({ RUNWORK_BIN_LINK_DIR: linkDir }));
+        expect(r2.status).toBe(0);
+        for (const p of written) {
+            const occurrences = read(p).split('.runwork/bin').length - 1;
+            expect(occurrences, `profile ${p} should reference .runwork/bin exactly once`).toBe(1);
+        }
+    });
+    it('does NOT touch shell profiles when a custom RUNWORK_INSTALL_DIR is used', async () => {
+        const result = await runInstallSh(envFor({
+            RUNWORK_INSTALL_DIR: join(workDir, 'install'),
+            RUNWORK_BIN_LINK_DIR: join(workDir, 'link'),
+        }));
+        expect(result.status).toBe(0);
+        const profiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((p) => join(workDir, p));
+        for (const p of profiles) {
+            if (existsSync(p))
+                expect(readFileSync(p, 'utf-8')).not.toContain('.runwork/bin');
+        }
+    });
     it('aborts on sha256 mismatch and leaves the install directory untouched', async () => {
         // Tamper with the archive the server is about to serve.
         writeFileSync(archivePath, Buffer.from('tampered payload'));

package/dist/agents/__tests__/chatgpt-registry.test.d.ts

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

package/dist/agents/__tests__/chatgpt-registry.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { getAgent, getAgentFamily, getFamilyAgents, isConnectOnlyAgent, isWebAgent, } from '../registry-data.js';
+describe('ChatGPT registry entries', () => {
+    it('registers both Web and Desktop entries', () => {
+        const web = getAgent('chatgpt');
+        const app = getAgent('chatgpt-app');
+        expect(web).toBeDefined();
+        expect(app).toBeDefined();
+        expect(web?.category).toBe('web');
+        expect(app?.category).toBe('desktop');
+        expect(web?.firstClass).toBe(true);
+        expect(app?.firstClass).toBe(true);
+    });
+    it('treats Web entry as always-available with a URL launch', () => {
+        const web = getAgent('chatgpt');
+        expect(web?.detection).toEqual({ method: 'always' });
+        expect(web?.launch?.url).toContain('chatgpt.com');
+        expect(isWebAgent('chatgpt')).toBe(true);
+        expect(isWebAgent('chatgpt-app')).toBe(false);
+    });
+    it('marks both entries connect-only (no local config paths)', () => {
+        for (const slug of ['chatgpt', 'chatgpt-app']) {
+            const agent = getAgent(slug);
+            expect(isConnectOnlyAgent(agent)).toBe(true);
+            expect(agent?.skillsPaths).toBeUndefined();
+            expect(agent?.mcpConfigPath).toBeUndefined();
+            expect(agent?.instructionFile).toBeUndefined();
+        }
+    });
+    it('does not mark file-backed agents as connect-only', () => {
+        expect(isConnectOnlyAgent(getAgent('claude-code'))).toBe(false);
+        expect(isConnectOnlyAgent(getAgent('codex'))).toBe(false);
+    });
+    it('groups both entries under one family', () => {
+        expect(getAgentFamily('chatgpt')).toBe('chatgpt');
+        expect(getAgentFamily('chatgpt-app')).toBe('chatgpt');
+        const family = getFamilyAgents('chatgpt').map((a) => a.slug).sort();
+        expect(family).toEqual(['chatgpt', 'chatgpt-app']);
+    });
+    it('falls back to the slug as family for standalone agents', () => {
+        expect(getAgentFamily('claude-code')).toBe('claude-code');
+        expect(getFamilyAgents('claude-code').map((a) => a.slug)).toEqual(['claude-code']);
+    });
+    it('provides team/personal manual-setup variants and a copyable MCP URL', () => {
+        for (const slug of ['chatgpt', 'chatgpt-app']) {
+            const setup = getAgent(slug)?.manualSetup;
+            expect(setup?.showAfter).toBe('connecting');
+            expect(setup?.copyValue?.token).toBe('{mcpUrl}');
+            const keys = setup?.variants?.map((v) => v.key).sort();
+            expect(keys).toEqual(['personal', 'team']);
+            // Every variant carries at least one step.
+            for (const variant of setup?.variants ?? []) {
+                expect(variant.steps.length).toBeGreaterThan(0);
+            }
+        }
+    });
+    it('uses url-prompt resume for connect-only ChatGPT entries', () => {
+        expect(getAgent('chatgpt')?.resumeCapability?.mode).toBe('url-prompt');
+        expect(getAgent('chatgpt-app')?.resumeCapability?.mode).toBe('url-prompt');
+    });
+});

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

@@ -83,4 +83,7 @@ describe('runAgentDetection', () => {
             ],
         })).toBe(false);
     });
+    it('always method reports true without any local probe (web-only agents)', async () => {
+        expect(await runAgentDetection({ method: 'always' })).toBe(true);
+    });
 });

package/dist/agents/detection.js

@@ -85,6 +85,9 @@ export async function runAgentDetection(detection) {
             const probes = await Promise.all(detection.target.map((p) => runAgentDetection(p)));
             return probes.some(Boolean);
         }
+        case 'always':
+            // Web-only agents have no local footprint; always treated as available.
+            return true;
         default:
             return false;
     }

package/dist/agents/intro-skill.js

@@ -300,14 +300,14 @@ export function generateIntroSkill(ctx) {
     lines.push('| `runwork info --json` | Full workspace and app context |');
     lines.push('| `runwork init my-app` | Create a new app |');
     lines.push('| `runwork dev` | Start local development (watches files, syncs automatically) |');
-    lines.push('| `runwork deploy` | Deploy to production |');
+    lines.push('| `runwork deploy` | Deploy to production (`--detach` runs in the background to survive shell timeouts; `runwork deploy --status` polls the result) |');
     lines.push('| `runwork entities list` | Browse data across apps |');
     lines.push('| `runwork entities records <name>` | Query entity records |');
     lines.push('| `runwork workflows trigger <name>` | Trigger a workflow |');
     lines.push('| `runwork integrations call <id> <method> <path>` | Call an integration API |');
     lines.push('| `runwork integrations search <query>` | Search 3,200+ available integrations |');
     lines.push('| `runwork logs` | View app logs |');
-    lines.push('| `runwork doctor` | Check system health |');
+    lines.push('| `runwork doctor` | Check system health (`--fix` auto-remediates git auth/remote; `--check <names>` scopes output) |');
     lines.push('| `runwork setup` | Set up workspace connection and sync to agents |');
     lines.push('| `runwork sync` | Sync skills, MCP servers, and settings to local agents |');
     lines.push('');
@@ -323,6 +323,8 @@ export function generateIntroSkill(ctx) {
     lines.push('');
     lines.push('> By default, `runwork init` scaffolds into `~/.runwork/apps/<slug>` so every app has a predictable home. Pass `--here` to scaffold in the current directory instead.');
     lines.push('');
+    lines.push('> Clone/init into a normal working directory (e.g. under your home folder). Some sandboxed "outputs" mounts disallow the unlink operations git uses for pack files, which can corrupt the repo ("unable to unlink \'.git/objects/pack/...\': Operation not permitted"). If you hit that, switch to a standard path.');
+    lines.push('');
     lines.push('**CLI development workflow:**');
     lines.push('1. `runwork init my-app` -- scaffold the app (created at `~/.runwork/apps/my-app`)');
     lines.push('2. `cd ~/.runwork/apps/my-app` -- enter the app directory');
@@ -385,7 +387,7 @@ export function generateIntroSkill(ctx) {
     lines.push('- **Connect workspace:** `runwork login` then `runwork setup`');
     lines.push('- **Connect an integration:** Visit the workspace settings in the web dashboard at https://runwork.ai, or use `runwork integrations search <query>` to find services');
     lines.push('- **Web dashboard:** https://runwork.ai for visual management of everything');
-    lines.push('- **Troubleshoot:** `runwork doctor` checks system health; `runwork logs` shows app output');
+    lines.push('- **Troubleshoot:** `runwork doctor` checks system health (`runwork doctor --fix` auto-repairs git auth and the runwork remote); `runwork logs` shows app output');
     lines.push('');
     // References
     lines.push('### References');

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

@@ -8,7 +8,7 @@
  * Keep this file browser-safe: no `os`, `path`, `fs`, or other Node-only
  * imports. Node-only path resolvers live next to this file in `./registry.ts`.
  */
-export type AgentCategory = 'cli' | 'ide' | 'desktop' | 'extension';
+export type AgentCategory = 'cli' | 'ide' | 'desktop' | 'extension' | 'web';
 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. */
@@ -21,6 +21,13 @@ export interface AgentLaunch {
     };
     cli?: string;
     cliAcceptsPrompt?: boolean;
+    /**
+     * Web/URL launch target opened in the default browser. `{prompt}` is
+     * substituted with a URL-encoded prompt (e.g. ChatGPT's `?prompt=`), or
+     * stripped when no prompt is supplied. Used by web-only agents and as the
+     * fallback for desktop agents whose app is not installed.
+     */
+    url?: string;
 }
 export interface AgentQuickStart {
     launchHint?: string;
@@ -44,6 +51,28 @@ export interface AgentManualSetupArtifact {
 }
 /** Where a manual-setup step is inserted in the onboarding journey. */
 export type ManualSetupSlot = 'installation' | 'connecting' | 'try-it';
+/**
+ * A plan-conditional variant of a manual-setup checklist. When an agent's
+ * connector setup differs by account plan (e.g. ChatGPT Team vs Personal),
+ * each variant carries its own steps; the onboarding UI selects the variant
+ * matching the workspace's stored plan. Agents without plan branching omit
+ * `variants` and use the flat `steps`.
+ */
+export interface AgentManualSetupVariant {
+    key: 'team' | 'personal';
+    label: string;
+    title?: string;
+    steps: ManualSetupStep[];
+}
+/**
+ * A copy-to-clipboard value surfaced alongside the manual-setup steps. The
+ * onboarding UI substitutes `token` with a real value (e.g. `{mcpUrl}` →
+ * the workspace MCP URL) before rendering the copy control.
+ */
+export interface AgentManualSetupCopyValue {
+    label: string;
+    token: '{mcpUrl}';
+}
 export interface AgentManualSetup {
     title: string;
     steps: ManualSetupStep[];
@@ -51,6 +80,10 @@ export interface AgentManualSetup {
     /** Where in the journey to show this step. Defaults to 'try-it'. */
     showAfter?: ManualSetupSlot;
     downloadArtifact?: AgentManualSetupArtifact;
+    /** Plan-conditional step lists. When present, the UI renders the variant matching the workspace plan instead of `steps`. */
+    variants?: AgentManualSetupVariant[];
+    /** A value the user copies into the agent during setup (e.g. the workspace MCP URL). */
+    copyValue?: AgentManualSetupCopyValue;
 }
 /**
  * How a recipient can resume a shared conversation locally in this agent.
@@ -72,12 +105,18 @@ export interface AgentManualSetup {
  *                       paste-prompt path. Used for walled-garden agents like
  *                       Microsoft Copilot or Claude Desktop Chat mode.
  *
+ *   - 'url-prompt'      Open the agent's `launch.url` (or app) with a prefilled
+ *                       prompt that instructs the agent to fetch and continue
+ *                       the shared conversation via Runwork's MCP tools. Used by
+ *                       connect-only agents (ChatGPT) that have MCP access but no
+ *                       local session files to drop into.
+ *
  * Bundle placement logic (which directory, which filename) is per-agent and
  * lives in the resume command implementation, not here. This data field stays
  * declarative.
  */
 export interface AgentResumeCapability {
-    mode: 'cli-resume' | 'file-drop-only' | 'unsupported';
+    mode: 'cli-resume' | 'file-drop-only' | 'unsupported' | 'url-prompt';
     /** Bundle format this agent reads natively (must match a bundle's `format`). */
     nativeBundleFormat?: 'claude-jsonl' | 'codex-rollout' | string;
     /** Template for the resume command (cli-resume only). `{uuid}` is substituted with the share's session id. */
@@ -88,6 +127,13 @@ export interface AgentResumeCapability {
 export interface AgentDefinition extends InstallableTool {
     aliases?: string[];
     category: AgentCategory;
+    /**
+     * Family identifier grouping multiple entries that share one account/
+     * connector/OAuth identity (e.g. `chatgpt` + `chatgpt-app` → 'chatgpt').
+     * Drives the shared plan toggle, connect-step dedup, and family-level
+     * adoption. Undefined for standalone agents.
+     */
+    family?: string;
     /** Desktop launch hints (GUI app name, CLI command) */
     launch?: AgentLaunch;
     /** Whether the CLI knows how to auto-install this agent */
@@ -127,6 +173,17 @@ export declare function getAgentsByCategory(category: AgentCategory): AgentDefin
 export declare function isCLIAgent(slug: string): boolean;
 export declare function isIDEAgent(slug: string): boolean;
 export declare function isDesktopAgent(slug: string): boolean;
+export declare function isWebAgent(slug: string): boolean;
+/**
+ * Connect-only agents have no local footprint to write: no skills directory,
+ * no MCP config file, no instruction file. The connector lives in the user's
+ * account (e.g. ChatGPT). `runwork sync` skips these for all local writes.
+ */
+export declare function isConnectOnlyAgent(agent: AgentDefinition | undefined): boolean;
+/** Family identifier for an agent (e.g. 'chatgpt' for both ChatGPT entries), or its slug when standalone. */
+export declare function getAgentFamily(slug: string): string | undefined;
+/** All agents sharing the given family identifier. */
+export declare function getFamilyAgents(family: string): AgentDefinition[];
 /** Alias of {@link getAgent} kept for backward compatibility with CLI callers. */
 export declare const getRegistryAgent: typeof getAgent;
 /** Alias of {@link getAgents} kept for backward compatibility with CLI callers. */

package/dist/agents/registry-data.js

@@ -246,6 +246,158 @@ const AGENT_REGISTRY = [
             ],
         },
     },
+    {
+        // ChatGPT Web. Connect-only: no local files. Shares one account/connector/
+        // OAuth identity with `chatgpt-app` (family: 'chatgpt'). Launches in the
+        // browser; chatgpt.com supports `?prompt=` for open + resume.
+        slug: 'chatgpt',
+        name: 'ChatGPT (Web)',
+        aliases: ['ChatGPT'],
+        description: "OpenAI's ChatGPT in the browser, connected to your workspace via MCP",
+        category: 'web',
+        family: 'chatgpt',
+        detection: { method: 'always' },
+        launch: { url: 'https://chatgpt.com/?prompt={prompt}' },
+        logo: 'openai',
+        downloadUrl: 'https://chatgpt.com',
+        firstClass: true,
+        resumeCapability: {
+            mode: 'url-prompt',
+            manualOpenHint: 'Opens ChatGPT with a prompt that fetches and continues the shared conversation via your Runwork workspace tools.',
+        },
+        quickStart: {
+            launchHint: 'Open chatgpt.com',
+            examplePrompts: [
+                "What can my team's Runwork workspace do?",
+                "Check my team's recent activity",
+            ],
+        },
+        manualSetup: {
+            title: 'Connect Runwork in ChatGPT',
+            showAfter: 'connecting',
+            copyValue: { label: 'Workspace MCP URL', token: '{mcpUrl}' },
+            // Flat steps mirror the 'personal' variant as a safe fallback when no
+            // plan is resolved. The onboarding UI prefers `variants` by plan.
+            steps: [
+                { id: 'open', label: 'Open chatgpt.com and sign in' },
+                { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+            ],
+            variants: [
+                {
+                    key: 'team',
+                    label: 'Team / Enterprise',
+                    title: 'Connect the Runwork app in ChatGPT',
+                    steps: [
+                        { id: 'open', label: 'Open chatgpt.com and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'find', label: 'Find the Runwork app published by your workspace admin and open it' },
+                        { id: 'connect', label: 'Click Connect and complete the OAuth sign-in to authorize Runwork' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+                {
+                    key: 'personal',
+                    label: 'Personal',
+                    title: 'Create the Runwork connector in ChatGPT',
+                    steps: [
+                        { id: 'open', label: 'Open chatgpt.com and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                        { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                        { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                        { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                        { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+            ],
+        },
+    },
+    {
+        // ChatGPT Desktop app. Connect-only (no local files); shares the same
+        // account/connector/OAuth identity as `chatgpt` Web. Launches the app,
+        // falling back to the web URL when the app is not installed.
+        slug: 'chatgpt-app',
+        name: 'ChatGPT Desktop',
+        description: "OpenAI's ChatGPT desktop app, connected to your workspace via MCP",
+        category: 'desktop',
+        family: 'chatgpt',
+        detection: {
+            method: 'any',
+            target: [
+                { method: 'path', target: { macos: '/Applications/ChatGPT.app' } },
+                { method: 'windows-appx', target: 'OpenAI.ChatGPT' },
+            ],
+        },
+        launch: { app: { macos: 'ChatGPT', windows: 'ChatGPT' }, url: 'https://chatgpt.com/?prompt={prompt}' },
+        logo: 'openai',
+        downloadUrl: 'https://chatgpt.com/download',
+        firstClass: true,
+        resumeCapability: {
+            mode: 'url-prompt',
+            manualOpenHint: 'Opens ChatGPT with a prompt that fetches and continues the shared conversation via your Runwork workspace tools.',
+        },
+        quickStart: {
+            launchHint: 'Open the ChatGPT desktop app',
+            examplePrompts: [
+                "What can my team's Runwork workspace do?",
+                "Check my team's recent activity",
+            ],
+        },
+        manualSetup: {
+            title: 'Connect Runwork in ChatGPT',
+            showAfter: 'connecting',
+            copyValue: { label: 'Workspace MCP URL', token: '{mcpUrl}' },
+            steps: [
+                { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                { id: 'open-web', label: 'Connectors are created on chatgpt.com: open it in your browser and sign in' },
+                { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                { id: 'confirm', label: 'Open the ChatGPT desktop app and, in a new chat, ask "Do you have access to Runwork tools?" to confirm' },
+            ],
+            variants: [
+                {
+                    key: 'team',
+                    label: 'Team / Enterprise',
+                    title: 'Connect the Runwork app in ChatGPT',
+                    steps: [
+                        { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                        { id: 'open', label: 'Open the ChatGPT desktop app and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'find', label: 'Find the Runwork app published by your workspace admin and open it' },
+                        { id: 'connect', label: 'Click Connect and complete the OAuth sign-in to authorize Runwork' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+                {
+                    key: 'personal',
+                    label: 'Personal',
+                    title: 'Create the Runwork connector in ChatGPT',
+                    steps: [
+                        { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                        { id: 'open-web', label: 'Connectors are created on chatgpt.com: open it in your browser and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                        { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                        { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                        { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                        { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                        { id: 'confirm', label: 'Open the ChatGPT desktop app and, in a new chat, ask "Do you have access to Runwork tools?" to confirm' },
+                    ],
+                },
+            ],
+        },
+    },
     {
         slug: 'windsurf',
         name: 'Windsurf',
@@ -481,6 +633,30 @@ export function isIDEAgent(slug) {
 export function isDesktopAgent(slug) {
     return getAgent(slug)?.category === 'desktop';
 }
+export function isWebAgent(slug) {
+    return getAgent(slug)?.category === 'web';
+}
+/**
+ * Connect-only agents have no local footprint to write: no skills directory,
+ * no MCP config file, no instruction file. The connector lives in the user's
+ * account (e.g. ChatGPT). `runwork sync` skips these for all local writes.
+ */
+export function isConnectOnlyAgent(agent) {
+    if (!agent)
+        return false;
+    return !agent.skillsPaths && !agent.mcpConfigPath && !agent.instructionFile;
+}
+/** Family identifier for an agent (e.g. 'chatgpt' for both ChatGPT entries), or its slug when standalone. */
+export function getAgentFamily(slug) {
+    const agent = getAgent(slug);
+    if (!agent)
+        return undefined;
+    return agent.family ?? agent.slug;
+}
+/** All agents sharing the given family identifier. */
+export function getFamilyAgents(family) {
+    return AGENT_REGISTRY.filter((a) => (a.family ?? a.slug) === family);
+}
 /** Alias of {@link getAgent} kept for backward compatibility with CLI callers. */
 export const getRegistryAgent = getAgent;
 /** Alias of {@link getAgents} kept for backward compatibility with CLI callers. */

package/dist/commands/__tests__/clone-args.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { normalizeCloneArgs } from '../clone.js';
+import { normalizeCloneArgs, RESTRICTED_FS_HELP } from '../clone.js';
 describe('normalizeCloneArgs', () => {
     it('passes through both args unchanged when --app is not provided', () => {
         expect(normalizeCloneArgs('app-id', 'C:/dir', undefined)).toEqual({
@@ -42,3 +42,10 @@ describe('normalizeCloneArgs', () => {
         });
     });
 });
+describe('clone --help restricted-FS guidance', () => {
+    it('warns agents about restricted "outputs" mounts and the remedy', () => {
+        expect(RESTRICTED_FS_HELP).toContain('Operation not permitted');
+        expect(RESTRICTED_FS_HELP).toContain('outputs');
+        expect(RESTRICTED_FS_HELP).toContain('home directory');
+    });
+});

package/dist/commands/__tests__/clone-source-result.test.d.ts

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

package/dist/commands/__tests__/clone-source-result.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { pullOutcomeFromError, isCloneSourceFailure } from '../clone.js';
+/** Fake an execFileSync error carrying git's stderr. */
+function gitError(stderr) {
+    const err = new Error('git failed');
+    err.stderr = Buffer.from(stderr);
+    return err;
+}
+describe('clone source outcome', () => {
+    describe('pullOutcomeFromError()', () => {
+        it('classifies an empty remote (brand-new app) as benign', () => {
+            const src = pullOutcomeFromError(gitError("fatal: couldn't find remote ref main"));
+            expect(src.pulled).toBe(false);
+            expect(src.reason).toBe('empty-remote');
+        });
+        it('classifies an auth failure', () => {
+            const src = pullOutcomeFromError(gitError('fatal: Authentication failed for https://runwork.ai'));
+            expect(src.reason).toBe('auth');
+        });
+        it('classifies a network failure', () => {
+            const src = pullOutcomeFromError(gitError('fatal: unable to access: Could not resolve host: runwork.ai'));
+            expect(src.reason).toBe('network');
+        });
+        it('classifies a missing remote', () => {
+            const src = pullOutcomeFromError(gitError("fatal: 'runwork' does not appear to be a git repository"));
+            expect(src.reason).toBe('no-remote');
+        });
+        it('preserves the raw stderr as detail', () => {
+            const src = pullOutcomeFromError(gitError('fatal: Authentication failed'));
+            expect(src.detail).toContain('Authentication failed');
+        });
+    });
+    describe('isCloneSourceFailure()', () => {
+        it('is false for a successful pull', () => {
+            expect(isCloneSourceFailure({ pulled: true })).toBe(false);
+        });
+        it('is false for an empty remote (expected for new apps)', () => {
+            expect(isCloneSourceFailure({ pulled: false, reason: 'empty-remote' })).toBe(false);
+        });
+        it.each(['auth', 'network', 'no-remote', 'unknown'])('is true for a real %s failure (template-only scaffold)', (reason) => {
+            const src = { pulled: false, reason };
+            expect(isCloneSourceFailure(src)).toBe(true);
+        });
+    });
+});

package/dist/commands/clone.d.ts

@@ -1,6 +1,19 @@
 import { Command } from 'commander';
 import { ApiClient } from '../api/client.js';
 import type { Credentials, AppInfo } from '../types.js';
+import { type SyncErrorReason } from '../git/classify-sync-error.js';
+/**
+ * Outcome of overlaying the app's git-tracked source on top of the template.
+ * `pulled: false` with `reason: 'empty-remote'` is the expected, benign state
+ * for a brand-new app (nothing pushed yet). Any other `reason` is a real
+ * failure that left a template-only scaffold -- the caller must NOT report
+ * success, since editing it would edit the wrong code (friction log #1).
+ */
+export interface CloneSource {
+    pulled: boolean;
+    reason?: 'empty-remote' | SyncErrorReason;
+    detail?: string;
+}
 export interface CloneResult {
     appId: string;
     appName: string;
@@ -8,8 +21,21 @@ export interface CloneResult {
     directory: string;
     workspaceId: string;
     workspaceName: string;
+    source: CloneSource;
 }
 export declare function execClone(client: ApiClient, app: AppInfo, directory?: string, creds?: Credentials | null): Promise<CloneResult>;
+/**
+ * Turn a failed-pull error into a CloneSource: an empty remote (benign,
+ * brand-new app) vs a classified real failure (auth/network/no-remote) that
+ * leaves a template-only scaffold.
+ */
+export declare function pullOutcomeFromError(err: unknown): CloneSource;
+/**
+ * A clone is a real failure -- a template-only scaffold rather than the app's
+ * code -- when the source pull didn't happen for any reason other than an
+ * empty remote. Callers must not report success in that case.
+ */
+export declare function isCloneSourceFailure(source: CloneSource): boolean;
 /**
  * Reconcile positional args with --app. When --app is provided, the first
  * positional argument is intended as the *directory* -- not another appId
@@ -24,4 +50,11 @@ export declare function normalizeCloneArgs(appId: string | undefined, directory:
     appId: string | undefined;
     directory: string | undefined;
 };
+/**
+ * Help epilogue shown under `runwork clone --help`. Agents tend to read help
+ * before running, so we surface the restricted-mount caveat (friction log #9)
+ * here. Exported so it can be asserted on directly (commander's help-text
+ * hooks aren't reflected by `helpInformation()`).
+ */
+export declare const RESTRICTED_FS_HELP = "\nNote for AI agents: clone into a normal working directory. Some sandboxed\n\"outputs\" mounts (e.g. certain agent environments) disallow the unlink\noperations git uses for pack files, which can corrupt the repo with errors\nlike \"unable to unlink '.git/objects/pack/...': Operation not permitted\". If\nyou hit that, clone into your home directory or another standard path instead.";
 export declare const cloneCommand: Command;