foreman-worker-pi-sdk

name	foreman-worker-pi-sdk
description	Use when changing Foreman's Node/Pi worker bridge, detached worker config/env, Pi SDK sessions, custom tools, tool policy, observability, worker terminal events, or sandboxed Pi resource paths.

Foreman Worker Pi SDK

When to Use

Use this skill for changes in src/orchestrator/dispatcher.ts, src/orchestrator/agent-worker.ts, src/orchestrator/pi-sdk-runner.ts, src/orchestrator/pi-sdk-tools.ts, packages/foreman-pi-extensions/**, or worker env/config surfaces.

Process Boundary

• Dispatcher writes worker config under ~/.foreman/tmp/worker-<runId>.json, spawns a detached worker with cwd = worktreePath, strips CLAUDECODE, removes DATABASE_URL, and propagates FOREMAN_VCS_BACKEND.
• Worker code treats Elixir as authoritative for registered project/run/task state and must not open a direct database pool.
• Worktree path and project path differ; do not collapse them.

Pi Session Boundary

• runPhaseSession() builds guarded built-in tools, custom Foreman tools, tool policy, observability, and in-memory Pi sessions.
• allowedTools controls built-in tools; custom Foreman tools (send_mail, mail_read, mail_send, phase_handoff, artifact_write, validation_result, task_block, progress_update, ask_operator, abort_phase, needs_retry, safe_command_run, VCS/PR helpers) have their own flow and policy checks.
• Tool policy denial is a tool result/error payload, not a thrown process exception.

Sandboxed Resources

• Default FOREMAN_PI_EXTENSIONS mode disables user skills and prompt templates; Foreman must explicitly pass bundled skill paths through additionalSkillPaths.
• New bundled required skills must be included in getSandboxedPiResourcePaths() through a shared list, not hardcoded one-by-one.

Terminal Semantics

• Preserve authoritative terminal run/task events; launcher process-exit inference is fallback diagnostics only.
• Do not mark a task complete just because a worker process exited zero if required phase artifacts/events are missing.

Verification

• Target src/orchestrator/__tests__/pi-sdk-runner.test.ts for resource path/sandbox changes.
• Target worker/phase tests for custom tool or terminal status changes.