@apralabs/apra-fleet 0.2.2

package/dist/version.js

@@ -0,0 +1,101 @@
+// BUILD_VERSION is replaced by esbuild `define` at bundle time.
+// In dev (tsc), it stays as-is and we fall back to reading version.json.
+import { createRequire } from 'node:module';
+/**
+ * Core version resolution logic with injectable root directory.
+ *
+ * The `rootDir` parameter is a testability seam: callers may pass a path that
+ * does not contain a valid version.json to exercise the catch -> 'v0.0.0-unknown'
+ * fallback without needing to mock native built-ins.  Production code always
+ * calls this via resolveVersion() which supplies the real package root.
+ *
+ * NOTE: the seam is intentionally minimal -- only rootDir is injectable.
+ * The require() loader is NOT injected because changing it would undermine
+ * the createRequire(import.meta.url) lazy-load strategy that keeps this
+ * module from being perturbed by consumers that mock 'node:fs' at module scope
+ * (see update.test.ts).  For the fallback test, a non-existent rootDir is
+ * sufficient to trigger the catch without mocking anything.
+ */
+export function resolveVersionFromRoot(rootDir) {
+    // fs/path/url are loaded lazily via require() rather than top-level ESM
+    // imports so that consumers which mock 'node:fs' at module scope do not
+    // perturb this module-load-time call (serverVersion is assigned eagerly).
+    // Under ESM (tsc output for npm) `require` and `__dirname` do not exist,
+    // so we build a require() from import.meta.url and derive the dir from it.
+    // Under CJS/SEA we use the bare globals so the existing path is unaffected.
+    try {
+        let req;
+        if (typeof __dirname === 'undefined') {
+            // ESM path (tsc output for npm).
+            req = createRequire(import.meta.url);
+        }
+        else {
+            // CJS / SEA path.
+            req = require;
+        }
+        const { readFileSync, existsSync } = req('node:fs');
+        const { join } = req('node:path');
+        const root = rootDir;
+        const vf = JSON.parse(readFileSync(join(root, 'version.json'), 'utf-8'));
+        // 3. Dev-only git-hash suffix. npm installs ship no .git/ directory, so
+        //    this naturally yields a bare semver for npm users.
+        let hash = '';
+        try {
+            const headPath = join(root, '.git', 'HEAD');
+            if (existsSync(headPath)) {
+                const head = readFileSync(headPath, 'utf-8').trim();
+                if (head.startsWith('ref: ')) {
+                    const refPath = join(root, '.git', head.slice(5));
+                    if (existsSync(refPath)) {
+                        hash = '_' + readFileSync(refPath, 'utf-8').trim().slice(0, 6);
+                    }
+                }
+                else {
+                    hash = '_' + head.slice(0, 6);
+                }
+            }
+        }
+        catch { /* no git info */ }
+        return `v${vf.version}${hash}`;
+    }
+    catch {
+        return 'v0.0.0-unknown';
+    }
+}
+function resolveVersion() {
+    // 1. Build-time injection (esbuild bundle / SEA binary)
+    try {
+        if (typeof BUILD_VERSION !== 'undefined')
+            return BUILD_VERSION;
+    }
+    catch {
+        // BUILD_VERSION not defined -- dev/npm mode
+    }
+    // 2. Resolve the package root containing version.json.
+    //    fs/path/url are loaded lazily via require() rather than top-level ESM
+    //    imports so that consumers which mock 'node:fs' at module scope do not
+    //    perturb this module-load-time call (serverVersion is assigned eagerly).
+    //    Under ESM (tsc output for npm) `require` and `__dirname` do not exist,
+    //    so we build a require() from import.meta.url and derive the dir from it.
+    //    Under CJS/SEA we use the bare globals so the existing path is unaffected.
+    let req;
+    let dir;
+    if (typeof __dirname === 'undefined') {
+        // ESM path (tsc output for npm).
+        req = createRequire(import.meta.url);
+        const { fileURLToPath } = req('node:url');
+        const { dirname } = req('node:path');
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    else {
+        // CJS / SEA path. __dirname points to dist/ (tsc output).
+        req = require;
+        dir = __dirname;
+    }
+    const { join } = req('node:path');
+    // dist/ entry -> package root is one level up.
+    const root = join(dir, '..');
+    return resolveVersionFromRoot(root);
+}
+export const serverVersion = resolveVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"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"}

