@shogo-ai/worker 1.7.4 → 1.7.7

package/README.md

@@ -8,14 +8,45 @@ Outbound-only: the worker dials Shogo Cloud over HTTPS, never the other way arou
 
 ## Install
 
+**macOS / Linux**
+
 ```bash
-# Requires node >= 20 (or bun >= 1.3)
-npm i -g @shogo-ai/worker
+curl -fsSL https://install.shogo.ai | bash
+```
+
+**Windows (PowerShell)**
+
+```powershell
+irm https://install.shogo.ai/ps | iex
 ```
 
-> Prefer a single self-contained binary? Grab the prebuilt tarball for your
-> OS / arch from the [latest worker release](https://github.com/shogo-ai/shogo-ai/releases?q=worker-v)
-> — it has no Node / Bun dependency.
+The installer drops a single self-contained binary at `~/.shogo/bin/shogo`
+(`%USERPROFILE%\.shogo\bin\shogo.exe` on Windows), verifies its SHA-256 against
+the published sidecar, and adds the bin dir to `PATH`. No Node or Bun on the
+target machine required.
+
+### Installer flags
+
+```bash
+curl -fsSL https://install.shogo.ai | bash -s -- [flags]
+
+  --channel <stable|beta>   release channel (default: stable)
+  --prefix <dir>            install dir (default: $HOME/.shogo/bin)
+  --force                   overwrite existing install
+  --no-binary               force npm install even if a prebuilt binary exists
+```
+
+### Alternate paths
+
+| Method | When to use |
+|--------|-------------|
+| `npm i -g @shogo-ai/worker` | Node ≥ 20 already on the machine; you want lockstep with `package.json` in a project repo. |
+| `gh release download v<X.Y.Z> -p 'shogo-<target>.tar.gz'` from [github.com/shogo-labs/shogo-ai/releases](https://github.com/shogo-labs/shogo-ai/releases) | Air-gapped / proxy-locked environments where `install.shogo.ai` is blocked. |
+| `bash packages/shogo-worker/install.sh` from a repo checkout | Self-mirror; pass `SHOGO_RELEASE_HOST=...` to pull tarballs from your own CDN. |
+
+The single binary, the npm package, and the GitHub Release tarballs all ship
+from the same `v*` tag, so the version you get is identical regardless of
+install method.
 
 ## Quick start
 
@@ -74,11 +105,52 @@ SHOGO_API_KEY=shogo_sk_... shogo worker start --foreground
 ├── logs/
 │   ├── worker.log
 │   └── worker.err.log
-└── runtime/
-    ├── agent-runtime  # AGPL binary, downloaded by `shogo runtime install`
-    └── version.json
+├── runtime/
+│   ├── agent-runtime    # AGPL binary, downloaded by `shogo runtime install`
+│   ├── runtime-template/  # Vite/React/Tailwind scaffolding the runtime seeds
+│   │                      # into new project workspaces. MUST live next to the
+│   │                      # binary — `getRuntimeTemplatePath()` looks here
+│   │                      # second (after the `RUNTIME_TEMPLATE_DIR` env
+│   │                      # override). The agent-runtime release tarball
+│   │                      # ships binary + this directory together.
+│   ├── tree-sitter-wasm/  # Tree-sitter parser core + per-language grammars
+│   │                      # (`tree-sitter.wasm` + `tree-sitter-${lang}.wasm`).
+│   │                      # `bun build --compile` bakes the build-machine path
+│   │                      # for these into the binary; we ship the WASMs
+│   │                      # next to the binary so it can dlopen them at
+│   │                      # runtime regardless of where the operator put it.
+│   │                      # The worker also exports
+│   │                      # `TREE_SITTER_WASM_DIR=<this dir>` to the spawned
+│   │                      # runtime so the resolved location is observable
+│   │                      # via `env | grep TREE_SITTER`.
+│   └── version.json
+└── projects/<projectId>/  # cloned project workspaces (auto-pulled on first
+                           # request, override with `--projects-dir` /
+                           # `SHOGO_PROJECTS_DIR`)
 ```
 
+### Workspace seeding (cli-worker)
+
+When the worker spawns the agent-runtime for a project, it MUST point that
+runtime at a real on-disk workspace via `WORKSPACE_DIR` / `PROJECT_DIR`.
+Three knobs control where that workspace comes from, in priority order:
+
+1. **Auto-pull (default).** On the first inbound request for a project,
+   `WorkerRuntimeManager` clones the cloud snapshot into
+   `<projectsDir>/<projectId>/`, watches it via `CloudSyncWatcher`, and
+   pushes local edits back. No operator action required.
+2. **`--projects-dir <path>` / `SHOGO_PROJECTS_DIR=<path>`.** Override the
+   root directory under which workspaces live. Useful when you want
+   workspaces on a faster disk or backed-up volume.
+3. **`shogo project pull <projectId>` (manual pre-pull).** When you've
+   passed `--no-auto-pull` (e.g. slow or metered connection), the worker
+   refuses to spawn until the canonical workspace exists at
+   `<projectsDir>/<projectId>/`. Pre-pulling is how you get there.
+
+If you disable auto-pull and **don't** pre-pull, the worker fails loudly
+with a multi-line error pointing you at all three options instead of
+silently falling back to an empty workspace.
+
 ## Networking
 
 The worker needs outbound HTTPS (TCP 443) to 3 hosts. **No inbound ports required.**
@@ -137,16 +209,54 @@ port allocation, env injection, restart-with-backoff, idle eviction, and health
 checks. The same code path is consumed by Shogo Desktop (`apps/api`) for its own
 agent runtimes — so any improvement made here ships to both.
 
+### What the cli-worker tunnel does — and doesn't — handle
+
+A cli-worker is an **execution target**: it forwards `/agent/*` paths to
+the per-project agent-runtime and nothing else. Stateful data
+(`/api/projects`, `/api/chat-sessions`, etc.) lives in Shogo Cloud and
+is served by the cloud backend, not by the worker. Studio's
+`SDKDomainProvider` checks `instance.kind` and only tunnels stateful
+APIs through the desktop adapter; for cli-workers it reads from cloud
+directly.
+
+If a request for a non-`/agent/*` path does reach the cli-worker tunnel
+(e.g. an out-of-date Studio client), the worker replies with a
+structured 502 body so future debuggers can read the rejection without
+log access:
+
+```json
+{
+  "code": "CLI_WORKER_HAS_NO_DATA_API",
+  "message": "cli-worker only serves /agent/* paths; tried: /api/projects",
+  "path": "/api/projects?workspaceId=ws-1"
+}
+```
+
 ## Programmatic use
 
 Both core classes are exposed for direct embedding (e.g. building your own
 desktop wrapper):
 
 ```ts
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { WorkerTunnel, WorkerRuntimeManager } from '@shogo-ai/worker'
 
+// `WorkerRuntimeManager` refuses to spawn a runtime unless it knows
+// where the workspace lives on disk. For embedders that just want
+// the cli-worker default behaviour, set `autoPull` and the manager
+// will clone each project's workspace from cloud on first request.
+// Embedders that manage workspaces themselves should set `projectDir`
+// inside `defaultSpawnConfig` (or via `enrichSpawnConfig`) instead.
 const runtimeManager = new WorkerRuntimeManager({
-  defaultSpawnConfig: { cloudUrl: 'https://studio.shogo.ai', apiKey: process.env.SHOGO_API_KEY! },
+  defaultSpawnConfig: {
+    cloudUrl: 'https://studio.shogo.ai',
+    apiKey: process.env.SHOGO_API_KEY!,
+  },
+  autoPull: {
+    enabled: true,
+    projectsDir: join(homedir(), '.shogo', 'projects'),
+  },
 })
 
 const tunnel = new WorkerTunnel({
@@ -159,6 +269,104 @@ const tunnel = new WorkerTunnel({
 tunnel.start()
 ```
 
+## External triggers
+
+The worker lets external services (Jira, Linear, Zapier, n8n, your own
+HTTP clients) send messages to a Shogo agent **running on this machine**,
+without exposing any inbound port. Combine `shogo worker start` with a
+project pin in Studio (or via the SDK) and the cloud-side
+`/api/projects/:id/agent-proxy/*` becomes a stable public URL routed
+through the worker's outbound tunnel:
+
+```
+External caller ──HTTPS──▶  Shogo Cloud  ──tunnel──▶  shogo worker  ──▶  agent-runtime
+                                                                         (this machine)
+```
+
+### Pin a project to this machine
+
+From Studio: open the project → **Channels → Run on** → pick this machine.
+From a script (uses `@shogo-ai/sdk`):
+
+```ts
+import { createClient } from '@shogo-ai/sdk'
+
+const client = createClient({
+  apiUrl: 'https://api.shogo.ai',
+  shogoApiKey: process.env.SHOGO_API_KEY!,
+})
+
+const machines = await client.machines.list({ workspaceId })
+const me = machines.find((m) => m.kind === 'cli_worker' && m.name === 'my-devbox')!
+
+await client.machines.pinProject(projectId, {
+  instanceId: me.id,
+  policy: 'pinned',   // 503 instance_offline if this machine goes down
+                      // (use 'prefer' to fall back to a cloud pod instead)
+})
+```
+
+### Trigger the agent
+
+```bash
+curl -X POST \
+  "https://api.shogo.ai/api/projects/$PROJECT_ID/agent-proxy/agent/channels/webhook/incoming" \
+  -H "Authorization: Bearer $SHOGO_API_KEY" \
+  -H "X-Webhook-Secret: $CHANNEL_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Triage Jira ticket ABC-123"}'
+```
+
+The cloud verifies the bearer key, looks up the project pin, and relays
+the request through this worker's existing outbound WebSocket into the
+agent-runtime that the worker spawned on demand. Tool calls (shell, file
+I/O, MCP servers) execute on **this machine**.
+
+See [Webhook channel reference](https://docs.shogo.ai/docs/features/external-triggers/webhook-channel)
+for the request/response shape, secret handling, and async callback mode.
+
+## Cloning a staging project (`shogo project pull`)
+
+When you pin a staging project to this machine, the worker needs the
+project's workspace files on disk to spawn the agent against. By default
+the worker **auto-clones** the project on first request:
+
+```bash
+shogo worker start                       # auto-pull is ON, git transport by default
+shogo worker start --no-auto-pull        # opt out (e.g. for git-backed projects)
+shogo worker start --no-git              # force the Files API path even when git is on PATH
+shogo worker start --projects-dir /mnt/big-disk/shogo   # override default ~/.shogo/projects
+```
+
+You can also clone manually ahead of time:
+
+```bash
+# Clones to ~/.shogo/projects/<projectId>/ by default
+shogo project pull <projectId>
+
+# Pull-then-watch: keeps a local editor and cloud in sync
+shogo project pull <projectId> --watch
+
+# Push local edits back
+shogo project push <projectId>
+shogo project push <projectId> --delete-remote   # mirror local deletions
+
+# Roll the local workspace back to a specific git checkpoint
+shogo project checkout <projectId>                             # fast-forward to remote HEAD
+shogo project checkout <projectId> --at "before refactor"      # resolve by checkpoint name
+shogo project checkout <projectId> --at <sha> --unshallow      # full history
+```
+
+**Two transports.** Auto-pull uses git's smart-HTTP protocol by default
+(`git clone --depth=1` against `https://api.shogo.ai/api/projects/<id>/git`)
+so the worker gets a full checkpoint history and delta-sized pushes for free.
+If `git` isn't available, the worker falls back to the Files API. Manual
+`shogo project pull/push` always uses the Files API so `--include` filters
+and `.shogo/` SQLite state work the same way. See
+[Cloning projects to a paired machine](https://docs.shogo.ai/docs/features/my-machines/project-pull)
+and [Checkpoints on the VPS](https://docs.shogo.ai/docs/features/my-machines/checkpoints-on-the-vps)
+for the end-to-end walkthrough.
+
 ## Troubleshooting
 
 ```bash
@@ -176,4 +384,4 @@ shogo runtime install   # (re)download the latest stable binary
 - [Cloud Agent: My Machines guide](../../docs/cloud-agent-my-machines.md) — full
   walk-through, security model, deploy patterns
 - [Networking & firewall guide](../../docs/my-machines-networking.md)
-- Source: [github.com/shogo-ai/shogo-ai](https://github.com/shogo-ai/shogo-ai)
+- Source: [github.com/shogo-labs/shogo-ai](https://github.com/shogo-labs/shogo-ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shogo-ai/worker",
-  "version": "1.7.4",
+  "version": "1.7.7",
   "description": "Shogo Cloud Agent Worker — run Shogo agents on your own machine (laptop, devbox, CI).",
   "license": "MIT",
   "author": "Shogo Technologies, Inc.",

package/src/cli.ts

@@ -24,6 +24,9 @@ import {
   runRuntimeVersion,
   runRuntimeWhere,
 } from './commands/runtime.ts';
+import { runProjectPull } from './commands/project-pull.ts';
+import { runProjectPush } from './commands/project-push.ts';
+import { runProjectCheckout } from './commands/project-checkout.ts';
 
 const VERSION = '0.1.0';
 
@@ -58,6 +61,9 @@ worker
   .option('--runtime-bin <path>', 'Override the agent-runtime binary path')
   .option('--debug', 'Run preflight checks before starting')
   .option('--foreground', 'Run in foreground (don\'t detach)')
+  .option('--no-auto-pull', 'Disable auto-clone of project workspaces on first request')
+  .option('--projects-dir <path>', 'Root directory for cloned project workspaces (default: ~/.shogo/projects)')
+  .option('--no-git', 'Force the file-transport sync path even when git is available')
   .action((flags) => handle(() => runStart(flags)));
 
 worker
@@ -110,9 +116,38 @@ config
   .action(() => handle(runConfigShow));
 config
   .command('set <key> <value>')
-  .description('Set apiKey / cloudUrl / name / workerDir / port')
+  .description('Set apiKey / cloudUrl / name / workerDir / port / projectsDir')
   .action((k: string, v: string) => handle(() => runConfigSet(k, v)));
 
+const project = program.command('project').description('Clone/sync project workspaces between Shogo Cloud and this machine');
+project
+  .command('pull <projectId>')
+  .description('Clone a project from Shogo Cloud into ~/.shogo/projects/<projectId>/')
+  .option('--into <dir>', 'Destination directory (default: ~/.shogo/projects/<projectId>)')
+  .option('--watch', 'After pull, watch the local dir and push edits back to cloud')
+  .option('--include <patterns>', 'Comma-separated glob patterns (e.g. "src/**,*.md")')
+  .option('--api-key <key>', 'Override API key for this run')
+  .option('--cloud-url <url>', 'Override Shogo Cloud URL for this run')
+  .action((id: string, flags) => handle(() => runProjectPull(id, flags)));
+project
+  .command('push <projectId>')
+  .description('Upload local workspace edits back to Shogo Cloud')
+  .option('--from <dir>', 'Source directory (default: ~/.shogo/projects/<projectId>)')
+  .option('--delete-remote', 'Mirror local deletions to cloud (DESTRUCTIVE)')
+  .option('--include <patterns>', 'Comma-separated glob patterns')
+  .option('--api-key <key>', 'Override API key for this run')
+  .option('--cloud-url <url>', 'Override Shogo Cloud URL for this run')
+  .action((id: string, flags) => handle(() => runProjectPush(id, flags)));
+project
+  .command('checkout <projectId>')
+  .description('Roll the local workspace to a specific git checkpoint (SHA or named checkpoint)')
+  .option('--at <ref>', 'Target SHA or checkpoint name (default: remote HEAD)')
+  .option('--unshallow', 'Fetch full history before checking out (needed for old SHAs)')
+  .option('--into <dir>', 'Local dir override (default: ~/.shogo/projects/<projectId>)')
+  .option('--api-key <key>', 'Override API key for this run')
+  .option('--cloud-url <url>', 'Override Shogo Cloud URL for this run')
+  .action((id: string, flags) => handle(() => runProjectCheckout(id, flags)));
+
 program.showHelpAfterError(pc.dim('\n(use --help for usage)'));
 program.parseAsync(process.argv);
 

package/src/commands/project-checkout.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo project checkout <projectId> [--at <sha|name>] [--unshallow]`
+ *
+ * Rolls the worker's local copy of a project back (or forward) to a
+ * specific git checkpoint. By default this targets the project's
+ * current cloud HEAD — i.e. it's the worker-side equivalent of
+ * `git pull --rebase`.
+ *
+ * `--at` accepts:
+ *   - A full or short SHA (anything `git rev-parse` can resolve).
+ *   - A checkpoint name (resolved against
+ *     `GET /api/projects/:projectId/checkpoints?limit=…`).
+ *
+ * `--unshallow` first converts the local repo from a shallow clone to
+ * a full clone — necessary when checking out a historical SHA that
+ * lives beyond the original `--depth=1` window.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { resolveConfig } from '../lib/config.ts';
+import { projectDirFor } from '../lib/paths.ts';
+import {
+  gitFetchAndReset,
+  gitFetchUnshallow,
+  isGitRepo,
+  runGit,
+} from '../lib/git-cloner.ts';
+
+export interface ProjectCheckoutFlags {
+  /** SHA or checkpoint name. Defaults to remote HEAD. */
+  at?: string;
+  /** Convert a shallow clone to a full one before checking out. */
+  unshallow?: boolean;
+  /** Local dir override. */
+  into?: string;
+  /** API key override. */
+  apiKey?: string;
+  /** Cloud URL override. */
+  cloudUrl?: string;
+}
+
+export async function runProjectCheckout(projectId: string, flags: ProjectCheckoutFlags): Promise<void> {
+  if (!projectId) throw new Error('projectId is required');
+
+  const cfg = resolveConfig({
+    apiKey: flags.apiKey,
+    cloudUrl: flags.cloudUrl,
+  });
+
+  const localDir = resolve(flags.into ?? projectDirFor(projectId, cfg.projectsDir));
+  if (!existsSync(localDir)) {
+    throw new Error(`Local project dir does not exist: ${localDir} — run \`shogo project pull\` first`);
+  }
+  if (!isGitRepo(localDir)) {
+    throw new Error(
+      `${localDir} is not a git repo. \`shogo project checkout\` requires the git sync path; ` +
+        `run \`shogo project pull\` after installing git, or use \`shogo project pull --include\` for file-only restore.`,
+    );
+  }
+
+  console.log(pc.bold(`\nshogo project checkout ${pc.cyan(projectId)}`));
+  console.log(pc.dim('  cloud  ') + cfg.cloudUrl);
+  console.log(pc.dim('  local  ') + localDir);
+  if (flags.at) console.log(pc.dim('  at     ') + flags.at);
+  console.log('');
+
+  if (flags.unshallow) {
+    console.log(pc.dim('Unshallowing repo (this may take a moment)...'));
+    await gitFetchUnshallow({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+    });
+  }
+
+  if (!flags.at) {
+    // Default: fast-forward to remote HEAD.
+    const res = await gitFetchAndReset({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+    });
+    console.log(pc.green(`✓ Reset to ${res.commitSha.slice(0, 8)} (remote HEAD)`));
+    return;
+  }
+
+  // Resolve --at: try as SHA first (cheapest), fall back to checkpoint
+  // name lookup against the cloud listing.
+  let targetSha: string;
+  try {
+    const head = await runGit(['rev-parse', '--verify', `${flags.at}^{commit}`], { cwd: localDir });
+    targetSha = head.stdout.trim();
+  } catch {
+    targetSha = await resolveCheckpointByName(cfg.cloudUrl, cfg.apiKey, projectId, flags.at);
+    console.log(pc.dim(`  resolved checkpoint "${flags.at}" → ${targetSha.slice(0, 8)}`));
+  }
+
+  // Fetch up to that SHA (covers the shallow-window case for users who
+  // didn't pass --unshallow but are reaching for a slightly older sha).
+  try {
+    await gitFetchAndReset({
+      apiUrl: cfg.cloudUrl,
+      apiKey: cfg.apiKey,
+      projectId,
+      localDir,
+      branch: targetSha,
+    });
+  } catch {
+    // If we can't fetch directly to that sha (it's outside the shallow
+    // window), do a full unshallow and retry.
+    if (!flags.unshallow) {
+      console.log(pc.yellow('  fetch failed; unshallowing and retrying...'));
+      await gitFetchUnshallow({
+        apiUrl: cfg.cloudUrl,
+        apiKey: cfg.apiKey,
+        projectId,
+        localDir,
+      });
+      await gitFetchAndReset({
+        apiUrl: cfg.cloudUrl,
+        apiKey: cfg.apiKey,
+        projectId,
+        localDir,
+        branch: targetSha,
+      });
+    } else {
+      throw new Error(`Cannot reach commit ${targetSha} in local clone`);
+    }
+  }
+
+  // Final reset to the requested sha (FETCH_HEAD may differ if we
+  // fetched a branch and the user asked for a specific commit).
+  await runGit(['reset', '--hard', targetSha], { cwd: localDir });
+  console.log(pc.green(`✓ Checked out ${targetSha.slice(0, 8)}`));
+}
+
+interface CheckpointListResponse {
+  ok: true;
+  checkpoints: Array<{ id: string; commitSha: string; name: string | null; commitMessage: string | null; createdAt: string }>;
+  hasMore: boolean;
+}
+
+/**
+ * Resolve a checkpoint by user-facing name (case-insensitive).
+ * Strategy: ask the cloud for the most recent N checkpoints, pick the
+ * one whose `name` or first 8 chars of `commitMessage` matches.
+ */
+async function resolveCheckpointByName(
+  cloudUrl: string,
+  apiKey: string,
+  projectId: string,
+  needle: string,
+): Promise<string> {
+  const url = `${cloudUrl.replace(/\/+$/, '')}/api/projects/${encodeURIComponent(projectId)}/checkpoints?limit=100`;
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to list checkpoints: HTTP ${res.status}`);
+  }
+  const body = (await res.json()) as CheckpointListResponse;
+  const norm = needle.toLowerCase();
+  const match = body.checkpoints.find((cp) => {
+    if (cp.name && cp.name.toLowerCase() === norm) return true;
+    if (cp.commitSha.startsWith(needle)) return true;
+    if (cp.commitMessage && cp.commitMessage.toLowerCase().includes(norm)) return true;
+    return false;
+  });
+  if (!match) {
+    throw new Error(`No checkpoint matches "${needle}" (searched ${body.checkpoints.length} most recent)`);
+  }
+  return match.commitSha;
+}

package/src/commands/project-pull.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * `shogo project pull <projectId>` — clone a project's workspace from
+ * Shogo Cloud to a local directory. Optionally `--watch` starts a
+ * bidirectional sync: pull initially, then push any local edits back via
+ * the {@link CloudSyncWatcher}.
+ *
+ * This is the easy-button companion to pinning a project to a paired
+ * machine:
+ *
+ *   shogo login                      # one-time pairing
+ *   shogo project pull <projectId>   # clones the staging snapshot locally
+ *   shogo worker start               # auto-routes pinned traffic here
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import pc from 'picocolors';
+import { CloudFileTransport, type ProgressEvent, type SyncStats } from '@shogo-ai/sdk';
+import { resolveConfig } from '../lib/config.ts';
+import { ensureProjectsDir, projectDirFor } from '../lib/paths.ts';
+import { CloudSyncWatcher } from '../lib/cloud-sync-watcher.ts';
+
+export interface ProjectPullFlags {
+  into?: string;
+  watch?: boolean;
+  include?: string;
+  apiKey?: string;
+  cloudUrl?: string;
+}
+
+export async function runProjectPull(projectId: string, flags: ProjectPullFlags): Promise<void> {
+  if (!projectId) throw new Error('projectId is required');
+
+  const cfg = resolveConfig({
+    apiKey: flags.apiKey,
+    cloudUrl: flags.cloudUrl,
+  });
+
+  ensureProjectsDir(cfg.projectsDir);
+  const into = resolve(flags.into ?? projectDirFor(projectId, cfg.projectsDir));
+  if (!existsSync(into)) {
+    mkdirSync(into, { recursive: true });
+  }
+
+  const include = flags.include?.split(',').map((s) => s.trim()).filter(Boolean);
+
+  console.log(pc.bold(`\nshogo project pull ${pc.cyan(projectId)}`));
+  console.log(pc.dim('  cloud   ') + cfg.cloudUrl);
+  console.log(pc.dim('  into    ') + into);
+  if (include?.length) console.log(pc.dim('  include ') + include.join(', '));
+  console.log('');
+
+  const transport = new CloudFileTransport({
+    apiUrl: cfg.cloudUrl,
+    apiKey: cfg.apiKey,
+    projectId,
+    localDir: into,
+    include,
+    onProgress: makeProgressReporter(),
+  });
+
+  const stats = await transport.downloadAll();
+  printSummary('Pull', stats);
+
+  if (flags.watch) {
+    console.log(pc.bold('\nWatching for local changes...'));
+    const watcher = new CloudSyncWatcher({
+      rootDir: into,
+      transport,
+      onFlush: ({ uploaded, errors }) => {
+        const list = uploaded.length === 1 ? uploaded[0] : `${uploaded.length} files`;
+        const errSuffix = errors > 0 ? pc.red(` (${errors} errors)`) : '';
+        console.log(pc.dim(`  ↑ ${list}${errSuffix}`));
+      },
+    });
+    watcher.start();
+
+    let shuttingDown = false;
+    const shutdown = async (signal: NodeJS.Signals) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      console.log(pc.dim(`\nReceived ${signal} — flushing pending uploads...`));
+      try {
+        await watcher.stop();
+      } catch (err: any) {
+        console.warn(pc.yellow(`watcher.stop: ${err?.message ?? err}`));
+      }
+      process.exit(0);
+    };
+    process.once('SIGINT', () => void shutdown('SIGINT'));
+    process.once('SIGTERM', () => void shutdown('SIGTERM'));
+    process.once('SIGHUP', () => void shutdown('SIGHUP'));
+
+    // Park the foreground process. Shutdown handler exits when the user terminates.
+    await new Promise<void>(() => { /* never resolves */ });
+  }
+}
+
+function makeProgressReporter(): (e: ProgressEvent) => void {
+  return (e) => {
+    const verb = e.kind === 'download' ? '↓' : e.kind === 'upload' ? '↑' : e.kind === 'delete' ? '✗' : '·';
+    const pct = e.total > 0 ? ` ${e.index + 1}/${e.total}` : '';
+    const sizeNote = e.bytes != null ? pc.dim(` (${formatBytes(e.bytes)})`) : '';
+    console.log(pc.dim(`  ${verb}${pct} ${e.path}${sizeNote}`));
+  };
+}
+
+function printSummary(label: string, stats: SyncStats): void {
+  const ok = stats.errors.length === 0;
+  const head = ok ? pc.green(`✓ ${label} complete`) : pc.red(`✗ ${label} completed with errors`);
+  console.log(`\n${head}`);
+  console.log(pc.dim('  downloaded: ') + stats.downloaded);
+  if (stats.uploaded) console.log(pc.dim('  uploaded:   ') + stats.uploaded);
+  if (stats.deleted) console.log(pc.dim('  deleted:    ') + stats.deleted);
+  if (stats.skipped) console.log(pc.dim('  skipped:    ') + stats.skipped);
+  if (!ok) {
+    console.log(pc.dim('  errors:     ') + stats.errors.length);
+    for (const err of stats.errors.slice(0, 5)) {
+      console.log(pc.dim('    ') + pc.red(`${err.path}: ${err.message}`));
+    }
+    if (stats.errors.length > 5) {
+      console.log(pc.dim(`    ... and ${stats.errors.length - 5} more`));
+    }
+  }
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}