@evalops/maestro 0.10.18 → 0.10.20

package/dist/cli/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACxC,MAAM,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,CAC5C,IAAI,OAAO,gGAAgG,CAC3G,EAAE,CAAC;IACJ,MAAM,KAAK,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,KAAK,CAC/C,iCAAiC,CACjC,EAAE,CAAC;IACJ,MAAM,OAAO,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG;QAC9C,4DAA4D;QAC5D,+DAA+D;QAC/D,iEAAiE;QACjE,2EAA2E;QAC3E,4FAA4F;QAC5F,wDAAwD;QACxD,0EAA0E;QAC1E,yEAAyE;QACzE,mEAAmE;QACnE,0EAA0E;QAC1E,+EAA+E;QAC/E,gFAAgF;QAChF,+EAA+E;QAC/E,mDAAmD;QACnD,oDAAoD;QACpD,mDAAmD;QACnD,wDAAwD;QACxD,0DAA0D;QAC1D,wCAAwC;KACxC;SACC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;SACjC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACf,MAAM,QAAQ,GAAG,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,KAAK,CACrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCA8CqC,CACrC,EAAE,CAAC;IACJ,MAAM,GAAG,GAAG,GAAG,cAAc,CAAC,wBAAwB,CAAC,GAAG,KAAK,CAC9D;;;;;;;;;;;;;;;;;;;;;;yEAsBuE,CACvE,EAAE,CAAC;IACJ,MAAM,WAAW,GAAG,GAAG,cAAc,CAAC,cAAc,CAAC,GAAG,KAAK,CAC5D;;;;;;;;;oEASkE,CAClE,EAAE,CAAC;IACJ,MAAM,UAAU,GAAG,GAAG,cAAc,CAAC,aAAa,CAAC,GAAG,KAAK,CAC1D;;;;0BAIwB,CACxB,EAAE,CAAC;IACJ,MAAM,kBAAkB,GAAG,GAAG,cAAc,CAAC,qBAAqB,CAAC,GAAG,KAAK,CAC1E;;;;;;;+EAO6E,CAC7E,EAAE,CAAC;IACJ,MAAM,aAAa,GAAG,GAAG,cAAc,CAAC,gBAAgB,CAAC,GAAG,KAAK,CAChE;;;;mEAIiE,CACjE,EAAE,CAAC;IACJ,MAAM,aAAa,GAAG,GAAG,cAAc,CAAC,gBAAgB,CAAC,GAAG,KAAK,CAChE;;;;qDAImD,CACnD,EAAE,CAAC;IACJ,MAAM,WAAW,GAAG,GAAG,cAAc,CAAC,cAAc,CAAC,GAAG,KAAK,CAC5D;;;;6EAI2E,CAC3E,EAAE,CAAC;IACJ,MAAM,mBAAmB,GAAG,GAAG,cAAc,CAAC,uBAAuB,CAAC,GAAG,KAAK,CAC7E;;;8FAG4F,CAC5F,EAAE,CAAC;IACJ,MAAM,eAAe,GAAG,GAAG,cAAc,CAAC,kBAAkB,CAAC,GAAG,KAAK,CACpE;;mEAEiE,CACjE,EAAE,CAAC;IACJ,MAAM,iBAAiB,GAAG,GAAG,cAAc,CAAC,kBAAkB,CAAC,GAAG,KAAK,CACtE;;2CAEyC,CACzC,EAAE,CAAC;IACJ,MAAM,KAAK,GAAG,GAAG,cAAc,CAAC,iBAAiB,CAAC,GAAG,KAAK,CACzD;;;;;;;;;;;;2FAYyF,CACzF,EAAE,CAAC;IAEJ,MAAM,gBAAgB,GAAG,GAAG,cAAc,CAAC,sBAAsB,CAAC,GAAG,KAAK,CACzE;;;mGAGiG,CACjG,EAAE,CAAC;IAEJ,OAAO,CAAC,GAAG,CACV;QACC,MAAM;QACN,KAAK;QACL,OAAO;QACP,QAAQ;QACR,GAAG;QACH,WAAW;QACX,UAAU;QACV,kBAAkB;QAClB,aAAa;QACb,WAAW;QACX,aAAa;QACb,mBAAmB;QACnB,eAAe;QACf,iBAAiB;QACjB,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG,KAAK,CAChC,cAAc,EACd,qBAAqB,EACrB,MAAM,CACN,EAAE;QACH,gBAAgB;QAChB,KAAK;KACL,CAAC,IAAI,CAAC,MAAM,CAAC,CACd,CAAC;AACH,CAAC","sourcesContent":["/**\n * @fileoverview CLI Help Output Module\n *\n * This module generates and displays the `--help` output for the Maestro CLI.\n * It provides a comprehensive overview of:\n *\n * - **Usage syntax** and common invocation patterns\n * - **Command-line options** for provider, model, session management, etc.\n * - **Environment variables** for API keys and configuration\n * - **Available tools** and their capabilities\n * - **Subcommands** like `maestro exec` for headless execution\n * - **Session management** commands and workflows\n *\n * ## Styling\n *\n * The output uses the application's theme system for consistent terminal styling:\n * - `heading()` - Main title styling\n * - `sectionHeading()` - Section headers\n * - `muted()` - De-emphasized text for descriptions\n * - `badge()` - Highlighted tips and hints\n *\n * @module cli/help\n */\nimport { badge, heading, muted, sectionHeading } from \"../style/theme.js\";\n\n/**\n * Prints the complete CLI help message to stdout.\n *\n * This function is invoked when the user runs `maestro --help` or `maestro -h`.\n * It formats and displays all available options, commands, and usage examples\n * using the terminal theme for consistent styling.\n *\n * @param version - The current Maestro version string (e.g., \"1.2.3\")\n *\n * @example\n * ```typescript\n * import { printHelp } from \"./help.js\";\n * import { version } from \"../../package.json\";\n *\n * if (args.includes(\"--help\")) {\n *   printHelp(version);\n *   process.exit(0);\n * }\n * ```\n */\nexport function printHelp(version: string) {\n\tconst header = `${heading(\"Maestro\")} ${muted(\n\t\t`v${version} by EvalOps — AI coding assistant with read, list, search, diff, bash, edit, write, todo tools`,\n\t)}`;\n\tconst usage = `${sectionHeading(\"Usage\")}${muted(\n\t\t\"maestro [options] [messages...]\",\n\t)}`;\n\tconst options = `${sectionHeading(\"Options\")}${[\n\t\t\"--provider <name>       Provider name (default: anthropic)\",\n\t\t\"-m, --model <id>        Model ID (default: claude-sonnet-4-5)\",\n\t\t\"--task-budget <tokens> API-side Anthropic task budget in tokens\",\n\t\t\"--models <patterns>     Comma-separated patterns for Ctrl+P model cycling\",\n\t\t\"--tools <names>         Comma-separated tool names to enable (e.g., read,search,list,find)\",\n\t\t\"--api-key <key>         API key (defaults to env vars)\",\n\t\t\"--system-prompt <text>  System prompt (default: coding assistant prompt)\",\n\t\t\"--append-system-prompt <text>  Append instructions to the system prompt\",\n\t\t\"--mode <mode>           Output mode: text (default), json, or rpc\",\n\t\t\"--auth <mode>           Credential mode: auto (default), api-key, claude\",\n\t\t\"--approval-mode <mode>  Action approvals: prompt (default in TUI), auto, fail\",\n\t\t\"--sandbox <mode>        Sandbox mode: docker, local, none (see docs/SAFETY.md)\",\n\t\t\"--port <n>              Port for `maestro web` (defaults to PORT env or 8080)\",\n\t\t\"--continue, -c          Continue previous session\",\n\t\t\"--resume, -r            Select a session to resume\",\n\t\t\"--session <path>        Use specific session file\",\n\t\t\"--no-session            Don't save session (ephemeral)\",\n\t\t\"--safe-mode             Enable extra safety restrictions\",\n\t\t\"--help, -h              Show this help\",\n\t]\n\t\t.map((line) => `  ${muted(line)}`)\n\t\t.join(\"\\n\")}`;\n\tconst examples = `${sectionHeading(\"Examples\")}${muted(\n\t\t`  # Interactive mode (no messages = interactive TUI)\n  maestro\n\n  # Single message\n  maestro \"List all .ts files in src/\"\n\n  # Multiple messages\n  maestro \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  maestro --continue \"What did we discuss?\"\n\n  # Use different model\n  maestro --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use Codex subscription models after \\`maestro codex login\\`\n  maestro --provider openai-codex --model gpt-5.5 \"Plan this migration\"\n\n  # Bootstrap EvalOps login, API key, and agent registration in one flow\n  maestro init\n\n  # Use EvalOps managed gateway models after \\`maestro init\\`\n  maestro --provider evalops --model gpt-4o-mini \"Say hello in one sentence\"\n\n  # Confirm managed mode sinks and EvalOps org identity\n  maestro status\n\n  # Export a portable session log\n  maestro export <session-id> ./session.jsonl --format jsonl\n\n  # Export a portable JSON archive with secret redaction\n  maestro export <session-id> ./session.json --format json --redact-secrets\n\n  # Import a portable session log into this workspace\n  maestro import ./session.json\n\n  # Start a hosted EvalOps runner session and wait for attach readiness\n  maestro remote start --workspace ws_123 --repo evalops/foo --branch main --ttl 90m --wait --verify\n\n  # Run a single-session hosted runtime pod entrypoint\n  maestro hosted-runner --runner-session-id mrs_abc --workspace-root /workspace --listen 0.0.0.0:8080\n\n  # Show usage analytics for the last 7 days\n  maestro stats\n\n  # Show usage analytics for one session\n  maestro stats --session <session-id>`,\n\t)}`;\n\tconst env = `${sectionHeading(\"Environment Variables:\")}${muted(\n\t\t`  GEMINI_API_KEY          - Google Gemini API key\n  OPENAI_API_KEY          - OpenAI API key\n  OPENAI_CODEX_TOKEN      - OpenAI Codex ChatGPT access token\n  OPENAI_CODEX_ACCOUNT_ID - ChatGPT account id when using a raw Codex token\n  ANTHROPIC_API_KEY       - Anthropic API key\n  CLAUDE_CODE_TOKEN       - Claude Code access token for --auth claude\n  ANTHROPIC_OAUTH_TOKEN   - Alternate env for Claude Code bearer tokens\n  MAESTRO_AGENT_DIR      - Session storage directory (default: ~/.maestro/agent)\n  MAESTRO_SANDBOX_MODE   - Sandbox mode: docker, local, none (default: none)\n  MAESTRO_CHANGELOG      - Set to off/false/hide/hidden/skip/0 to hide startup changelog banner\n  MAESTRO_TUI_MINIMAL    - Set to 1/true to disable animations and reduce TUI effects (SSH-friendly)\n  MAESTRO_TUI_TOOL_MAX_CHARS - Max chars shown per tool output panel (0 = unlimited)\n  MAESTRO_TUI_TOOL_MAX_LINES - Max lines shown per tool output panel (0 = unlimited)\n  MAESTRO_MEMORY_BASE - Durable memory service base URL\n  MAESTRO_MEMORY_ACCESS_TOKEN - Override bearer token for durable memory service\n  MAESTRO_MEMORY_TEAM_ID - Optional team scope for durable memory service\n  MAESTRO_SHARED_MEMORY_BASE - Shared memory base URL (Cloudflare Durable Objects worker)\n  MAESTRO_SHARED_MEMORY_API_KEY - API key for shared memory service\n  MAESTRO_REMOTE_RUNNER_URL - Hosted runner control-plane URL (default: https://runner.evalops.dev)\n  MAESTRO_REMOTE_RUNNER_TOKEN - Hosted runner bearer token override\n  MAESTRO_REMOTE_RUNNER_ORG_ID - EvalOps organization id for hosted runner sessions\n  MAESTRO_REMOTE_RUNNER_WORKSPACE_ID - EvalOps workspace id for hosted runner sessions\n  CODING_AGENT_DIR        - Legacy session directory override (fallback)`,\n\t)}`;\n\tconst execSection = `${sectionHeading(\"maestro exec\")}${muted(\n\t\t`  maestro exec \"Summarize recent changes\" --json\n\n  Flags:\n    --json                      Stream JSONL thread/turn events\n    --output-schema <file|json> Validate final assistant JSON against a schema\n    --output-last-message <path> Write the final assistant message to disk\n    --full-auto | --read-only   Force approval policy (auto or fail)\n    --sandbox <mode>            Run in sandbox: docker, local, none\n    --resume <sessionId>        Resume a prior exec session by id\n    --last                      Resume the most recent exec session`,\n\t)}`;\n\tconst webSection = `${sectionHeading(\"maestro web\")}${muted(\n\t\t`  # Start the bundled web UI + API server\n  maestro web\n\n  # Use a custom port\n  maestro web --port 3000`,\n\t)}`;\n\tconst portabilitySection = `${sectionHeading(\"Session Portability\")}${muted(\n\t\t`  maestro export <session-id> [output-path] --format json|jsonl [--redact-secrets]\n  maestro import <file.json|file.jsonl>\n\n  Notes:\n    - json preserves the full session in a portable wrapper object\n    - jsonl preserves the append-only session log verbatim unless redaction is requested\n    - --redact-secrets scrubs detected credentials from exported payloads\n    - import restores the session into the current workspace session directory`,\n\t)}`;\n\tconst memorySection = `${sectionHeading(\"maestro memory\")}${muted(\n\t\t`  maestro memory [status]         Show shared memory service status\n  maestro memory session <id>     Show per-session metrics\n  maestro memory audit <id> [n]   Show recent sync audit entries\n  maestro memory export <id>      Export metrics log as JSONL\n  maestro memory watch [id] [ms]  Poll status/metrics continuously`,\n\t)}`;\n\tconst remoteSection = `${sectionHeading(\"maestro remote\")}${muted(\n\t\t`  maestro remote start --workspace <id> --repo <repo> --branch <branch> [--ttl 90m] [--wait] [--verify]\n  maestro remote list --workspace <id> [--state running]\n  maestro remote attach <session-id> [--verify] [--print-env]\n  maestro remote extend <session-id> --ttl 2h\n  maestro remote stop <session-id> [--reason <text>]`,\n\t)}`;\n\tconst initSection = `${sectionHeading(\"maestro init\")}${muted(\n\t\t`  maestro init                         Login, create or reuse an API key, and register this agent\n  maestro init --rotate-key           Replace the stored agent MCP API key\n  maestro init --mcp-url <url>        Override the EvalOps agent MCP endpoint\n  maestro init --capability code:write Declare an agent-registry capability\n  maestro init --json                 Emit machine-readable bootstrap output`,\n\t)}`;\n\tconst hostedRunnerSection = `${sectionHeading(\"maestro hosted-runner\")}${muted(\n\t\t`  maestro hosted-runner --runner-session-id <id> --workspace-root <path> [--listen 0.0.0.0:8080]\n\n  Env mode:\n    MAESTRO_RUNNER_SESSION_ID=mrs_abc MAESTRO_WORKSPACE_ROOT=/workspace maestro hosted-runner`,\n\t)}`;\n\tconst sessionsSection = `${sectionHeading(\"Session Metadata\")}${muted(\n\t\t`  /session favorite|unfavorite      Toggle favorite for current session\n  /session summary \"<text>\"         Save a manual summary for current session\n  /sessions summarize <id>          Auto-summarize a saved session`,\n\t)}`;\n\tconst sessionsDiscovery = `${sectionHeading(\"Session Commands\")}${muted(\n\t\t`  /session [info|favorite|unfavorite|summary \"<text>\"]\n  /sessions [list|load <id>|favorite <id>|unfavorite <id>|summarize <id>]\n  (Also available via TUI command palette)`,\n\t)}`;\n\tconst tools = `${sectionHeading(\"Available Tools\")}${muted(\n\t\t`  read   - Read file contents\n  list   - List files in a directory\n  find   - Fast file search using fd (glob patterns)\n  search - Search files with ripgrep-style filtering\n  parallel_ripgrep - Run multiple ripgrep patterns in parallel and merge line ranges\n  diff   - Show git diffs (workspace, staged, or ranges)\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  todo   - Create TodoWrite-style checklists\n\n  Read-only tools: read,list,find,search,parallel_ripgrep,diff,status\n  Example: maestro --tools read,list,find,search,parallel_ripgrep,diff \"Analyze this code\"`,\n\t)}`;\n\n\tconst frameworkSection = `${sectionHeading(\"Framework Preference\")}${muted(\n\t\t`  /framework <id>            Set default stack (fastapi, express, node)\n  /framework <id> --workspace  Set workspace-scoped default\n  /framework list              Show available options\n  Precedence: policy (locked) > policy > env override > env default > workspace > user file > none`,\n\t)}`;\n\n\tconsole.log(\n\t\t[\n\t\t\theader,\n\t\t\tusage,\n\t\t\toptions,\n\t\t\texamples,\n\t\t\tenv,\n\t\t\texecSection,\n\t\t\twebSection,\n\t\t\tportabilitySection,\n\t\t\tmemorySection,\n\t\t\tinitSection,\n\t\t\tremoteSection,\n\t\t\thostedRunnerSection,\n\t\t\tsessionsSection,\n\t\t\tsessionsDiscovery,\n\t\t\t`${sectionHeading(\"Tips\")}${badge(\n\t\t\t\t\"Need models?\",\n\t\t\t\t\"maestro models list\",\n\t\t\t\t\"info\",\n\t\t\t)}`,\n\t\t\tframeworkSection,\n\t\t\ttools,\n\t\t].join(\"\\n\\n\"),\n\t);\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @fileoverview CLI Help Output Module\n *\n * This module generates and displays the `--help` output for the Maestro CLI.\n * It provides a comprehensive overview of:\n *\n * - **Usage syntax** and common invocation patterns\n * - **Command-line options** for provider, model, session management, etc.\n * - **Environment variables** for API keys and configuration\n * - **Available tools** and their capabilities\n * - **Subcommands** like `maestro exec` for headless execution\n * - **Session management** commands and workflows\n *\n * ## Styling\n *\n * The output uses the application's theme system for consistent terminal styling:\n * - `heading()` - Main title styling\n * - `sectionHeading()` - Section headers\n * - `muted()` - De-emphasized text for descriptions\n * - `badge()` - Highlighted tips and hints\n *\n * @module cli/help\n */\nimport { badge, heading, muted, sectionHeading } from \"../style/theme.js\";\n\ninterface CliHelpOption {\n\ttext: string;\n\thidden?: boolean;\n}\n\nconst CLI_OPTIONS: CliHelpOption[] = [\n\t{ text: \"--provider <name>       Provider name (default: anthropic)\" },\n\t{ text: \"-m, --model <id>        Model ID (default: claude-sonnet-4-5)\" },\n\t{ text: \"--task-budget <tokens> API-side Anthropic task budget in tokens\" },\n\t{\n\t\ttext: \"--models <patterns>     Comma-separated patterns for Ctrl+P model cycling\",\n\t},\n\t{\n\t\ttext: \"--tools <names>         Comma-separated tool names to enable (e.g., read,search,list,find)\",\n\t},\n\t{ text: \"--api-key <key>         API key (defaults to env vars)\" },\n\t{\n\t\ttext: \"--system-prompt <text>  System prompt (default: coding assistant prompt)\",\n\t},\n\t{\n\t\ttext: \"--append-system-prompt <text>  Append instructions to the system prompt\",\n\t},\n\t{ text: \"--mode <mode>           Output mode: text (default), json, or rpc\" },\n\t{\n\t\ttext: \"--auth <mode>           Credential mode: auto (default), api-key, claude\",\n\t},\n\t{\n\t\ttext: \"--approval-mode <mode>  Action approvals: prompt (default in TUI), auto, fail\",\n\t},\n\t{\n\t\ttext: \"--sandbox <mode>        Sandbox mode: read-only, workspace-write, danger-full-access, native, docker, local, none\",\n\t},\n\t{\n\t\ttext: \"--port <n>              Port for `maestro web` (defaults to PORT env or 8080)\",\n\t},\n\t{ text: \"--continue, -c          Continue previous session\" },\n\t{ text: \"--resume, -r            Select a session to resume\" },\n\t{ text: \"--session <path>        Use specific session file\" },\n\t{ text: \"--no-session            Don't save session (ephemeral)\" },\n\t{ text: \"--safe-mode             Enable extra safety restrictions\" },\n\t{\n\t\ttext: \"--replay <path|uri>     Open a scripted deterministic replay session\",\n\t},\n\t{\n\t\ttext: \"--record-scenario <path> Record assistant turns as a replay fixture\",\n\t},\n\t{ text: \"--help, -h              Show this help\" },\n\t{\n\t\ttext: \"--help-hidden          Show hidden support and staged-rollout flags\",\n\t\thidden: true,\n\t},\n\t{\n\t\ttext: \"--list-modes-all       List visible and hidden agent modes\",\n\t\thidden: true,\n\t},\n];\n\nfunction renderHelpOptions(options: CliHelpOption[], includeHidden: boolean) {\n\treturn options\n\t\t.filter((option) => includeHidden || option.hidden !== true)\n\t\t.map((option) => `  ${muted(option.text)}`)\n\t\t.join(\"\\n\");\n}\n\n/**\n * Prints the complete CLI help message to stdout.\n *\n * This function is invoked when the user runs `maestro --help` or `maestro -h`.\n * It formats and displays all available options, commands, and usage examples\n * using the terminal theme for consistent styling.\n *\n * @param version - The current Maestro version string (e.g., \"1.2.3\")\n *\n * @example\n * ```typescript\n * import { printHelp } from \"./help.js\";\n * import { version } from \"../../package.json\";\n *\n * if (args.includes(\"--help\")) {\n *   printHelp(version);\n *   process.exit(0);\n * }\n * ```\n */\nexport function printHelp(\n\tversion: string,\n\toptions?: { includeHidden?: boolean },\n) {\n\tconst includeHidden = options?.includeHidden === true;\n\tconst header = `${heading(\"Maestro\")} ${muted(\n\t\t`v${version} by EvalOps — AI coding assistant with read, list, search, diff, bash, edit, write, todo tools`,\n\t)}`;\n\tconst usage = `${sectionHeading(\"Usage\")}${muted(\n\t\t\"maestro [options] [messages...]\",\n\t)}`;\n\tconst renderedOptions = `${sectionHeading(\"Options\")}${renderHelpOptions(\n\t\tCLI_OPTIONS,\n\t\tincludeHidden,\n\t)}`;\n\tconst hiddenSupportSection = includeHidden\n\t\t? `${sectionHeading(\"Hidden Support Flags\")}${muted(\n\t\t\t\t\"  Hidden flags are external support surfaces. Keep them in docs/CONVENTIONS/staged-rollout-registry.json with an owner, telemetry event, and promotion/removal target.\",\n\t\t\t)}`\n\t\t: null;\n\tconst examples = `${sectionHeading(\"Examples\")}${muted(\n\t\t`  # Interactive mode (no messages = interactive TUI)\n  maestro\n\n  # Single message\n  maestro \"List all .ts files in src/\"\n\n  # Multiple messages\n  maestro \"Read package.json\" \"What dependencies do we have?\"\n\n  # Continue previous session\n  maestro --continue \"What did we discuss?\"\n\n  # Use different model\n  maestro --provider openai --model gpt-4o-mini \"Help me refactor this code\"\n\n  # Use Codex subscription models after \\`maestro codex login\\`\n  maestro --provider openai-codex --model gpt-5.5 \"Plan this migration\"\n  maestro codex doctor\n\n  # Bootstrap EvalOps login, API key, and agent registration in one flow\n  maestro init\n\n  # Use EvalOps managed gateway models after \\`maestro init\\`\n  maestro --provider evalops --model gpt-4o-mini \"Say hello in one sentence\"\n\n  # Confirm managed mode sinks and EvalOps org identity\n  maestro status\n\n  # Inspect mode-level subagent model dispatch before running a swarm\n  maestro modes describe smart\n\n  # Explain which instruction files and MCP context sources are visible\n  maestro context explain\n\n  # Compare context sources between two workspaces\n  maestro context diff ./before ./after\n\n  # Include live MCP resources and prompts in context diagnostics\n  maestro context explain --live-mcp\n\n  # Export a portable session log\n  maestro export <session-id> ./session.jsonl --format jsonl\n\n  # Export a portable JSON archive with secret redaction\n  maestro export <session-id> ./session.json --format json --redact-secrets\n\n  # Import a portable session log into this workspace\n  maestro import ./session.json\n\n  # Scaffold and validate progressive skill packages\n  maestro skill new processing-incidents --description \"Process incident reports. Use when the user asks for incident triage.\"\n  maestro skill lint .maestro/skills\n\n  # Start a hosted EvalOps runner session and wait for attach readiness\n  maestro remote start --workspace ws_123 --repo evalops/foo --branch main --ttl 90m --wait --verify\n\n  # Run a single-session hosted runtime pod entrypoint\n  maestro hosted-runner --runner-session-id mrs_abc --workspace-root /workspace --listen 0.0.0.0:8080\n\n  # Show usage analytics for the last 7 days\n  maestro stats\n\n  # Show usage analytics for one session\n  maestro stats --session <session-id>\n\n  # Reconstruct the timeline, trajectory, and evidence coverage for a saved run\n  maestro run inspect <session-id> --json\n  maestro run promote <session-id>\n\n  # Validate and run a deterministic scenario fixture\n  maestro scenario validate ./test/fixtures/agent-trajectory-scenarios/local-diagnostic-success.json\n  maestro scenario run ./test/fixtures/agent-trajectory-scenarios/local-diagnostic-success.json --junit ./tmp/scenario.xml\n\n  # Open a real agent session backed by a scripted model fixture\n  maestro --replay ./test/fixtures/scripted-replay/basic-tool-call.json\n  maestro --replay gs://evalops-prod-maestro-scenario-fixtures/maestro/scenarios/example.json\n\n  # Record a live run into a replayable scripted scenario\n  maestro --record-scenario ./tmp/recorded-scenario.json \"inspect package.json\"`,\n\t)}`;\n\tconst env = `${sectionHeading(\"Environment Variables:\")}${muted(\n\t\t`  GEMINI_API_KEY          - Google Gemini API key\n  OPENAI_API_KEY          - OpenAI API key\n  OPENAI_CODEX_TOKEN      - OpenAI Codex ChatGPT access token\n  OPENAI_CODEX_ACCOUNT_ID - ChatGPT account id when using a raw Codex token\n  ANTHROPIC_API_KEY       - Anthropic API key\n  CLAUDE_CODE_TOKEN       - Claude Code access token for --auth claude\n  ANTHROPIC_OAUTH_TOKEN   - Alternate env for Claude Code bearer tokens\n  MAESTRO_AGENT_DIR      - Session storage directory (default: ~/.maestro/agent)\n  MAESTRO_SANDBOX_MODE   - Sandbox mode: read-only, workspace-write, danger-full-access\n  MAESTRO_CHANGELOG      - Set to off/false/hide/hidden/skip/0 to hide startup changelog banner\n  MAESTRO_TUI_MINIMAL    - Set to 1/true to disable animations and reduce TUI effects (SSH-friendly)\n  MAESTRO_TUI_TOOL_MAX_CHARS - Max chars shown per tool output panel (0 = unlimited)\n  MAESTRO_TUI_TOOL_MAX_LINES - Max lines shown per tool output panel (0 = unlimited)\n  MAESTRO_MEMORY_BASE - Durable memory service base URL\n  MAESTRO_MEMORY_ACCESS_TOKEN - Override bearer token for durable memory service\n  MAESTRO_MEMORY_TEAM_ID - Optional team scope for durable memory service\n  MAESTRO_SHARED_MEMORY_BASE - Shared memory base URL (Cloudflare Durable Objects worker)\n  MAESTRO_SHARED_MEMORY_API_KEY - API key for shared memory service\n  MAESTRO_REMOTE_RUNNER_URL - Hosted runner control-plane URL (default: https://runner.evalops.dev)\n  MAESTRO_REMOTE_RUNNER_TOKEN - Hosted runner bearer token override\n  MAESTRO_REMOTE_RUNNER_ORG_ID - EvalOps organization id for hosted runner sessions\n  MAESTRO_REMOTE_RUNNER_WORKSPACE_ID - EvalOps workspace id for hosted runner sessions\n  CODING_AGENT_DIR        - Legacy session directory override (fallback)`,\n\t)}`;\n\tconst execSection = `${sectionHeading(\"maestro exec\")}${muted(\n\t\t`  maestro exec \"Summarize recent changes\" --json\n\n  Flags:\n    --json                      Stream JSONL thread/turn events\n    --output-schema <file|json> Validate final assistant JSON against a schema\n    --output-last-message <path> Write the final assistant message to disk\n    --full-auto | --read-only   Force approval policy (auto or fail)\n    --sandbox <mode>            Run in sandbox: read-only, workspace-write, danger-full-access, native, docker, local, none\n    --resume <sessionId>        Resume a prior exec session by id\n    --last                      Resume the most recent exec session`,\n\t)}`;\n\tconst webSection = `${sectionHeading(\"maestro web\")}${muted(\n\t\t`  # Start the bundled web UI + API server\n  maestro web\n\n  # Use a custom port\n  maestro web --port 3000`,\n\t)}`;\n\tconst portabilitySection = `${sectionHeading(\"Session Portability\")}${muted(\n\t\t`  maestro export <session-id> [output-path] --format json|jsonl [--redact-secrets]\n maestro import <file.json|file.jsonl>\n\n  Notes:\n    - json preserves the full session in a portable wrapper object\n    - jsonl preserves the append-only session log verbatim unless redaction is requested\n    - --redact-secrets scrubs detected credentials from exported payloads\n    - import restores the session into the current workspace session directory`,\n\t)}`;\n\tconst modesSection = `${sectionHeading(\"maestro modes\")}${muted(\n\t\t`  maestro modes list\n  maestro modes describe <mode> [--provider <provider>] [--json]\n\n  Prints the mode primary/fallback model policy and resolved subagent dispatch\n  table, including cross-provider overrides such as smart-mode coder lanes\n  routed to openai-codex/gpt-5.5.`,\n\t)}`;\n\tconst memorySection = `${sectionHeading(\"maestro memory\")}${muted(\n\t\t`  maestro memory [status]         Show shared memory service status\n  maestro memory session <id>     Show per-session metrics\n  maestro memory audit <id> [n]   Show recent sync audit entries\n  maestro memory export <id>      Export metrics log as JSONL\n  maestro memory watch [id] [ms]  Poll status/metrics continuously`,\n\t)}`;\n\tconst skillSection = `${sectionHeading(\"maestro skill\")}${muted(\n\t\t`  maestro skill list                 List available progressive skills\n  maestro skill inspect <name>       Print one skill package manifest\n  maestro skill install <source>     Validate and install an OSS skill package\n  maestro skill publish-check <src>  Validate an OSS skill package for publishing\n  maestro skill new <name>           Scaffold SKILL.md, reference/, scripts/, toolbox/, and mcp.json.example\n  maestro skill lint [path...]       Validate frontmatter, budget, mcp.json includeTools, and toolbox shape`,\n\t)}`;\n\tconst remoteSection = `${sectionHeading(\"maestro remote\")}${muted(\n\t\t`  maestro remote start --workspace <id> --repo <repo> --branch <branch> [--ttl 90m] [--wait] [--verify]\n  maestro remote list --workspace <id> [--state running]\n  maestro remote attach <session-id> [--verify] [--print-env]\n  maestro remote extend <session-id> --ttl 2h\n  maestro remote stop <session-id> [--reason <text>]`,\n\t)}`;\n\tconst operatingPlaneSection = `${sectionHeading(\"maestro operating-plane\")}${muted(\n\t\t`  maestro operating-plane status --thread-id <slack-thread> [--evidence-id <id>] [--auth-subject <subject>]\n  maestro operating-plane status --trace-id <id> --json\n\n  Fetches the Platform operating-plane ledger and prints a content-free value\n  proof report with identity, model/tool/approval/trace/evidence/cost status,\n  allowed evidence ids/revisions, blockers, next actions, and withheld reasons.`,\n\t)}`;\n\tconst runSection = `${sectionHeading(\"maestro run\")}${muted(\n\t\t`  maestro run inspect <session-id> [--json]\n  maestro run ledger <session-id>\n  maestro run replay <session-id>\n  maestro run promote <session-id>\n\n  Reconstructs a saved session into a timeline plus canonical agent trajectory\n  with prompt, tool, file-change, artifact, policy, diagnostic, compaction,\n  pending-wait, and MCP-context coverage. The ledger/replay/promote commands\n  expose the local AgentRuntime projection and dry-run Platform promotion plan.`,\n\t)}`;\n\tconst initSection = `${sectionHeading(\"maestro init\")}${muted(\n\t\t`  maestro init                         Login, create or reuse an API key, and register this agent\n  maestro init --rotate-key           Replace the stored agent MCP API key\n  maestro init --mcp-url <url>        Override the EvalOps agent MCP endpoint\n  maestro init --capability code:write Declare an agent-registry capability\n  maestro init --json                 Emit machine-readable bootstrap output`,\n\t)}`;\n\tconst hostedRunnerSection = `${sectionHeading(\"maestro hosted-runner\")}${muted(\n\t\t`  maestro hosted-runner --runner-session-id <id> --workspace-root <path> [--listen 0.0.0.0:8080]\n\n  Env mode:\n    MAESTRO_RUNNER_SESSION_ID=mrs_abc MAESTRO_WORKSPACE_ROOT=/workspace maestro hosted-runner`,\n\t)}`;\n\tconst sessionsSection = `${sectionHeading(\"Session Metadata\")}${muted(\n\t\t`  /session favorite|unfavorite      Toggle favorite for current session\n  /session summary \"<text>\"         Save a manual summary for current session\n  /sessions summarize <id>          Auto-summarize a saved session`,\n\t)}`;\n\tconst sessionsDiscovery = `${sectionHeading(\"Session Commands\")}${muted(\n\t\t`  /session [info|favorite|unfavorite|summary \"<text>\"]\n  /sessions [list|load <id>|favorite <id>|unfavorite <id>|summarize <id>]\n  (Also available via TUI command palette)`,\n\t)}`;\n\tconst tools = `${sectionHeading(\"Available Tools\")}${muted(\n\t\t`  read   - Read file contents\n  list   - List files in a directory\n  find   - Fast file search using fd (glob patterns)\n  search - Search files with ripgrep-style filtering\n  parallel_ripgrep - Run multiple ripgrep patterns in parallel and merge line ranges\n  diff   - Show git diffs (workspace, staged, or ranges)\n  bash   - Execute bash commands\n  edit   - Edit files with find/replace\n  write  - Write files (creates/overwrites)\n  todo   - Create TodoWrite-style checklists\n\n  Read-only tools: read,list,find,search,parallel_ripgrep,diff,status\n  Example: maestro --tools read,list,find,search,parallel_ripgrep,diff \"Analyze this code\"`,\n\t)}`;\n\n\tconst frameworkSection = `${sectionHeading(\"Framework Preference\")}${muted(\n\t\t`  /framework <id>            Set default stack (fastapi, express, node)\n  /framework <id> --workspace  Set workspace-scoped default\n  /framework list              Show available options\n  Precedence: policy (locked) > policy > env override > env default > workspace > user file > none`,\n\t)}`;\n\n\tconsole.log(\n\t\t[\n\t\t\theader,\n\t\t\tusage,\n\t\t\trenderedOptions,\n\t\t\thiddenSupportSection,\n\t\t\texamples,\n\t\t\tenv,\n\t\t\texecSection,\n\t\t\twebSection,\n\t\t\tportabilitySection,\n\t\t\tmodesSection,\n\t\t\tmemorySection,\n\t\t\tskillSection,\n\t\t\tinitSection,\n\t\t\trunSection,\n\t\t\tremoteSection,\n\t\t\toperatingPlaneSection,\n\t\t\thostedRunnerSection,\n\t\t\tsessionsSection,\n\t\t\tsessionsDiscovery,\n\t\t\t`${sectionHeading(\"Tips\")}${badge(\n\t\t\t\t\"Need models?\",\n\t\t\t\t\"maestro models list\",\n\t\t\t\t\"info\",\n\t\t\t)}`,\n\t\t\tframeworkSection,\n\t\t\ttools,\n\t\t]\n\t\t\t.filter((section): section is string => section !== null)\n\t\t\t.join(\"\\n\\n\"),\n\t);\n}\n"]}