package/hooks/hooks-config.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "mcp__apra-fleet__register_member",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const fs = require('fs'), path = require('path'), cp = require('child_process'); let home = process.env.USERPROFILE || process.env.HOME || ''; if (process.platform === 'linux' && home.startsWith('/home/')) { const user = process.env.USER || home.split('/').pop(); const wslHome = '/mnt/c/Users/' + user; if (fs.existsSync(wslHome)) home = wslHome; } const p = path.join(home, '.apra-fleet', 'hooks', 'post-register-member.sh'); if (fs.existsSync(p)) { cp.execSync('bash \\\"' + p + '\\\"', { stdio: 'inherit' }); }\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/post-register-member.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# PostToolUse hook for mcp__apra-fleet__register_member
+# Self-contained onboarding nudge — works with or without the PM skill.
+#
+# Installed by install.sh into the user's ~/.claude/settings.json hook config.
+# Hook input (stdin): JSON with tool_name, tool_input, session_id, etc.
+
+cat <<'EOF'
+{"decision":"block","reason":"New member registered. Run onboarding before dispatching work.","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Onboarding checklist:\n1. Remote members: migrate to SSH key auth via setup_ssh_key (skip for local members)\n2. Check member_detail to confirm connectivity and auth status\n3. Detect VCS provider: execute_command → git remote -v on the member\n4. Provision VCS auth if needed via provision_vcs_auth\n5. Disable AI attribution: execute_command → write {\"attribution\":{\"commit\":\"\",\"pr\":\"\"}} to .claude/settings.json on the member\n6. Ask user for member roles (development, review, testing, devops)\n7. If PM skill is installed, update the project status file with member profile"}}
+EOF

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@apralabs/apra-fleet",
+  "version": "0.2.2",
+  "description": "MCP server for orchestrating multiple agentic AI instances (Claude, Gemini, Codex, Copilot, AGY) across machines via SSH",
+  "author": "Apra Labs",
+  "homepage": "https://github.com/Apra-Labs/apra-fleet",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Apra-Labs/apra-fleet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Apra-Labs/apra-fleet/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "apra-fleet": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist/",
+    "hooks/",
+    "scripts/fleet-statusline.sh",
+    "scripts/agy-settings-merge.js",
+    "scripts/agy-transcript-reader.js",
+    "skills/",
+    "version.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:sea": "node scripts/build-sea.mjs",
+    "build:sea-config": "node scripts/gen-sea-config.mjs",
+    "build:sea-package": "node scripts/package-sea.mjs",
+    "build:binary": "npm run build:sea && npm run build:sea-config && npm run build:sea-package",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "tsc && node dist/smoke-test.js",
+    "integration": "tsc && npx tsx tests/integration.test.ts",
+    "prepare": "node scripts/install-hooks.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai-agent",
+    "anthropic",
+    "automation",
+    "claude",
+    "claude-code",
+    "devtools",
+    "fleet",
+    "mcp",
+    "model-context-protocol",
+    "multi-agent",
+    "orchestration",
+    "remote-execution",
+    "ssh"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@inquirer/password": "^5.0.11",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "smol-toml": "^1.6.1",
+    "ssh2": "^1.17.0",
+    "uuid": "^14.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ssh2": "^1.15.0",
+    "@types/uuid": "^10.0.0",
+    "esbuild": "^0.27.4",
+    "postject": "^1.0.0-alpha.6",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/agy-settings-merge.js

