runwork 0.14.0 → 0.15.1

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;

package/dist/commands/clone.js

@@ -13,6 +13,10 @@ import { runAgentWizard } from '../ui/banner.js';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { buildCloneGuide, buildErrorResponse } from '../utils/agent-guidance.js';
 import { ensureGitIdentity } from '../git/identity.js';
+import { ensureGitCredentialHelper } from '../git/credentials.js';
+import { ensureRunworkRemote } from '../git/remote.js';
+import { hardenRepoForRestrictedFs } from '../git/repo-config.js';
+import { classifySyncError } from '../git/classify-sync-error.js';
 import { requireGit } from '../git/preflight.js';
 import { formatError } from '../utils/format-error.js';
 export async function execClone(client, app, directory, creds) {
@@ -58,16 +62,24 @@ export async function execClone(client, app, directory, creds) {
             execFileSync('git', ['symbolic-ref', 'HEAD', 'refs/heads/main'], { cwd: dir, stdio: 'pipe' });
         }
         catch { /* best-effort: push uses HEAD:main so this is just cleanliness */ }
+        // Disable background gc/maintenance so pack rewrites don't fail on
+        // restricted filesystems (e.g. some agent "outputs" mounts). Harmless on
+        // normal filesystems. See git/repo-config.ts.
+        hardenRepoForRestrictedFs(dir);
     }
     // Seed a local git identity so subsequent commits do not fail on machines
     // (commonly fresh Windows installs) without `git config --global user.email`.
     ensureGitIdentity(dir, creds);