package/dist/cli/system-prompt.d.ts

@@ -1,15 +1,33 @@
-import { type ComposerConfig } from "../config/index.js";
+import { type RuntimeConstraintContext } from "@evalops/contracts";
+import { type ComposerConfig, type PromptProjectDocManifest } from "../config/index.js";
 export declare function resolveSystemPromptOverride(value?: string): string | null;
 export declare function resolveExplicitSystemPromptSourcePaths(customPrompt?: string, appendPrompt?: string): string[];
-interface ContextFile {
+interface RuntimeConstraintDetectionOptions {
+    cwd?: string;
+    sandboxMode?: string | null;
+    sandboxEnabled?: boolean;
+    readOnly?: boolean;
+    env?: Record<string, string | undefined>;
+}
+export interface FinalizeSystemPromptOptions {
+    runtimeConstraints?: RuntimeConstraintContext | null;
+    promptContextManifest?: PromptProjectDocManifest;
+}
+export declare function detectRuntimeConstraintContext(options?: RuntimeConstraintDetectionOptions): RuntimeConstraintContext;
+export interface ContextFile {
     path: string;
     content: string;
 }
+export declare function truncateUtf8(buffer: Buffer, maxBytes: number): {
+    content: string;
+    bytes: number;
+};
 export declare function loadProjectContextFiles(cwdOverride?: string, options?: {
     config?: ComposerConfig;
 }): ContextFile[];
+export declare function buildFileCitationPromptFragment(cwd?: string): string;
 export declare function buildBundledSystemPromptBase(toolNames?: string[]): string;
-export declare function finalizeSystemPrompt(basePrompt: string, appendPrompt?: string, cwd?: string): string;
-export declare function buildSystemPrompt(customPrompt?: string, toolNames?: string[], appendPrompt?: string): string;
+export declare function finalizeSystemPrompt(basePrompt: string, appendPrompt?: string, cwd?: string, options?: FinalizeSystemPromptOptions): string;
+export declare function buildSystemPrompt(customPrompt?: string, toolNames?: string[], appendPrompt?: string, options?: FinalizeSystemPromptOptions): string;
 export {};
 //# sourceMappingURL=system-prompt.d.ts.map

package/dist/cli/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/cli/system-prompt.ts"],"names":[],"mappings":"AAYA,OAAO,EACN,KAAK,cAAc,EAInB,MAAM,oBAAoB,CAAC;AAgD5B,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAezE;AASD,wBAAgB,sCAAsC,CACrD,YAAY,CAAC,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACnB,MAAM,EAAE,CAQV;AA2GD,UAAU,WAAW;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAgJD,wBAAgB,uBAAuB,CACtC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,cAAc,CAAA;CAAO,GACvC,WAAW,EAAE,CA4Df;AAwCD,wBAAgB,4BAA4B,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAUzE;AAED,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,SAAgB,GACjB,MAAM,CAuBR;AAED,wBAAgB,iBAAiB,CAChC,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,YAAY,CAAC,EAAE,MAAM,GACnB,MAAM,CAKR"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/cli/system-prompt.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,KAAK,wBAAwB,EAI7B,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAI7B,MAAM,oBAAoB,CAAC;AAoD5B,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAezE;AASD,wBAAgB,sCAAsC,CACrD,YAAY,CAAC,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACnB,MAAM,EAAE,CAQV;AASD,UAAU,iCAAiC;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,2BAA2B;IAC3C,kBAAkB,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACrD,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;CACjD;AAmGD,wBAAgB,8BAA8B,CAC7C,OAAO,GAAE,iCAAsC,GAC7C,wBAAwB,CAkC1B;AA0GD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACd;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd,CA6CA;AAED,wBAAgB,uBAAuB,CACtC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,cAAc,CAAA;CAAO,GACvC,WAAW,EAAE,CAOf;AAgID,wBAAgB,+BAA+B,CAAC,GAAG,SAAgB,GAAG,MAAM,CAc3E;AAED,wBAAgB,4BAA4B,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAUzE;AAED,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,SAAgB,EACnB,OAAO,GAAE,2BAAgC,GACvC,MAAM,CAsCR;AAED,wBAAgB,iBAAiB,CAChC,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,2BAA2B,GACnC,MAAM,CAUR"}