@@ -0,0 +1,27 @@
+// agy-settings-merge.js -- writes per-workspace model override for Antigravity.
+//
+// Merges a model name into .gemini/antigravity-cli/settings.json (relative to cwd)
+// without overwriting other fields (colorScheme, statusLine, permissions, etc.).
+//
+// argv[1] = model display name (e.g. "Gemini 3.5 Flash (Medium)")
+
+const fs = require('fs');
+const path = require('path');
+
+const model = process.argv[2];
+if (!model) {
+  process.exit(0);
+}
+
+const sp = path.join('.gemini', 'antigravity-cli', 'settings.json');
+fs.mkdirSync(path.dirname(sp), { recursive: true });
+
+let settings = {};
+try {
+  settings = JSON.parse(fs.readFileSync(sp, 'utf8'));
+} catch {
+  // file missing or malformed -- start fresh
+}
+
+settings.model = model;
+fs.writeFileSync(sp, JSON.stringify(settings, null, 2) + '\n');

package/scripts/agy-transcript-reader.js

@@ -0,0 +1,62 @@
+// agy-transcript-reader.js -- reads the Antigravity CLI conversation transcript.
+//
+// Tries two strategies to locate the transcript:
+//   1. Direct UUID lookup: brain/<convId>/.system_generated/logs/transcript.jsonl
+//      (when agy honors --conversation)
+//   2. Folder-based lookup: last_conversations.json[workFolder]
+//      (when agy ignores --conversation and registers under its work folder,
+//      which happens for local members in a git repo)
+//
+// argv[1] = conversation UUID that fleet minted and passed via --conversation
+// argv[2] = work folder path for the fallback lookup
+
+const fs = require('fs');
+const path = require('path');
+
+try {
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  const convId = process.argv[2];
+  const workDir = process.argv[3] || '';
+
+  function readTranscript(id) {
+    const tp = path.join(
+      home, '.gemini', 'antigravity-cli', 'brain',
+      id, '.system_generated', 'logs', 'transcript.jsonl'
+    );
+    if (fs.existsSync(tp)) {
+      console.log('FLEET_TRANSCRIPT_START');
+      console.log(fs.readFileSync(tp, 'utf8'));
+      console.log('FLEET_TRANSCRIPT_END');
+      return true;
+    }
+    return false;
+  }
+
+  // Strategy 1: direct UUID lookup
+  if (convId && readTranscript(convId)) {
+    process.exit(0);
+  }
+
+  // Strategy 2: folder-based lookup via last_conversations.json
+  const cachePath = path.join(
+    home, '.gemini', 'antigravity-cli', 'cache', 'last_conversations.json'
+  );
+  if (workDir && fs.existsSync(cachePath)) {
+    const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    const norm = (p) => path.resolve(p).toLowerCase().split(path.sep).join('/');
+    const target = norm(workDir);
+    for (const k of Object.keys(cache)) {
+      if (norm(k) === target) {
+        if (readTranscript(cache[k])) {
+          process.exit(0);
+        }
+        break;
+      }
+    }
+    console.log('FLEET_TRANSCRIPT_MISSING:NOT_IN_CACHE:' + target);
+  } else {
+    console.log('FLEET_TRANSCRIPT_MISSING:' + (convId || 'NO_ID'));
+  }
+} catch (e) {
+  console.log('FLEET_TRANSCRIPT_ERROR:' + e.message);
+}

package/scripts/fleet-statusline.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Fleet statusline script for Claude Code.
+# Reads pre-rendered statusline.txt and appends a freshness indicator
+# based on file mtime — gradient from green to red:
+#
+# Claude Code pipes JSON session data to stdin — we consume it to avoid
+# broken-pipe but don't need it; the fleet server writes the real state.
+
+cat > /dev/null  # drain stdin
+
+STATUSLINE_FILE="${APRA_FLEET_DATA_DIR:-$HOME/.apra-fleet/data}/statusline.txt"
+
+if [ ! -f "$STATUSLINE_FILE" ]; then
+  echo "Fleet: no status"
+  exit 0
+fi
+
+# Read the pre-rendered line
+LINE=$(cat "$STATUSLINE_FILE")
+
+# Compute age in seconds (portable: works on macOS + Linux + Git Bash)
+if stat --version >/dev/null 2>&1; then
+  # GNU stat (Linux, Git Bash on Windows)
+  MTIME=$(stat -c %Y "$STATUSLINE_FILE" 2>/dev/null)
+else
+  # BSD stat (macOS)
+  MTIME=$(stat -f %m "$STATUSLINE_FILE" 2>/dev/null)
+fi
+
+NOW=$(date +%s)
+AGE=$(( NOW - ${MTIME:-0} ))
+
+if   [ "$AGE" -lt 10 ];   then FRESH="✅"    # <10s  fresh
+elif [ "$AGE" -lt 60 ];   then FRESH="☑️"    # <1m   recent
+elif [ "$AGE" -lt 300 ];  then FRESH="✔️"    # <5m   ok
+elif [ "$AGE" -lt 900 ];  then FRESH="⏳"    # <15m  getting stale
+elif [ "$AGE" -lt 1800 ]; then FRESH="⚠️"    # <30m  stale warning
+elif [ "$AGE" -lt 3600 ]; then FRESH="🟡"    # <1h   attention
+elif [ "$AGE" -lt 7200 ]; then FRESH="🟠"    # <2h   concern
+else                            FRESH="🔴"    # >2h   stale, possibly down
+fi
+
+echo "${LINE}  ${FRESH}"