-    try {
-        execFileSync('git', ['remote', 'set-url', 'runwork', remoteUrl], { cwd: dir, stdio: 'pipe' });
-    }
-    catch {
-        execFileSync('git', ['remote', 'add', 'runwork', remoteUrl], { cwd: dir, stdio: 'pipe' });
+    // Make sure git can authenticate to the runwork remote before we fetch.
+    // Headless auth paths (the get_cli_setup MCP tool, or a hand-written
+    // ~/.runwork/.credentials) register API creds but not the git helper, so
+    // without this the fetch below silently fails and we fall back to a
+    // template-only scaffold. See git/credentials.ts:ensureGitCredentialHelper.
+    if (creds?.baseUrl) {
+        await ensureGitCredentialHelper(creds.baseUrl);
     }
+    ensureRunworkRemote(dir, remoteUrl);
+    let source = { pulled: true };
     try {
         execFileSync('git', ['fetch', 'runwork', 'main'], { cwd: dir, stdio: 'pipe' });
         // Reset to remote HEAD - overlays git-tracked files on top of template
@@ -76,11 +88,19 @@ export async function execClone(client, app, directory, creds) {
         execFileSync('git', ['checkout', '.'], { cwd: dir, stdio: 'pipe' });
     }
     catch (err) {
-        // Distinguish "remote is empty" (expected for brand-new apps) from
-        // real failures. We print both the generic next-step hint and the
-        // underlying error so authentication / network failures aren't lost.
-        console.warn('Could not pull from runwork remote. Starting with template only.');
-        console.warn(`  ${formatError(err)}`);
+        source = pullOutcomeFromError(err);
+        if (source.reason === 'empty-remote') {
+            // Brand-new app: the remote has no `main` branch yet. Expected and
+            // benign -- the template scaffold IS the starting point.
+            console.warn('No source pushed for this app yet. Starting from the template scaffold.');
+        }
+        else {
+            // A real failure (auth, missing remote, network). The scaffold here is
+            // NOT the app's code -- surface it loudly so the caller fails instead of
+            // silently editing the wrong files.
+            console.warn('Could not pull the app source from the runwork remote.');
+            console.warn(`  ${formatError(err)}`);
+        }
     }
     // Write .runwork.json config
     const config = {
@@ -107,8 +127,45 @@ export async function execClone(client, app, directory, creds) {
         directory: resolve(dir),
         workspaceId: app.workspaceId,
         workspaceName: app.workspaceName,
+        source,
     };
 }
+/** Pull the raw git stderr off an execFileSync error for classification. */
+function extractStderr(err) {
+    const e = err;
+    if (e?.stderr)
+        return e.stderr.toString().trim();
+    return formatError(err);
+}
+/**
+ * Whether a failed `git fetch runwork main` means the remote simply has no
+ * `main` branch yet (a brand-new app), as opposed to an auth/network/remote
+ * failure. Git reports this as "couldn't find remote ref main".
+ */
+function isEmptyRemote(stderr) {
+    const s = stderr.toLowerCase();
+    return s.includes("couldn't find remote ref") || s.includes('could not find remote ref');
+}
+/**
+ * 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 function pullOutcomeFromError(err) {
+    const detail = extractStderr(err);
+    if (isEmptyRemote(detail)) {
+        return { pulled: false, reason: 'empty-remote', detail };
+    }
+    return { pulled: false, reason: classifySyncError(detail), detail };
+}
+/**
+ * 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 function isCloneSourceFailure(source) {
+    return !source.pulled && source.reason !== 'empty-remote';
+}
 /**
  * Reconcile positional args with --app. When --app is provided, the first
  * positional argument is intended as the *directory* -- not another appId
@@ -123,11 +180,24 @@ export function normalizeCloneArgs(appId, directory, options) {
     }
     return { appId, directory };
 }
+/**
+ * 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 const RESTRICTED_FS_HELP = `
+Note for AI agents: clone into a normal working directory. Some sandboxed
+"outputs" mounts (e.g. certain agent environments) disallow the unlink
+operations git uses for pack files, which can corrupt the repo with errors
+like "unable to unlink '.git/objects/pack/...': Operation not permitted". If
+you hit that, clone into your home directory or another standard path instead.`;
 export const cloneCommand = new Command('clone')
     .description('Clone a Runwork app to local development')
     .argument('[appId]', 'App ID to clone (interactive if omitted)')
     .argument('[directory]', 'Target directory')
     .option('--app <name-or-id>', 'App name or ID (skips interactive selection)')
+    .addHelpText('after', RESTRICTED_FS_HELP)
     .action(async (rawAppId, rawDirectory, options) => {
     requireGit('clone');
     const { appId, directory } = normalizeCloneArgs(rawAppId, rawDirectory, options);
@@ -156,20 +226,45 @@ export const cloneCommand = new Command('clone')
         console.log(`Cloning "${app.name}"...`);
     }
     const cloneResult = await execClone(client, app, directory, creds);
+    // A real pull failure (auth/network/missing-remote) left a template-only
+    // scaffold that is NOT the app's deployed code. Report it as a failure so
+    // an agent doesn't start editing the wrong files (friction log #1).
+    const pullFailed = isCloneSourceFailure(cloneResult.source);
     if (useJson) {
+        if (pullFailed) {
+            jsonOut(buildErrorResponse('clone', 'Cloned the scaffold but could not pull the app source', `git could not fetch the app's source (${cloneResult.source.reason}), so the directory holds only the template scaffold, not the deployed code. ${cloneResult.source.detail ?? ''}`.trim(), [
+                'Run `runwork doctor --fix` to repair git auth and the runwork remote',
+                `Then re-clone: runwork clone --app ${cloneResult.appName}`,
+            ]));
+            process.exit(1);
+        }
         const response = {
             success: true,
             command: 'clone',
             result: cloneResult,
+            warning: cloneResult.source.reason === 'empty-remote'
+                ? 'This app has no source pushed yet. The directory is the starting template scaffold.'
+                : undefined,
             guide: buildCloneGuide(cloneResult.appName, cloneResult.slug),
         };
         jsonOut(response);
         return;
     }
+    if (pullFailed) {
+        console.error(`\nCloned the scaffold for "${cloneResult.appName}", but could NOT pull the app source (${cloneResult.source.reason}).`);
+        console.error('The directory holds only the template scaffold, not the deployed code.');
+        console.error('Fix git access, then re-clone:');
+        console.error('  runwork doctor --fix');
+        console.error(`  runwork clone --app ${cloneResult.appName}`);
+        process.exit(1);
+    }
     // No trailing separator: cloneResult.directory is already an absolute
     // path. Appending '/' here mixed with Windows '\' separators produced
     // confusing output like `C:\Users\...\app/` on Windows.
     console.log(`\nApp "${cloneResult.appName}" cloned to ${cloneResult.directory}`);
+    if (cloneResult.source.reason === 'empty-remote') {
+        console.log('Note: no source pushed for this app yet. Starting from the template scaffold.');
+    }
     console.log(`Remote: ${client.getGitRemoteUrl(cloneResult.workspaceId, cloneResult.appId)}`);
     await runAgentWizard(cloneResult.directory);
     console.log(`Next: cd ${cloneResult.slug} && runwork dev`);