package/dist/cli/system-prompt.js

@@ -1,9 +1,11 @@
-import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildRuntimeConstraintPrompt, isSandboxModeEnabled, } from "@evalops/contracts";
 import chalk from "chalk";
 import { buildSearchGuidelines } from "../agent/search-guidance.js";
-import { getAgentDir } from "../config/constants.js";
-import { loadConfig, resolveLoadedAppendSystemPromptPath, resolveProjectDocCandidateFilenames, } from "../config/index.js";
+import { loadPromptProjectDocManifest, resolveLoadedAppendSystemPromptPath, } from "../config/index.js";
+import { DEFAULT_GUARDED_FILE_RULES, findDefaultGuardedFileMatch, } from "../safety/guarded-files.js";
 // Tool descriptions for dynamic system prompt generation
 const TOOL_DESCRIPTIONS = {
     read: "Read file contents",
@@ -72,9 +74,120 @@ function loadAppendSystemPrompt(cwd) {
         ? resolveSystemPromptOverride(appendSystemPath)
         : null;
 }
+function readEnvFlag(env, name) {
+    const value = env[name]?.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function normalizeNetworkAccess(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized === "disabled" ||
+        normalized === "offline" ||
+        normalized === "none" ||
+        normalized === "no-network") {
+        return "disabled";
+    }
+    if (normalized === "restricted" ||
+        normalized === "firewall" ||
+        normalized === "gated") {
+        return "restricted";
+    }
+    if (normalized === "available" || normalized === "enabled") {
+        return "available";
+    }
+    return "unknown";
+}
+function resolveGitDirectoryAtPath(path) {
+    const gitPath = join(path, ".git");
+    try {
+        const gitStat = statSync(gitPath);
+        if (gitStat.isDirectory()) {
+            return gitPath;
+        }
+        if (!gitStat.isFile()) {
+            return null;
+        }
+        const gitFile = readFileSync(gitPath, "utf8");
+        const match = /^gitdir:\s*(.+?)\s*$/m.exec(gitFile);
+        const gitDir = match?.[1];
+        if (!gitDir) {
+            return null;
+        }
+        return resolve(path, gitDir);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveGitDirectory(cwd) {
+    let current = resolve(cwd);
+    while (true) {
+        const gitDir = resolveGitDirectoryAtPath(current);
+        if (gitDir) {
+            return gitDir;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function resolveGitCommonDirectory(gitDir) {
+    try {
+        const commonDir = readFileSync(join(gitDir, "commondir"), "utf8").trim();
+        if (commonDir) {
+            return resolve(gitDir, commonDir);
+        }
+    }
+    catch {
+        // Older/non-worktree repositories do not have a commondir file.
+    }
+    return gitDir;
+}
+function isShallowGitCheckout(cwd) {
+    const gitDir = resolveGitDirectory(cwd);
+    if (!gitDir) {
+        return false;
+    }
+    const commonGitDir = resolveGitCommonDirectory(gitDir);
+    return (existsSync(join(commonGitDir, "shallow")) ||
+        existsSync(join(gitDir, "shallow")));
+}
+export function detectRuntimeConstraintContext(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const sandboxMode = options.sandboxMode ??
+        env.MAESTRO_SANDBOX_MODE ??
+        env.CODEX_SANDBOX_MODE ??
+        env.MAESTRO_SANDBOX ??
+        null;
+    const networkAccess = readEnvFlag(env, "MAESTRO_OFFLINE_EVAL") ||
+        readEnvFlag(env, "CODEX_OFFLINE_EVAL")
+        ? "disabled"
+        : normalizeNetworkAccess(env.MAESTRO_NETWORK_ACCESS ?? env.CODEX_NETWORK_ACCESS);
+    return {
+        sandboxMode,
+        sandboxEnabled: options.sandboxEnabled ?? isSandboxModeEnabled(sandboxMode),
+        isShallowGitCheckout: isShallowGitCheckout(cwd),
+        readOnly: options.readOnly ??
+            (readEnvFlag(env, "MAESTRO_READ_ONLY") ||
+                readEnvFlag(env, "CODEX_READ_ONLY")),
+        networkAccess,
+        hostedRunner: readEnvFlag(env, "MAESTRO_HOSTED_RUNNER") ||
+            env.MAESTRO_RUNNER_KIND?.trim().toLowerCase() === "hosted",
+        firewallRestricted: readEnvFlag(env, "MAESTRO_FIREWALL_RESTRICTED") ||
+            readEnvFlag(env, "CODEX_FIREWALL_RESTRICTED"),
+        runnerImage: env.MAESTRO_RUNNER_IMAGE ?? null,
+    };
+}
 function buildGuidelines(toolNames, currentYear) {
     const guidelines = [];
     guidelines.push("You can emit multiple tool calls in a single turn; the runtime will execute independent calls in parallel. No batch tool is needed—just include separate tool calls when parallelism helps.");
+    guidelines.push("Emit independent safe tool calls together when their inputs are known, including read-only inspections, trusted MCP reads, and disjoint file mutations with explicit paths.");
+    guidelines.push("Avoid one-tool-per-turn inspection chains: when the next few read/list/search calls are already known and independent, emit them together.");
     guidelines.push(...buildSearchGuidelines(toolNames, currentYear));
     if (toolNames.has("bash")) {
         guidelines.push("Always use bash tool for file operations like ls, grep, find");
@@ -123,7 +236,7 @@ function buildGuidelines(toolNames, currentYear) {
     guidelines.push("Do NOT create summary documents or CHANGELOG files unless explicitly requested by the user");
     return `Guidelines:\n${guidelines.map((g) => `- ${g}`).join("\n")}`;
 }
-function truncateUtf8(buffer, maxBytes) {
+export function truncateUtf8(buffer, maxBytes) {
     let end = Math.min(maxBytes, buffer.length);
     if (end === 0) {
         return { content: "", bytes: 0 };
@@ -168,123 +281,24 @@ function truncateUtf8(buffer, maxBytes) {
     const slice = buffer.slice(0, Math.max(0, end));
     return { content: slice.toString("utf-8"), bytes: slice.length };
 }
-function readContextFile(filePath, maxBytes) {
-    if (maxBytes !== undefined && maxBytes > 0) {
-        const stats = statSync(filePath);
-        if (stats.size > maxBytes) {
-            const fd = openSync(filePath, "r");
-            try {
-                const buffer = Buffer.alloc(maxBytes);
-                const bytesRead = readSync(fd, buffer, 0, maxBytes, 0);
-                const truncated = truncateUtf8(buffer, bytesRead);
-                return {
-                    content: truncated.content,
-                    truncated: true,
-                    bytesRead: truncated.bytes,
-                    originalSize: stats.size,
-                    maxBytes,
-                };
-            }
-            finally {
-                closeSync(fd);
-            }
-        }
-    }
-    const content = readFileSync(filePath, "utf-8");
-    return {
-        content,
-        truncated: false,
-        bytesRead: Buffer.byteLength(content),
-    };
-}
-function loadContextFileFromDir(dir, options) {
-    const { candidates, maxBytes, remainingBytes } = options;
-    const budget = remainingBytes ?? maxBytes;
-    if (budget !== undefined && budget <= 0) {
-        return null;
-    }
-    for (const filename of candidates) {
-        const filePath = join(dir, filename);
-        if (existsSync(filePath)) {
-            try {
-                const result = readContextFile(filePath, budget);
-                if (!result)
-                    return null;
-                const note = result.truncated
-                    ? `\n\n[Truncated to ${result.bytesRead} bytes from ${result.originalSize} bytes.]`
-                    : "";
-                return {
-                    file: {
-                        path: filePath,
-                        content: `${result.content}${note}`,
-                    },
-                    bytesRead: result.bytesRead,
-                };
-            }
-            catch (error) {
-                console.error(chalk.yellow(`Warning: Could not read ${filePath}: ${error}`));
-            }
-        }
-    }
-    return null;
-}
-function resolveContextCandidates(config) {
-    return resolveProjectDocCandidateFilenames(config);
-}
 export function loadProjectContextFiles(cwdOverride, options = {}) {
-    const contextFiles = [];
-    const cwd = cwdOverride ?? process.cwd();
-    const config = options.config ?? loadConfig(cwd);
-    const candidates = resolveContextCandidates(config);
-    const maxBytesRaw = config.project_doc_max_bytes;
-    const maxBytes = typeof maxBytesRaw === "number"
-        ? Math.max(0, Math.floor(maxBytesRaw))
-        : undefined;
-    let remainingBytes = maxBytes;
-    if (remainingBytes === 0) {
-        return contextFiles;
-    }
-    const globalContextDir = resolve(getAgentDir());
-    const globalContext = loadContextFileFromDir(globalContextDir, {
-        candidates,
-        maxBytes,
-        remainingBytes,
-    });
-    if (globalContext) {
-        contextFiles.push(globalContext.file);
-        if (remainingBytes !== undefined) {
-            remainingBytes = Math.max(0, remainingBytes - globalContext.bytesRead);
-        }
-    }
-    const directories = [];
-    let currentDir = cwd;
-    const root = resolve("/");
-    while (true) {
-        directories.push(currentDir);
-        if (currentDir === root)
-            break;
-        const parentDir = resolve(currentDir, "..");
-        if (parentDir === currentDir)
-            break;
-        currentDir = parentDir;
-    }
-    directories.reverse();
-    for (const dir of directories) {
-        if (remainingBytes === 0)
-            break;
-        const contextFile = loadContextFileFromDir(dir, {
-            candidates,
-            maxBytes,
-            remainingBytes,
-        });
-        if (contextFile) {
-            contextFiles.push(contextFile.file);
-            if (remainingBytes !== undefined) {
-                remainingBytes = Math.max(0, remainingBytes - contextFile.bytesRead);
-            }
-        }
-    }
-    return contextFiles;
+    return loadPromptProjectDocManifest(cwdOverride, options.config).entries.map((entry) => ({
+        path: entry.path,
+        content: entry.content,
+    }));
+}
+function formatProjectContextFile(file) {
+    const filename = basename(file.path);
+    const dir = dirname(file.path);
+    return [
+        `# ${filename} instructions for ${dir}`,
+        "",
+        "<INSTRUCTIONS>",
+        file.content.trimEnd(),
+        "</INSTRUCTIONS>",
+        "",
+        "",
+    ].join("\n");
 }
 // Default tool names when no filter is applied
 const DEFAULT_TOOL_NAMES = [
@@ -322,6 +336,80 @@ function formatCurrentDateTime() {
         timeZoneName: "short",
     });
 }
+const GUARDED_WORKSPACE_SCAN_IGNORES = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".nx",
+    ".cache",
+    "tmp",
+]);
+function collectGuardedWorkspaceCategories(cwd, options = {}) {
+    const maxEntries = options.maxEntries ?? 5000;
+    const categories = new Set();
+    const stack = [cwd];
+    let entriesVisited = 0;
+    while (stack.length > 0 && entriesVisited < maxEntries) {
+        const dir = stack.pop();
+        if (!dir)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entriesVisited >= maxEntries)
+                break;
+            entriesVisited += 1;
+            const path = join(dir, entry.name);
+            const match = findDefaultGuardedFileMatch(path, { cwd });
+            if (match) {
+                categories.add(match.category);
+            }
+            if (entry.isDirectory() &&
+                !GUARDED_WORKSPACE_SCAN_IGNORES.has(entry.name)) {
+                stack.push(path);
+            }
+        }
+    }
+    return DEFAULT_GUARDED_FILE_RULES.map((rule) => rule.category).filter((category) => categories.has(category));
+}
+function buildGuardedWorkspacePromptFragment(cwd) {
+    const categories = collectGuardedWorkspaceCategories(cwd);
+    if (categories.length === 0) {
+        return null;
+    }
+    const categoryText = categories.join(", ");
+    return [
+        "# Guarded Workspace Paths",
+        "",
+        `This workspace contains paths covered by Maestro's default guarded-files policy: ${categoryText}.`,
+        "Ask for explicit user approval before attempting to read, list, search, execute against, or modify these guarded paths.",
+    ].join("\n");
+}
+export function buildFileCitationPromptFragment(cwd = process.cwd()) {
+    const examplePath = join(cwd, "src/auth/middleware.ts");
+    const exampleUri = `${pathToFileURL(examplePath).href}#L42`;
+    return [
+        "# File Citations",
+        "",
+        "When mentioning a workspace file in any user-facing response, link it using Markdown with a `file:///` URI so every surface can make the reference clickable.",
+        "Prefer the displayed text users expect to read, such as `src/auth/middleware.ts`, and percent-encode spaces and other URI characters in the link target.",
+        "Include known line references as URL fragments, such as `#L42`, `#L42-L48`, or `#L42C8`.",
+        "At GitHub comment boundaries, use repository blob URLs instead of local `file:///` URIs when repository metadata is available.",
+        `Good: See [src/auth/middleware.ts](${exampleUri}) for the validation logic.`,
+        "Bad: See src/auth/middleware.ts for the validation logic.",
+    ].join("\n");
+}
 export function buildBundledSystemPromptBase(toolNames) {
     const currentYear = new Date().getFullYear();
     const activeToolNames = toolNames ?? DEFAULT_TOOL_NAMES;
@@ -332,18 +420,27 @@ ${buildToolsSection(activeToolNames)}
 
 ${buildGuidelines(toolNameSet, currentYear)}`;
 }
-export function finalizeSystemPrompt(basePrompt, appendPrompt, cwd = process.cwd()) {
+export function finalizeSystemPrompt(basePrompt, appendPrompt, cwd = process.cwd(), options = {}) {
     const appendSource = resolveSystemPromptOverride(appendPrompt) ?? loadAppendSystemPrompt(cwd);
     const appendText = appendSource?.trim();
     let prompt = basePrompt;
-    const contextFiles = loadProjectContextFiles(cwd);
+    const contextFiles = options.promptContextManifest?.entries ?? loadProjectContextFiles(cwd);
     if (contextFiles.length > 0) {
         prompt += "\n\n# Project Context\n\n";
         prompt += "The following project context files have been loaded:\n\n";
-        for (const { path, content } of contextFiles) {
-            prompt += `## ${path}\n\n${content}\n\n`;
+        for (const file of contextFiles) {
+            prompt += formatProjectContextFile(file);
         }
     }
+    const guardedWorkspaceFragment = buildGuardedWorkspacePromptFragment(cwd);
+    if (guardedWorkspaceFragment) {
+        prompt += `\n\n${guardedWorkspaceFragment}\n`;
+    }
+    const runtimeConstraintPrompt = buildRuntimeConstraintPrompt(options.runtimeConstraints);
+    if (runtimeConstraintPrompt) {
+        prompt += `\n\n${runtimeConstraintPrompt}\n`;
+    }
+    prompt += `\n\n${buildFileCitationPromptFragment(cwd)}\n`;
     if (appendText) {
         prompt += "\n\n# Additional System Instructions\n\n";
         prompt += `${appendText}\n\n`;
@@ -352,9 +449,9 @@ export function finalizeSystemPrompt(basePrompt, appendPrompt, cwd = process.cwd
     prompt += `\nCurrent working directory: ${cwd}`;
     return prompt;
 }
-export function buildSystemPrompt(customPrompt, toolNames, appendPrompt) {
+export function buildSystemPrompt(customPrompt, toolNames, appendPrompt, options) {
     const promptSource = resolveSystemPromptOverride(customPrompt) ??
         buildBundledSystemPromptBase(toolNames);
-    return finalizeSystemPrompt(promptSource, appendPrompt);
+    return finalizeSystemPrompt(promptSource, appendPrompt, process.cwd(), options);
 }
 //# sourceMappingURL=system-prompt.js.map