package/skills/fleet/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: fleet
+description: Fleet infrastructure mechanics  -  member management, permissions, onboarding, provider awareness, and tool usage patterns
+---
+
+# Fleet Skill
+
+This skill defines how to interact with fleet infrastructure: registering and onboarding members, managing permissions, dispatching work, monitoring tasks, and handling provider-specific differences.
+
+## Core Fleet Tools
+
+| Tool | Purpose |
+|------|---------|
+| `register_member` | Add a new member to the fleet |
+| `list_members` | List all fleet members and their status |
+| `member_detail` | Get detailed info on a member (provider, OS, icon, etc.) |
+| `update_member` | Update member metadata (icon, name, etc.) |
+| `remove_member` | Remove a member from the fleet |
+| `fleet_status` | Check member idle/busy state before dispatch |
+| `execute_command` | Run shell commands on a member |
+| `execute_prompt` | Dispatch a prompt to a member's LLM agent |
+| `send_files` | Push files from local to a member's work folder |
+| `receive_files` | Pull files from a member's work folder |
+| `monitor_task` | Check status of a long-running background task on any member. The `auto_stop` parameter and GPU utilization polling are cloud-only features. |
+| `compose_permissions` | Generate and deliver provider-native permission config |
+| `provision_llm_auth` | Provision LLM authentication for a **remote** member.  |
+| `provision_vcs_auth` | Provision VCS credentials (GitHub, Bitbucket, Azure DevOps) |
+| `revoke_vcs_auth` | Revoke VCS credentials |
+| `setup_ssh_key` | Migrate remote member from password to key-based auth |
+| `setup_git_app` | Configure GitHub App for token minting |
+| `update_llm_cli` | Update the LLM CLI on a member |
+| `cloud_control` | Manage cloud infrastructure for members |
+| `shutdown_server` | Shut down a remote member's server |
+| `credential_store_set` | Store a secret credential for use in commands (entered OOB  -  never in chat) |
+| `credential_store_list` | List stored credential names (values are never returned) |
+| `credential_store_delete` | Delete a stored credential by name |
+| `credential_store_update` | Update credential metadata (members, TTL, network policy) without re-entering the secret |
+| `stop_prompt` | Kill the active LLM process on a member. **Always call `TaskStop` after calling `stop_prompt`**.<br><br>**Use when:** a member is hung, working on the wrong thing, or needs to be cancelled. |
+
+See sub-documents for detailed usage:
+- `onboarding.md`  -  full 8-step member onboarding sequence
+- `permissions.md`  -  permission composition and denial handling
+- `profiles/`  -  stack permission profiles (base-dev, base-reviewer, node, python, go, etc.)  -  add new profiles here to support additional stacks or roles
+- `troubleshooting.md`  -  fleet tool troubleshooting by symptom
+- `skill-matrix.md`  -  skill installation matrix by project + VCS + role
+- `auth-github.md`, `auth-bitbucket.md`, `auth-azdevops.md`  -  VCS auth provisioning per provider
+- `beads.md`  -  Beads persistent task DB: commands, backlog ops, session recovery patterns
+
+## Beads  -  Persistent Task Tracking
+
+Beads (`bd` CLI) is installed automatically by `apra-fleet install`. It gives fleet users a persistent, dependency-aware task database that survives across sessions, branches, and members.
+
+**Run `bd` via `Bash` on the orchestrator  -  never via `execute_command` on a member.**
+
+See `beads.md` for the full command reference and workflow examples.
+
+## Secure Credentials
+
+The `{{secure.NAME}}` pattern lets you reference stored secrets in any command without ever exposing plaintext to the LLM or logs.
+
+**How it works:**
+1. Store a secret with `credential_store_set`  -  Fleet opens an OOB terminal prompt, so the value never appears in chat
+2. Reference it as `{{secure.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, or `provision_auth`
+3. Fleet resolves the token server-side before execution; LLM does not see the secret.
+
+**When to use:**
+- Any API key, token, or password that a member needs in a shell command
+- Rotating credentials: `credential_store_delete` then `credential_store_set`  -  no re-provisioning required
+- Pre-loading secrets before a dispatch so members can authenticate in commands autonomously
+
+NOTE: **`{{secure.NAME}}` only resolves in specific credential fields** (listed above). Using it in any other parameter (e.g. a prompt, a path field in a non-credential tool, or any other unsupported parameter) will pass the token string through literally  -  the secret will NOT be injected, and the raw handle name will be visible in logs. Only use `{{secure.NAME}}` in the fields documented above.
+
+**Access control (scoping):** Credentials can be scoped to specific members.
+- `members="*"` (default)  -  all members can access the credential
+- `members="alice,bob"`  -  only those members can access it
+- Scoping is enforced at resolve time  -  a member outside the allowed set receives an access-denied error
+- **Updating scope or metadata:** Use `credential_store_update` to change `members`, `ttl_seconds`, or `network_policy` without re-entering the secret. Use `credential_store_set` again only if you need to change the secret value (triggers OOB re-entry).
+
+**TTL (time-to-live):** Set `ttl_seconds` to auto-expire a credential. Expired credentials
+are rejected at resolve time with a clear error (not silently empty).
+
+Example: `credential_store_set  name=ci_token  ttl_seconds=3600`
+
+**Network egress policy:** Attach a network policy to a credential to control outbound
+network access for commands that use it:
+
+| Policy | Behaviour |
+|--------|-----------|
+| `'allow'` (default) | No restriction |
+| `'deny'` | Commands invoking network tools (curl, wget, ssh, git push, etc.) are blocked |
+| `'confirm'` | OOB prompt before the network call is allowed |
+
+## Member Identification
+
+All tools accept `member_id` (UUID) or `member_name` (friendly name) to identify a member. `member_id` takes precedence when both are provided.
+
+## Tool Boundaries
+
+- **Local members:** ALWAYS use fleet tools (`execute_command`, `execute_prompt`, `send_files`, etc.)  -  never SSH directly or bypass fleet infrastructure
+- Fleet tools are the canonical interface  -  all member interactions go through them
+
+## Dispatch Rules
+
+**Rule:** Shell commands (git, npm, bash scripts, file ops) -> `execute_command`. LLM reasoning tasks (write code, review, plan, analyse) -> `execute_prompt`. When in doubt: if a human could write the exact command string upfront, it's `execute_command`.
+
+- **`execute_prompt`**  -  always wrap in a background Agent: `Agent(run_in_background=true)`. No exceptions.
+- **`execute_command`**  -  any command that may take several seconds must be wrapped in a background Agent. Short reads (`cat`, `git status`, `echo`) can be called inline. Always use bash syntax  -  Git Bash is universally available on developer machines. Never use PowerShell or cmd.exe syntax, even on Windows members.
+- **When clubbing fleet calls into a background Agent:** Always name the tool explicitly in the subagent prompt  -  write "use `execute_command` to run..." or "use `execute_prompt` to dispatch...". Never leave tool selection implicit.
+- **`send_files` / `receive_files`**  -  transfers exceeding 1MB must use a background Agent.
+
+**Concurrent dispatch guard:** Only one `execute_prompt` can be in-flight per member at a time (enforced server-side). A second concurrent dispatch returns immediately with:
+
+```
+x execute_prompt is already running for "<member-name>"
+```
+
+Use `stop_prompt` to cancel the in-flight session before re-dispatching.
+
+## Pre-dispatch Checks
+
+Before dispatching any work:
+1. `fleet_status`  -  confirm member is idle (status must not be busy)
+2. Member must have completed onboarding  -  see `onboarding.md`
+
+Do not dispatch to a busy member. If busy, wait or re-check `member_detail`.
+
+## File Transfer
+
+Both `send_files` and `receive_files` are batch operations  -  always transfer all files in a single call, never one file per call.
+
+- `send_files`  -  push any files to a member: context files, plans, scripts, binaries, configs, or any other content. Takes `local_paths` (array of local file paths) and optional `dest_subdir` (destination subdirectory relative to work_folder on member; defaults to work_folder root, equivalent to `"."`). Always try to batch multiple files in a single call.
+- `receive_files`  -  pull files back: results, logs, build artifacts, updated configs, etc. Takes `remote_paths` (array of file paths on the member) and `local_dest_dir` (local directory to write files into). Always try to batch multiple files in a single call.
+
+**Directories and globs:** `send_files` accepts individual file paths only  -  directories and glob patterns are not supported yet. To transfer an entire directory, tar it locally and extract on the member:
+
+```
+1. execute_command on local: tar -czf /tmp/src.tar.gz -C /path/to src/
+2. send_files: local_paths=["/tmp/src.tar.gz"]
+3. execute_command on member: tar -xzf src.tar.gz && rm src.tar.gz
+```
+
+**Cross-OS transfers:** Both `send_files` and `receive_files` work bidirectionally for Linux<->Windows transfers (fleet host on Linux, member on Windows, and vice versa).
+
+## Permissions
+
+`compose_permissions` produces provider-native config automatically. See `permissions.md` for:
+- How to compose and deliver permissions before dispatching work
+- How to handle permission denials during execution
+- How to recompose when switching roles
+
+## execute_prompt Timeout Parameters
+
+`execute_prompt` accepts two independent timeout parameters:
+
+| Parameter | Semantics |
+|-----------|-----------|
+| `timeout_s` | **Inactivity timeout**  -  the session is killed only if no stdout/stderr output arrives for this many seconds. The timer resets on every output chunk. Active sessions (writing code, running tests, producing tokens) are never killed by this timer as long as output keeps flowing. Default: 300s (5 min). |
+| `max_total_s` | **Hard ceiling**  -  the session is killed after this total elapsed time in seconds regardless of activity. Optional; defaults to unlimited. |
+
+**When to use which:**
+
+- Use `timeout_s` for normal dispatch. It extends the deadline automatically as long as the member is active, so you don't need to over-estimate how long a task takes.
+- Use `max_total_s` only for tasks that must never run forever  -  CI pipelines, automated batch jobs, or any context where an unbounded runaway is unacceptable.
+- Both timers run concurrently; whichever fires first kills the process.
+
+## execute_prompt: Session Resume
+
+The `resume` parameter controls whether a prior session is continued:
+
+| Value | Behaviour |
+|-------|-----------|
+| `true` (default) | If a session ID is stored for this member, continues it. If none exists, starts fresh. |
+| `false` | Always starts a fresh session  -  ignores any stored session ID. |
+
+`resume` is boolean only. There is no way to target a specific session ID by value.
+The tool always resumes the most recently stored session for that member.
+
+**Automatic stale-session recovery:** If `resume=true` and the stored session has expired
+or the provider returns an error, `execute_prompt` retries once automatically with a fresh
+session. This recovery is transparent  -  no caller intervention required.
+
+**Provider support:**
+
+| Provider | Session resume | Notes |
+|----------|---------------|-------|
+| Claude | Full | `claude --resume <sessionId>` |
+| Antigravity (agy) | Full | `agy --conversation <sessionId>` |
+| Codex | Partial | `resume` command supported |
+| Copilot | None | Always starts fresh regardless of `resume` value |
+| Gemini | Full | Native session support |
+
+Session IDs are parsed from `execute_prompt` output and stored server-side per member.
+The output footer contains: `session: <sessionId>` when the provider supports it.
+
+## Unattended Execution Modes
+
+Configured via `register_member` or `update_member` with the `unattended` parameter:
+
+| Mode | Behaviour |
+|------|-----------|
+| `false` (default) | Interactive  -  member prompts for permission approvals |
+| `'auto'` | Trust the permissions config written by `compose_permissions`  -  auto-approves tools in the allow list |
+| `'dangerous'` | Skip all permission checks globally, bypassing the allow list |
+
+Per-provider flag behaviour:
+
+| Provider | `'auto'` flag | `'dangerous'` flag |
+|----------|--------------|-------------------|
+| Claude | `--permission-mode auto` | `--dangerously-skip-permissions` |
+| Antigravity (agy) | None (config-file only via `compose_permissions`) | `--dangerously-skip-permissions` |
+| Codex | `--ask-for-approval auto-edit` | `--sandbox danger-full-access --ask-for-approval never` |
+| Copilot | Not supported  -  warns and runs interactively | Not supported |
+| Gemini | None (config-file only via `compose_permissions`) | `--yolo` |
+
+Auto-approval is delivered via config files written by `compose_permissions`  -  call it before every dispatch.
+
+**Prefer `auto` + `compose_permissions` over `dangerous`**  -  `auto` scopes approval to the
+explicitly listed tools; `dangerous` bypasses all checks globally.
+
+**Always call `compose_permissions` before dispatch regardless of unattended mode.**
+The permissions config file must be delivered to the member's work folder before the CLI
+starts  -  `compose_permissions` does this for all providers.
+
+## Model Tiers
+
+Use model tiers: `cheap` for execution (commands, status, tests, deploys), `standard` for construction (code, config, devops), `premium` for planning, review, design, and architecture. The server resolves tiers to the appropriate model for each provider. User override always wins. When in doubt, prefer cheaper.
+
+Pass as `model: "cheap" | "standard" | "premium"` in `execute_prompt`.
+
+## Member Icons
+
+Icons are auto-assigned by the server and returned in `register_member` / `list_members` / `member_detail`. Prefix every member reference in output with their icon: ` alice: building auth module`.
+
+To override, use `update_member` with the icon parameter.
+
+## Update Notices
+
+`fleet_status` output may include a one-line update notice at the top when a newer release of apra-fleet is available:
+
+```
+[i] apra-fleet v0.1.8 is available (installed: v0.1.7). Run `/pm deploy apra-fleet` to update.
+```
+
+When you see this notice, surface it to the user verbatim before the rest of the status output. Do not suppress or paraphrase it. In JSON format the notice appears as an `updateAvailable` object with `latest` and `installed` fields  -  surface it the same way.
+
+## Provider Awareness
+
+| Concern | How to handle |
+|---------|---------------|
+| **Agent context file** | Use `member_detail` -> `llmProvider` to determine filename: CLAUDE.md (Claude), AGY.md (Antigravity), GEMINI.md (Gemini), AGENTS.md (Codex), COPILOT.md (Copilot) |
+| **Attribution config** | Claude-only (Step 2 in onboarding.md)  -  skip for all other providers |
+| **Timeouts** | Antigravity/Gemini members are slower -> use 2-3x timeout multiplier for `execute_prompt` dispatches to those members. Minimum `timeout_s: 900` for any non-trivial task. |
+
+## Fleet Logs
+
+The fleet server writes structured JSONL logs to `APRA_FLEET_DATA_DIR/logs/fleet-<pid>.log`. Multiple fleet instances each have their own log file. **To find the correct log file for the server you are talking to, call `fleet_status`  -  it reports the exact log file path** (e.g. `logging: ~/.apra-fleet/data/logs/fleet-40064.log`). Never guess by listing the directory.
+
+Use `jq` to read logs:
+
+```bash
+cat "$APRA_FLEET_DATA_DIR/logs/fleet-<pid>.log" | jq '.'
+```