@amistio/cli 0.1.39 → 0.1.41

package/README.md

@@ -13,6 +13,8 @@ The package install provides the `amistio` command and the optional `amistio-hos
 
 For enterprise setup, use the web Runner panel as the primary guide. It shows repository, pairing code, GitHub access, AI provider, local runner, and verification readiness with plain next actions; advanced CLI logs remain secondary diagnostics. The panel also shows trust/privacy boundaries, cost forecast and budget posture, runner health, blockers, verification health, and runner-version distribution from safe runner metadata.
 
+Runner execution profiles make runtime readiness explicit before local AI/tool execution. `amistio run --watch --execution-profile hostWorktree` keeps the default ADR-scoped Git worktree and checks Git, Node, Corepack, package manager, scripts, dependencies, and setup state. `--execution-profile hostWorktreeWithSetup --setup-package-manager-install` permits only the fixed package-manager install command inferred from package metadata, then rechecks readiness. `--execution-profile dockerWorkspace` validates Docker availability and a safe envelope mounted only to the worktree, rejecting privileged mode, host networking, extra mounts, and arbitrary environment injection; current runners still block approved work until containerized harness execution is enabled.
+
 Optional host helpers are configured outside the SaaS with `AMISTIO_HOST_HELPER_PATH`. The official npm package ships `amistio-host-helper` for Level 1 supervised process execution diagnostics; enable it with `AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper)` on reviewed runner machines and confirm `amistio host-helper status` plus `amistio host-helper conformance`. PTY and sandbox requests use a helper only when its versioned handshake advertises support; otherwise the CLI returns deterministic unsupported results instead of silently downgrading. The npm helper does not advertise PTY or sandbox support. Helper request envelopes include allowlisted environment values, explicit sandbox policy metadata, and bounded normalized output, and must never include provider tokens, OAuth material, runner API tokens, local auth files, or arbitrary SaaS-originated shell text.
 
 Before publishing the CLI, run the package release gate:
@@ -51,6 +53,9 @@ If no supported tool is available, install and authenticate one of the supported
 ```sh
 amistio sync watch
 amistio run --watch --tool opencode
+amistio run --watch --execution-profile hostWorktree
+amistio run --watch --execution-profile hostWorktreeWithSetup --setup-package-manager-install
+amistio run --watch --execution-profile dockerWorkspace
 amistio run --watch --tool opencode --provider anthropic --model-id claude-opus-4.6 --reasoning-effort xhigh
 amistio run --watch --max-concurrent-work 2 --tool opencode
 amistio run --watch --background --tool opencode
@@ -77,12 +82,14 @@ When `--tool codex` uses the Codex SDK, intermediate progress can be quiet until
 
 The runner advertises its supported work kinds in heartbeats. Current runners can claim read-only `projectContextRefresh` jobs from the workspace Context panel and create due runner-driven refreshes when no fresh approved map exists. Context refreshes inspect the paired checkout locally without modifying files and submit only bounded summaries, slices, entities, relations, safe citations, confidence, freshness, and repo-relative paths. If a submitted context refresh contains unsafe evidence, unsafe paths, or a map too large to store safely, Amistio marks the refresh failed with a safe reason instead of storing the rejected raw result. Approved maps are reused as context packs for source-aware assistant and impact-preview work. Current runners can also claim read-only issue diagnosis jobs from the web Issues panel, generate root-cause analysis and a proposed fix, and submit that result without modifying source. They can claim manual read-only `appEvaluationScan` jobs from the workspace Evaluate panel and create at most one due hourly evaluation during normal watch/background polling when app evaluation is enabled for the repository link. Evaluation results contain bounded summaries, safe evidence, suggested actions, lifecycle proposals, and repo-relative paths only. Current runners can also claim manual read-only `securityPostureScan` jobs from the workspace Security panel and create due daily posture checks during normal watch/background polling. Security scan results contain bounded summaries, standard references, safe evidence, and repo-relative paths only. Current runners can claim manual read-only `testQualityScan` jobs from the workspace Test panel and create one due daily Test scan per repository when Test quality is enabled. Test scans run only existing lint, typecheck, test, coverage, build, or verify commands and submit bounded command summaries, coverage summaries, safe findings, blocked reasons, warnings, and repo-relative paths. Missing tests, missing coverage, low coverage, failing checks, flaky tests, and test gaps create reviewable plan-backed findings in the app. Current runners also claim `implementationTestGate` jobs before implementation completion, PR handoff, or runner-managed push; a passing gate is required unless the web Test panel records an audited override. Blocked implementation Test gates submit structured Test findings, such as `blockedEnvironment`, with safe evidence, a suggested action, and a verification plan. Current runners can claim read-only `implementationVerification` jobs from Tasks to prove whether completed implementation work actually landed; verification submits bounded acceptance-criteria evidence, checks, gaps, outcome, and recommendation without mutating source. Source, secrets, environment variables, command lines, process lists, credentials, provider sessions, and arbitrary local paths stay local. Implementation or cleanup is queued separately only after the user approves an issue analysis, app evaluation finding, security remediation plan, or Test quality plan in the app.
 
-Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as `.env.local` or `.env.test.local` from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status. It then commits all source and artifact changes, fetches and rebases from the linked remote's default branch, pushes an `amistio/work/...` branch, opens or reuses a pull request with the locally authenticated `gh` CLI, reports only safe PR and artifact-inclusion metadata to Amistio, and removes the local worktree after the PR URL is durable. Artifact-only materialization changes still create or reuse a PR; no-change completion requires no source changes and no approved artifact changes, and runner-created no-change worktrees are removed after final clean checks. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and `gh auth status`. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked with safe recovery choices; source files and patches are not uploaded to Amistio. The Work panel can queue scoped Retry handoff or Retry cleanup commands to the paired runner for the same work item, branch, and worktree key. Rebase conflicts capture bounded repo-relative conflict files and try `git rebase --abort` so the implementation branch can be retried or manually reviewed without leaving an active rebase. Dirty, unmerged, or ambiguous worktrees are preserved rather than discarded.
+Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as `.env.local` or `.env.test.local` from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status. It then commits all source and artifact changes, fetches and rebases from the linked remote's default branch, pushes an `amistio/work/...` branch, opens or reuses a pull request with the locally authenticated `gh` CLI, reports only safe PR and artifact-inclusion metadata to Amistio, and removes the local worktree after the PR URL is durable. Artifact-only materialization changes still create or reuse a PR; no-change completion requires no source changes and no approved artifact changes, and runner-created no-change worktrees are removed after final clean checks. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and `gh auth status`. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked with safe recovery choices; source files and patches are not uploaded to Amistio. The Work panel can queue scoped Retry handoff or Retry cleanup commands only to the runner that owns the preserved worktree for the same work item, branch, and worktree key. Rebase conflicts capture bounded repo-relative conflict files and try `git rebase --abort` so the implementation branch can be retried or manually reviewed without leaving an active rebase. Dirty, unmerged, or ambiguous worktrees are preserved rather than discarded.
 
-Failed or stale work can be requeued from the web Tasks panel. Requeue creates a new linked work attempt and preserves the original terminal attempt for audit history; it is blocked while equivalent work is already active or when the paired runner does not advertise the needed work kind. Completed implementation status is separate from proof: queue `implementationVerification` from Tasks when a plan needs source-aware evidence before cleanup or implementation status decisions.
+Failed or stale work can be requeued from the web Tasks panel. Requeue creates a new linked work attempt and preserves the original terminal attempt for audit history; Requeue all sends one backend batch that recomputes safe candidates, reports already-active and skipped rows, and still uses linked attempts. Requeue is blocked while equivalent work is already active or when the paired runner does not advertise the needed work kind. Completed implementation status is separate from proof: queue `implementationVerification` from Tasks when a plan needs source-aware evidence before cleanup or implementation status decisions.
 
 Runner setup and local-tool execution use bounded failure controls. `amistio run --watch` retries Git worktree preflight failures by releasing the claim for another attempt, then fails the work item after `--max-preflight-attempts` attempts, defaulting to 3. Active local-tool runs renew the work lease, and `--tool-timeout-seconds` caps tool execution, defaulting to 1800 seconds.
 
+The environment doctor blocks work before local AI/tool execution when `git`, `node`, Corepack, the package manager, required package scripts, dependencies, setup allowlist, Docker, or the requested execution profile is not ready. Work and Runner surfaces receive sanitized profile/readiness metadata only; raw host paths, command lines, environment values, and secrets are not uploaded.
+
 Runner watch mode defaults to one claim lane. `--max-concurrent-work <count>` enables bounded parallel claim lanes for one paired runner, capped at 4. The server enforces one active lease per runner lane, honors the advertised capacity, and keeps equivalent implementation scopes serialized through Git worktree locks; use separate lanes for independent work, not multiple attempts at the same ADR scope.
 
 Watch mode prints a completed-work success once per work item, keeps fresh completion visible briefly, and returns old completed work to the ready state when no queued, running, blocked, failed, review, or runner-readiness action needs attention.

package/dist/index.js

@@ -4,7 +4,7 @@
 import { createHash as createHash9, randomUUID as randomUUID3 } from "node:crypto";
 import { writeFile as writeFile12 } from "node:fs/promises";
 import os9 from "node:os";
-import path18 from "node:path";
+import path19 from "node:path";
 import { Command } from "commander";
 
 // ../shared/src/schemas.ts
@@ -551,6 +551,45 @@ var runnerResourceUsageSchema = z.object({
 });
 var runnerClaimLaneIdSchema = z.string().trim().min(1).max(80);
 var workIsolationModeSchema = z.enum(["none", "primaryCheckout", "branch", "gitWorktree"]);
+var runnerExecutionEnvironmentProfileSchema = z.enum(["hostWorktree", "hostWorktreeWithSetup", "dockerWorkspace", "cloudSandbox"]);
+var runnerEnvironmentBlockerReasonSchema = z.enum([
+  "missingToolchain",
+  "missingPackageManager",
+  "missingCorepack",
+  "missingScript",
+  "dependenciesNotReady",
+  "dockerUnavailable",
+  "dockerProfileInvalid",
+  "setupCommandNotAllowed",
+  "setupFailed",
+  "unsupportedProfile"
+]);
+var runnerEnvironmentReadinessStatusSchema = z.enum(["ready", "blocked"]);
+var runnerEnvironmentCheckStatusSchema = z.enum(["passed", "blocked", "warning", "skipped"]);
+var runnerEnvironmentBlockerSchema = z.object({
+  reason: runnerEnvironmentBlockerReasonSchema,
+  summary: z.string().trim().min(1).max(600),
+  remediation: z.string().trim().min(1).max(600).optional(),
+  safePaths: z.array(safeRepoPathSchema).max(20).default([])
+}).strict();
+var runnerEnvironmentCheckSchema = z.object({
+  checkId: z.string().trim().min(1).max(80),
+  title: z.string().trim().min(1).max(120),
+  status: runnerEnvironmentCheckStatusSchema,
+  reason: runnerEnvironmentBlockerReasonSchema.optional(),
+  summary: z.string().trim().min(1).max(600).optional(),
+  safePaths: z.array(safeRepoPathSchema).max(20).default([])
+}).strict();
+var runnerEnvironmentReadinessSchema = z.object({
+  profile: runnerExecutionEnvironmentProfileSchema,
+  status: runnerEnvironmentReadinessStatusSchema,
+  summary: z.string().trim().min(1).max(1e3),
+  checks: z.array(runnerEnvironmentCheckSchema).max(40).default([]),
+  blockers: z.array(runnerEnvironmentBlockerSchema).max(20).default([]),
+  warnings: z.array(z.string().trim().min(1).max(600)).max(20).default([]),
+  safePaths: z.array(safeRepoPathSchema).max(30).default([]),
+  checkedAt: isoDateTimeSchema.optional()
+}).strict();
 var repositoryLinkSourceSchema = z.enum(["web", "cli"]);
 var repositoryCloneStatusSchema = z.enum(["notCloned", "cloned", "validated", "failed"]);
 var repositoryBrainAutoSyncStatusSchema = z.enum(["disabled", "enabledInactive", "active", "synced", "failed", "blocked", "conflicted"]);
@@ -813,6 +852,8 @@ var workItemSchema = baseItemSchema.extend({
   executionBranch: z.string().min(1).optional(),
   executionWorktreeKey: z.string().min(1).optional(),
   isolationMode: workIsolationModeSchema.optional(),
+  executionEnvironmentProfile: runnerExecutionEnvironmentProfileSchema.optional(),
+  executionEnvironmentReadiness: runnerEnvironmentReadinessSchema.optional(),
   repositoryLockId: z.string().min(1).optional(),
   baseRevision: z.string().min(1).optional(),
   baseContentHash: z.string().min(1).optional(),
@@ -850,6 +891,9 @@ var runnerHeartbeatItemSchema = baseItemSchema.extend({
   supportedWorkKinds: z.array(workKindSchema).optional(),
   supportsBranchIsolation: z.boolean().optional(),
   supportsGitWorktreeIsolation: z.boolean().optional(),
+  supportedExecutionEnvironmentProfiles: z.array(runnerExecutionEnvironmentProfileSchema).optional(),
+  currentExecutionEnvironmentProfile: runnerExecutionEnvironmentProfileSchema.optional(),
+  environmentReadiness: runnerEnvironmentReadinessSchema.optional(),
   maxConcurrentWork: z.number().int().min(1).max(4).optional(),
   activeClaimLaneIds: z.array(runnerClaimLaneIdSchema).max(4).optional(),
   currentWorkItemId: z.string().min(1).optional(),
@@ -1255,6 +1299,35 @@ var projectSystemDiagramGraphManifestSchema = z.object({
   unknowns: z.array(z.string().trim().min(1).max(300)).default([]),
   warnings: z.array(z.string().trim().min(1).max(600)).default([])
 });
+var projectSystemDiagramAutomationStatusSchema = z.enum(["current", "refreshing", "stale", "proposed", "degraded", "waitingForRunner", "blocked"]);
+var projectSystemDiagramProposalChangeKindSchema = z.enum(["node", "edge", "group", "boundary", "view", "mermaid", "metadata"]);
+var projectSystemDiagramProposalChangeSchema = z.object({
+  proposalId: z.string().trim().min(1).max(200),
+  kind: projectSystemDiagramProposalChangeKindSchema,
+  title: z.string().trim().min(1).max(160),
+  summary: z.string().trim().min(1).max(1200),
+  viewIds: z.array(z.string().trim().min(1).max(160)).default([]),
+  nodeIds: z.array(z.string().trim().min(1).max(200)).default([]),
+  edgeIds: z.array(z.string().trim().min(1).max(220)).default([]),
+  citations: z.array(projectContextCitationSchema).default([])
+});
+var projectSystemDiagramAutomationSchema = z.object({
+  status: projectSystemDiagramAutomationStatusSchema,
+  reason: z.string().trim().min(1).max(1e3).optional(),
+  trigger: z.string().trim().min(1).max(80).optional(),
+  sourceContextMapRevision: z.number().int().positive().optional(),
+  sourceBrainRevision: z.number().int().nonnegative().optional(),
+  lastCheckedAt: isoDateTimeSchema.optional(),
+  lastRefreshAt: isoDateTimeSchema.optional(),
+  lastRefreshResult: z.enum(["current", "regenerated", "proposalCreated", "missRecorded", "blocked", "degraded"]).optional(),
+  staleEdgeCount: z.number().int().nonnegative().default(0),
+  unreadableViewCount: z.number().int().nonnegative().default(0),
+  waitingForRunner: z.boolean().default(false),
+  proposedChangeCount: z.number().int().nonnegative().default(0),
+  proposalChanges: z.array(projectSystemDiagramProposalChangeSchema).default([]),
+  missCount: z.number().int().nonnegative().default(0),
+  misses: z.array(z.string().trim().min(1).max(300)).default([])
+});
 var projectSystemDiagramItemSchema = baseItemSchema.extend({
   type: z.literal("projectSystemDiagram"),
   projectId: z.string().min(1),
@@ -1274,6 +1347,7 @@ var projectSystemDiagramItemSchema = baseItemSchema.extend({
   approvedAt: isoDateTimeSchema.optional(),
   generatedAt: isoDateTimeSchema,
   supersedesDiagramId: z.string().min(1).optional(),
+  automation: projectSystemDiagramAutomationSchema.optional(),
   error: z.string().max(1e3).optional()
 });
 var projectContextMapItemSchema = baseItemSchema.extend({
@@ -2353,10 +2427,10 @@ function computeProjectNextAction(input) {
   const queuedPlanRevision = latestWorkItem(input.workItems.filter((item) => item.workKind === "planRevision" && item.status === "approved"));
   const queuedImplementation = latestWorkItem(input.workItems.filter((item) => item.workKind !== "brainGeneration" && item.workKind !== "planRevision" && item.status === "approved"));
   const queuedWork = queuedBrainGeneration ?? queuedPlanRevision ?? queuedImplementation;
-  const readiness = getSharedRunnerReadiness(pairedRepositoryLinks, input.runnerHeartbeats, nowMs);
-  if (queuedWork && !readiness.ready) {
+  const readiness2 = getSharedRunnerReadiness(pairedRepositoryLinks, input.runnerHeartbeats, nowMs);
+  if (queuedWork && !readiness2.ready) {
     const title = queuedWork.workKind === "brainGeneration" ? "Brain generation is queued" : queuedWork.workKind === "planRevision" ? "Plan revision is queued" : "Implementation is queued";
-    return runnerWaitAction(readiness, title);
+    return runnerWaitAction(readiness2, title);
   }
   if (queuedBrainGeneration) {
     return workAction(queuedBrainGeneration, "brainGenerationQueued", "runner", "warning", "Brain generation queued", "The local runner can claim this queued brain-generation work.");
@@ -2367,8 +2441,8 @@ function computeProjectNextAction(input) {
   if (queuedImplementation) {
     return workAction(queuedImplementation, "implementationQueued", "runner", "warning", "Implementation queued", "The local runner can claim approved implementation work.");
   }
-  if (!readiness.ready) {
-    return runnerWaitAction(readiness, "Runner setup needed");
+  if (!readiness2.ready) {
+    return runnerWaitAction(readiness2, "Runner setup needed");
   }
   const completedWork = latestWorkItem(input.workItems.filter((item) => item.status === "completed" && isFreshCompletedWork(item, nowMs)));
   if (completedWork) {
@@ -2380,38 +2454,38 @@ function computeProjectNextAction(input) {
     tone: "success",
     title: "Ready for the next task",
     message: "The repository and runner are ready for a new project-brain request.",
-    ...readiness.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness.repositoryLink.repositoryLinkId } : {},
-    ...readiness.heartbeat?.runnerId ? { runnerId: readiness.heartbeat.runnerId } : {},
-    ...readiness.heartbeat?.lastSeenAt ? { updatedAt: readiness.heartbeat.lastSeenAt } : {}
+    ...readiness2.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness2.repositoryLink.repositoryLinkId } : {},
+    ...readiness2.heartbeat?.runnerId ? { runnerId: readiness2.heartbeat.runnerId } : {},
+    ...readiness2.heartbeat?.lastSeenAt ? { updatedAt: readiness2.heartbeat.lastSeenAt } : {}
   };
 }
 function formatProjectNextAction(action) {
   return `${action.title}: ${action.message}${action.detail ? ` ${action.detail}` : ""}`;
 }
-function runnerWaitAction(readiness, fallbackTitle) {
-  const repositoryName = readiness.repositoryLink?.repoName ?? "the paired repository";
-  if (readiness.reason === "runnerOffline") {
+function runnerWaitAction(readiness2, fallbackTitle) {
+  const repositoryName = readiness2.repositoryLink?.repoName ?? "the paired repository";
+  if (readiness2.reason === "runnerOffline") {
     return {
       kind: "runnerOffline",
       actor: "user",
       tone: "danger",
       title: "Restart the runner",
       message: `The runner for ${repositoryName} is offline. Start amistio run --watch from the paired checkout.`,
-      ...readiness.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness.repositoryLink.repositoryLinkId } : {},
-      ...readiness.heartbeat?.runnerId ? { runnerId: readiness.heartbeat.runnerId } : {},
-      ...readiness.heartbeat?.lastSeenAt ? { updatedAt: readiness.heartbeat.lastSeenAt } : {}
+      ...readiness2.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness2.repositoryLink.repositoryLinkId } : {},
+      ...readiness2.heartbeat?.runnerId ? { runnerId: readiness2.heartbeat.runnerId } : {},
+      ...readiness2.heartbeat?.lastSeenAt ? { updatedAt: readiness2.heartbeat.lastSeenAt } : {}
     };
   }
-  if (readiness.reason === "runnerStale") {
+  if (readiness2.reason === "runnerStale") {
     return {
       kind: "runnerStale",
       actor: "user",
       tone: "warning",
       title: "Refresh the runner",
       message: `The runner for ${repositoryName} has not checked in recently. Restart amistio run --watch from the paired checkout.`,
-      ...readiness.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness.repositoryLink.repositoryLinkId } : {},
-      ...readiness.heartbeat?.runnerId ? { runnerId: readiness.heartbeat.runnerId } : {},
-      ...readiness.heartbeat?.lastSeenAt ? { updatedAt: readiness.heartbeat.lastSeenAt } : {}
+      ...readiness2.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness2.repositoryLink.repositoryLinkId } : {},
+      ...readiness2.heartbeat?.runnerId ? { runnerId: readiness2.heartbeat.runnerId } : {},
+      ...readiness2.heartbeat?.lastSeenAt ? { updatedAt: readiness2.heartbeat.lastSeenAt } : {}
     };
   }
   return {
@@ -2420,7 +2494,7 @@ function runnerWaitAction(readiness, fallbackTitle) {
     tone: "warning",
     title: fallbackTitle,
     message: `Start amistio run --watch from ${repositoryName} so the local runner can claim work.`,
-    ...readiness.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness.repositoryLink.repositoryLinkId } : {}
+    ...readiness2.repositoryLink?.repositoryLinkId ? { repositoryLinkId: readiness2.repositoryLink.repositoryLinkId } : {}
   };
 }
 function getSharedRunnerReadiness(repositoryLinks, runnerHeartbeats, nowMs) {
@@ -3145,8 +3219,8 @@ var toolSessionMutationSchema = z3.object({
 });
 function resolveApiUrl(apiUrl, urlPath) {
   const base = apiUrl.endsWith("/") ? apiUrl.slice(0, -1) : apiUrl;
-  const path19 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
-  return new URL(`${base}${path19}`);
+  const path20 = urlPath.startsWith("/") ? urlPath : `/${urlPath}`;
+  return new URL(`${base}${path20}`);
 }
 
 // src/orchestrator.ts
@@ -8729,6 +8803,12 @@ function buildBackgroundRunnerArgs(options) {
   if (options.reasoningEffort) {
     args.push("--reasoning-effort", options.reasoningEffort);
   }
+  if (options.executionProfile) {
+    args.push("--execution-profile", options.executionProfile);
+  }
+  if (options.setupPackageManagerInstall) {
+    args.push("--setup-package-manager-install");
+  }
   if (options.maxIterations !== void 0) {
     args.push("--max-iterations", String(options.maxIterations));
   }
@@ -9826,6 +9906,320 @@ function accountFingerprint(host, login) {
   return `sha256:${createHash8("sha256").update(`${host.toLowerCase()}\0${login.toLowerCase()}`).digest("hex")}`;
 }
 
+// src/runner-environment.ts
+import { constants as constants2 } from "node:fs";
+import { access as access2, readFile as readFile12 } from "node:fs/promises";
+import path18 from "node:path";
+var defaultRunnerExecutionEnvironmentProfile = "hostWorktree";
+var supportedRunnerExecutionEnvironmentProfiles = ["hostWorktree", "hostWorktreeWithSetup", "dockerWorkspace"];
+var commandLookupScript = String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const command = process.argv[1];
+const pathEntries = (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+for (const directory of pathEntries) {
+  for (const extension of extensions) {
+    const candidate = path.join(directory, process.platform === "win32" && !path.extname(command) ? command + extension : command);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      process.exit(0);
+    } catch {}
+  }
+}
+process.exit(1);
+`;
+async function checkRunnerExecutionEnvironment(options) {
+  const profile = options.profile ?? defaultRunnerExecutionEnvironmentProfile;
+  const hostExecution = options.hostExecution ?? await getRuntimeHostExecutionPort();
+  const env = options.env ?? process.env;
+  const checks = [];
+  const blockers = [];
+  const warnings = [];
+  const packageDetection = await detectRepositoryPackageManager(options.executionRoot);
+  const requiredScripts = [.../* @__PURE__ */ new Set([...options.requiredScripts ?? requiredScriptsForWorkKind(options.workKind)])];
+  if (profile === "cloudSandbox") {
+    addBlockedCheck(checks, blockers, "execution-profile", "Execution profile", "unsupportedProfile", "Cloud sandbox execution is reserved and is not supported by this runner.", "Select hostWorktree or dockerWorkspace for local execution.");
+    return readiness(profile, checks, blockers, warnings, options.executionRoot);
+  }
+  await checkExecutable({ checks, blockers, hostExecution, env, executionRoot: options.executionRoot, command: "git", title: "Git", reason: "missingToolchain", remediation: "Install Git and ensure it is available on the runner PATH." });
+  await checkExecutable({ checks, blockers, hostExecution, env, executionRoot: options.executionRoot, command: "node", title: "Node.js", reason: "missingToolchain", remediation: "Install Node.js and ensure it is available on the runner PATH." });
+  if (packageDetection.packageManager) {
+    await checkPackageManager({ checks, blockers, hostExecution, env, executionRoot: options.executionRoot, packageDetection });
+  } else if (packageDetection.lockfiles.length || packageDetection.scripts.length) {
+    addBlockedCheck(checks, blockers, "package-manager", "Package manager", "missingPackageManager", "The repository has package metadata but no supported package manager could be detected.", "Add a packageManager field or a supported lockfile.", ["package.json", ...packageDetection.lockfiles]);
+  } else {
+    checks.push({ checkId: "package-manager", title: "Package manager", status: "skipped", summary: "No package.json or supported lockfile was detected.", safePaths: [] });
+  }
+  for (const scriptName of requiredScripts) {
+    if (!packageDetection.scripts.includes(scriptName)) {
+      addBlockedCheck(checks, blockers, `script-${scriptName}`, `Package script: ${scriptName}`, "missingScript", `Required package script is missing: ${scriptName}.`, `Add a ${scriptName} script or update the runner test profile.`, ["package.json"]);
+    } else {
+      checks.push({ checkId: `script-${scriptName}`, title: `Package script: ${scriptName}`, status: "passed", summary: `Required package script is declared: ${scriptName}.`, safePaths: ["package.json"] });
+    }
+  }
+  if (profile === "hostWorktreeWithSetup") {
+    await runSetupCommands({ checks, blockers, hostExecution, env, executionRoot: options.executionRoot, packageDetection, setupCommands: options.setupCommands ?? [], timeoutMs: options.setupTimeoutMs ?? 12e4 });
+  } else if (options.setupCommands?.length) {
+    addBlockedCheck(checks, blockers, "setup-profile", "Setup profile", "setupCommandNotAllowed", "Setup commands require the hostWorktreeWithSetup execution profile.", "Select hostWorktreeWithSetup or remove setup commands.");
+  }
+  if (packageDetection.packageManager && await fileExists2(path18.join(options.executionRoot, "package.json")) && !await fileExists2(path18.join(options.executionRoot, "node_modules"))) {
+    const dependencySummary = profile === "hostWorktreeWithSetup" ? "Repository dependencies are not ready after setup." : "Repository dependencies are not ready in this worktree.";
+    addBlockedCheck(checks, blockers, "dependencies", "Dependencies", "dependenciesNotReady", dependencySummary, "Run an approved setup profile or install dependencies in the execution worktree.", ["package.json"]);
+  } else if (packageDetection.packageManager) {
+    checks.push({ checkId: "dependencies", title: "Dependencies", status: "passed", summary: "Repository dependencies appear ready for local package scripts.", safePaths: ["package.json"] });
+  }
+  if (profile === "dockerWorkspace") {
+    await checkDockerWorkspace({
+      checks,
+      blockers,
+      hostExecution,
+      env,
+      executionRoot: options.executionRoot,
+      ...options.primaryCheckoutRoot ? { primaryCheckoutRoot: options.primaryCheckoutRoot } : {},
+      ...options.docker ? { docker: options.docker } : {}
+    });
+  }
+  return readiness(profile, checks, blockers, warnings, options.executionRoot);
+}
+function createDockerWorkspaceCommandEnvelope(options) {
+  const executionRoot = path18.resolve(options.executionRoot);
+  const primaryCheckoutRoot = options.primaryCheckoutRoot ? path18.resolve(options.primaryCheckoutRoot) : void 0;
+  const docker = options.docker ?? {};
+  const network = docker.network ?? "none";
+  const image = docker.image ?? "node:20-bookworm";
+  if (primaryCheckoutRoot && executionRoot === primaryCheckoutRoot) {
+    return { ok: false, reason: "dockerProfileInvalid", summary: "Docker workspace mode requires an ADR-scoped worktree, not the primary checkout." };
+  }
+  if (docker.privileged) {
+    return { ok: false, reason: "dockerProfileInvalid", summary: "Docker workspace mode does not allow privileged containers." };
+  }
+  if (network === "host") {
+    return { ok: false, reason: "dockerProfileInvalid", summary: "Docker workspace mode does not allow host networking." };
+  }
+  if (docker.mounts?.length) {
+    return { ok: false, reason: "dockerProfileInvalid", summary: "Docker workspace mode only mounts the prepared execution worktree." };
+  }
+  if (docker.env && Object.keys(docker.env).length > 0) {
+    return { ok: false, reason: "dockerProfileInvalid", summary: "Docker workspace mode does not accept unbounded environment injection." };
+  }
+  return {
+    ok: true,
+    envelope: {
+      command: "docker",
+      cwd: executionRoot,
+      env: dockerSafeEnvironment(options.env ?? process.env),
+      args: [
+        "run",
+        "--rm",
+        "--network",
+        network,
+        "--workdir",
+        "/workspace",
+        "--mount",
+        `type=bind,source=${executionRoot},target=/workspace`,
+        image,
+        "node",
+        "--version"
+      ]
+    }
+  };
+}
+function requiredScriptsForWorkKind(workKind) {
+  if (workKind === "implementationTestGate" || workKind === "testQualityScan") {
+    return ["test"];
+  }
+  if (workKind === "implementationVerification") {
+    return ["typecheck"];
+  }
+  return [];
+}
+async function detectRepositoryPackageManager(executionRoot) {
+  const policy = createBoundedToolAdapterPolicy({ executionRoot, mutationPolicy: "readOnly" });
+  const result = await runPackageManagerDetectTool({ policy });
+  if (result.status !== "completed") {
+    return { lockfiles: [], scripts: [], profiles: [] };
+  }
+  const parsed = JSON.parse(result.stdout);
+  if (!isPackageManagerDetection(parsed)) {
+    return { lockfiles: [], scripts: [], profiles: [] };
+  }
+  return parsed;
+}
+async function checkPackageManager(options) {
+  const packageManager = options.packageDetection.packageManager;
+  if (!packageManager) return;
+  if (packageManager === "pnpm" || packageManager === "yarn") {
+    const corepackAvailable = await isCommandAvailable(options.hostExecution, "corepack", options.executionRoot, options.env);
+    if (!corepackAvailable) {
+      addBlockedCheck(options.checks, options.blockers, "corepack", "Corepack", "missingCorepack", `${packageManager} repositories require Corepack or an installed package-manager command.`, "Enable Corepack or install the package manager before rerunning work.", ["package.json", ...options.packageDetection.lockfiles]);
+    } else {
+      options.checks.push({ checkId: "corepack", title: "Corepack", status: "passed", summary: "Corepack is available to the runner PATH.", safePaths: [] });
+    }
+  }
+  const directPackageManagerAvailable = await isCommandAvailable(options.hostExecution, packageManager, options.executionRoot, options.env);
+  const corepackPackageManagerAvailable = packageManager === "pnpm" || packageManager === "yarn" ? await canRunCorepackPackageManager(options.hostExecution, packageManager, options.executionRoot, options.env) : false;
+  if (!directPackageManagerAvailable && !corepackPackageManagerAvailable) {
+    addBlockedCheck(options.checks, options.blockers, "package-manager", "Package manager", "missingPackageManager", `${packageManager} is required by repository package metadata but is not runnable in the runner environment.`, "Install the package manager or enable Corepack for this runner.", ["package.json", ...options.packageDetection.lockfiles]);
+    return;
+  }
+  options.checks.push({ checkId: "package-manager", title: "Package manager", status: "passed", summary: `${packageManager} is runnable in the runner environment.`, safePaths: ["package.json", ...options.packageDetection.lockfiles] });
+}
+async function checkExecutable(options) {
+  const available = await isCommandAvailable(options.hostExecution, options.command, options.executionRoot, options.env);
+  if (!available) {
+    addBlockedCheck(options.checks, options.blockers, `toolchain-${options.command}`, options.title, options.reason, `${options.title} is not available to the runner PATH.`, options.remediation);
+    return;
+  }
+  options.checks.push({ checkId: `toolchain-${options.command}`, title: options.title, status: "passed", summary: `${options.title} is available to the runner PATH.`, safePaths: [] });
+}
+async function runSetupCommands(options) {
+  if (!options.setupCommands.length) {
+    options.checks.push({ checkId: "setup-profile", title: "Setup profile", status: "skipped", summary: "No approved setup commands were requested.", safePaths: [] });
+    return;
+  }
+  for (const setupCommand of options.setupCommands) {
+    const command = setupCommandForPackageManager(setupCommand.id, options.packageDetection.packageManager, options.packageDetection.lockfiles);
+    if (!command) {
+      addBlockedCheck(options.checks, options.blockers, `setup-${setupCommand.id}`, "Setup profile", "setupCommandNotAllowed", "Requested setup command is not allowed for the detected repository package manager.", "Use an approved package-manager setup command derived from repository metadata.", ["package.json", ...options.packageDetection.lockfiles]);
+      continue;
+    }
+    const result = await options.hostExecution.executeCommand({
+      command: command.command,
+      args: command.args,
+      cwd: options.executionRoot,
+      env: options.env,
+      shell: false,
+      timeoutMs: options.timeoutMs,
+      timeoutMessage: "Approved runner setup command timed out."
+    });
+    if (result.exitCode !== 0) {
+      addBlockedCheck(options.checks, options.blockers, `setup-${setupCommand.id}`, "Setup profile", "setupFailed", "Approved runner setup command failed.", "Review setup output locally and rerun when dependencies are ready.", ["package.json", ...options.packageDetection.lockfiles]);
+      continue;
+    }
+    options.checks.push({ checkId: `setup-${setupCommand.id}`, title: "Setup profile", status: "passed", summary: "Approved runner setup command completed.", safePaths: ["package.json", ...options.packageDetection.lockfiles] });
+  }
+}
+async function checkDockerWorkspace(options) {
+  const dockerAvailable = await isCommandAvailable(options.hostExecution, "docker", options.executionRoot, options.env);
+  if (!dockerAvailable) {
+    addBlockedCheck(options.checks, options.blockers, "docker", "Docker", "dockerUnavailable", "Docker is not available to the runner PATH.", "Install Docker Desktop or select hostWorktree execution.");
+    return;
+  }
+  const envelope = createDockerWorkspaceCommandEnvelope(options);
+  if (!envelope.ok) {
+    addBlockedCheck(options.checks, options.blockers, "docker-profile", "Docker profile", envelope.reason, envelope.summary, "Use the default Docker workspace envelope mounted to the prepared worktree only.");
+    return;
+  }
+  options.checks.push({ checkId: "docker", title: "Docker", status: "passed", summary: "Docker is available and the workspace envelope is valid.", safePaths: [] });
+}
+function setupCommandForPackageManager(commandId, packageManager, lockfiles) {
+  if (commandId !== "packageManager.install" || !packageManager) {
+    return void 0;
+  }
+  if (packageManager === "pnpm") {
+    return { command: "corepack", args: ["pnpm", "--config.verify-deps-before-run=false", "install", "--frozen-lockfile"], displayName: "pnpm install", mutationPolicy: "mutating" };
+  }
+  if (packageManager === "yarn") {
+    return { command: "corepack", args: ["yarn", "install", "--immutable"], displayName: "yarn install", mutationPolicy: "mutating" };
+  }
+  if (packageManager === "bun") {
+    return { command: "bun", args: ["install", "--frozen-lockfile"], displayName: "bun install", mutationPolicy: "mutating" };
+  }
+  return lockfiles.includes("package-lock.json") ? { command: "npm", args: ["ci"], displayName: "npm ci", mutationPolicy: "mutating" } : { command: "npm", args: ["install"], displayName: "npm install", mutationPolicy: "mutating" };
+}
+async function isCommandAvailable(hostExecution, command, executionRoot, env) {
+  if (env === process.env) {
+    return hostExecution.commandExists(command);
+  }
+  const result = await hostExecution.executeCommand({
+    command: process.execPath,
+    args: ["-e", commandLookupScript, command],
+    cwd: executionRoot,
+    env,
+    shell: false,
+    timeoutMs: 5e3,
+    timeoutMessage: "Command lookup timed out."
+  });
+  return result.exitCode === 0;
+}
+async function canRunCorepackPackageManager(hostExecution, packageManager, executionRoot, env) {
+  if (packageManager !== "pnpm" && packageManager !== "yarn") {
+    return false;
+  }
+  const corepackAvailable = await isCommandAvailable(hostExecution, "corepack", executionRoot, env);
+  if (!corepackAvailable) {
+    return false;
+  }
+  const result = await hostExecution.executeCommand({
+    command: "corepack",
+    args: [packageManager, "--version"],
+    cwd: executionRoot,
+    env,
+    shell: false,
+    timeoutMs: 1e4,
+    timeoutMessage: "Package manager lookup through Corepack timed out."
+  });
+  return result.exitCode === 0;
+}
+function addBlockedCheck(checks, blockers, checkId, title, reason, summary, remediation, safePaths = []) {
+  checks.push({ checkId, title, status: "blocked", reason, summary, safePaths: [...safePaths] });
+  blockers.push({ reason, summary, remediation, safePaths: [...safePaths] });
+}
+function readiness(profile, checks, blockers, warnings, executionRoot) {
+  const status = blockers.length ? "blocked" : "ready";
+  const summary = status === "ready" ? `Runner execution environment ${profile} is ready.` : `Runner execution environment ${profile} is blocked: ${blockers.map((blocker) => blocker.reason).join(", ")}.`;
+  return runnerEnvironmentReadinessSchema.parse({
+    profile,
+    status,
+    summary: redactLocalPath(summary, executionRoot),
+    checks: checks.map((check) => redactCheck(check, executionRoot)),
+    blockers: blockers.map((blocker) => redactBlocker(blocker, executionRoot)),
+    warnings: warnings.map((warning) => redactLocalPath(warning, executionRoot)),
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function redactCheck(check, executionRoot) {
+  return {
+    ...check,
+    ...check.summary ? { summary: redactLocalPath(check.summary, executionRoot) } : {},
+    safePaths: check.safePaths ?? []
+  };
+}
+function redactBlocker(blocker, executionRoot) {
+  return {
+    ...blocker,
+    summary: redactLocalPath(blocker.summary, executionRoot),
+    ...blocker.remediation ? { remediation: redactLocalPath(blocker.remediation, executionRoot) } : {},
+    safePaths: blocker.safePaths ?? []
+  };
+}
+function redactLocalPath(value, executionRoot) {
+  return value.split(executionRoot).join("<execution-root>");
+}
+function dockerSafeEnvironment(env) {
+  return Object.fromEntries(["HOME", "PATH", "TMPDIR", "TEMP", "TMP"].flatMap((envName) => {
+    const value = env[envName];
+    return value ? [[envName, value]] : [];
+  }));
+}
+async function fileExists2(filePath) {
+  try {
+    await access2(filePath, constants2.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPackageManagerDetection(value) {
+  if (!isRecord4(value)) return false;
+  if (value.packageManager !== void 0 && !["pnpm", "npm", "yarn", "bun"].includes(String(value.packageManager))) return false;
+  return Array.isArray(value.lockfiles) && Array.isArray(value.scripts) && Array.isArray(value.profiles);
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/version.ts
 import { readFileSync } from "node:fs";
 function readCliPackageVersion() {
@@ -10233,7 +10627,7 @@ hostHelper.command("conformance").description("Run local compatibility checks ag
     process.exitCode = 1;
   }
 });
-program.command("orchestrate").description("Update the Amistio control plane through a user-installed local AI tool").argument("[goal...]", "Goal or next-step instruction for the orchestration pass").option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent", "auto").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel, "auto").option("--model <model>", "Model to request when the selected local tool supports model selection").option("--provider <providerId>", "Provider id for provider-backed model configuration").option("--model-id <modelId>", "Provider catalog model id to request").option("--model-variant <variant>", "Provider catalog model variant to request").option("--reasoning-effort <effort>", "Reasoning effort: auto, low, medium, high, or xhigh", parseReasoningEffort).option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--prompt-out <path>", "Write the generated orchestration prompt to a file before running").option("--dry-run", "Print the generated orchestration prompt without running a tool").option("--no-stream", "Capture local tool output instead of streaming it").action(async (goalParts, options) => {
+program.command("orchestrate").description("Update the Amistio control plane through a user-installed local AI tool").argument("[goal...]", "Goal or next-step instruction for the orchestration pass").option("--root <path>", "Repository root", defaultRoot).option("--tool <name>", "Local tool to use: auto, none, opencode, claude, codex, copilot, gemini, aider, cursor-agent", "auto").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel, "auto").option("--model <model>", "Model to request when the selected local tool supports model selection").option("--provider <providerId>", "Provider id for provider-backed model configuration").option("--model-id <modelId>", "Provider catalog model id to request").option("--model-variant <variant>", "Provider catalog model variant to request").option("--reasoning-effort <effort>", "Reasoning effort: auto, low, medium, high, or xhigh", parseReasoningEffort).option("--execution-profile <profile>", "Runner execution environment profile: hostWorktree, hostWorktreeWithSetup, or dockerWorkspace", parseRunnerExecutionEnvironmentProfile, defaultRunnerExecutionEnvironmentProfile).option("--setup-package-manager-install", "Allow hostWorktreeWithSetup to run the approved package-manager install command").option("--tool-command <command>", "Custom local command. Use {promptFile} and {root} placeholders when supported").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--prompt-out <path>", "Write the generated orchestration prompt to a file before running").option("--dry-run", "Print the generated orchestration prompt without running a tool").option("--no-stream", "Capture local tool output instead of streaming it").action(async (goalParts, options) => {
   const goal = goalParts?.join(" ").trim() || "Review the current repository state and update the Amistio control plane with the next useful orchestration steps.";
   const prompt = await createOrchestrationPrompt({ rootDir: options.root, goal });
   if (options.promptOut) {
@@ -10297,7 +10691,7 @@ program.command("run").description("Claim and run approved Amistio work locally"
       projectId: context.metadata.amistioProjectId,
       repositoryLinkId: context.metadata.repositoryLinkId,
       runnerId,
-      rootDir: path18.resolve(options.root),
+      rootDir: path19.resolve(options.root),
       apiUrl: options.apiUrl,
       args: buildBackgroundRunnerArgs(resolvedOptions)
     });
@@ -10489,7 +10883,7 @@ runner.command("stop").description("Stop a background runner for the paired repo
   console.log(stopResult === "stopped" ? `Stopped background runner ${record.runnerId}.` : `Marked background runner ${record.runnerId} stopped; process was not running.`);
 });
 var runnerService = runner.command("service").description("Manage a user-level startup service for the paired runner");
-runnerService.command("install").description("Install a user-level startup service for this paired repository runner").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--root <path>", "Repository root", defaultRoot).option("--runner-id <runnerId>", "Stable runner ID").option("--tool <name>", "Local tool to use: auto, opencode, claude, codex, copilot, gemini, aider, cursor-agent").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel).option("--model <model>", "Model to request when the selected local tool supports model selection").option("--provider <providerId>", "Provider id for provider-backed model configuration").option("--model-id <modelId>", "Provider catalog model id to request").option("--model-variant <variant>", "Provider catalog model variant to request").option("--reasoning-effort <effort>", "Reasoning effort: auto, low, medium, high, or xhigh", parseReasoningEffort).option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--interval-seconds <seconds>", "Polling interval for the service runner", parsePositiveInteger, 10).option("--max-concurrent-work <count>", "Maximum approved work items to run in parallel in --watch mode", parsePositiveInteger, 1).option("--max-preflight-attempts <count>", "Fail setup/preflight failures after this many claimed attempts", parsePositiveInteger, DEFAULT_MAX_PREFLIGHT_ATTEMPTS).option("--tool-timeout-seconds <seconds>", "Fail local tool execution after this many seconds", parsePositiveInteger, DEFAULT_TOOL_TIMEOUT_SECONDS).option("--no-stream", "Capture local tool output instead of streaming it").option("--verbose", "Print detailed runner errors").option("--dry-run", "Print the startup service descriptor without installing it").action(async (options) => {
+runnerService.command("install").description("Install a user-level startup service for this paired repository runner").option("--api-url <url>", apiUrlOptionDescription, defaultApiUrl()).option("--root <path>", "Repository root", defaultRoot).option("--runner-id <runnerId>", "Stable runner ID").option("--tool <name>", "Local tool to use: auto, opencode, claude, codex, copilot, gemini, aider, cursor-agent").option("--invocation-channel <channel>", "Local invocation channel: auto, sdk, or command", parseInvocationChannel).option("--model <model>", "Model to request when the selected local tool supports model selection").option("--provider <providerId>", "Provider id for provider-backed model configuration").option("--model-id <modelId>", "Provider catalog model id to request").option("--model-variant <variant>", "Provider catalog model variant to request").option("--reasoning-effort <effort>", "Reasoning effort: auto, low, medium, high, or xhigh", parseReasoningEffort).option("--execution-profile <profile>", "Runner execution environment profile for the service runner", parseRunnerExecutionEnvironmentProfile, defaultRunnerExecutionEnvironmentProfile).option("--setup-package-manager-install", "Allow hostWorktreeWithSetup to run the approved package-manager install command").option("--session <policy>", "Tool session policy: auto, new, continue:<toolSessionId>, or none", "auto").option("--interval-seconds <seconds>", "Polling interval for the service runner", parsePositiveInteger, 10).option("--max-concurrent-work <count>", "Maximum approved work items to run in parallel in --watch mode", parsePositiveInteger, 1).option("--max-preflight-attempts <count>", "Fail setup/preflight failures after this many claimed attempts", parsePositiveInteger, DEFAULT_MAX_PREFLIGHT_ATTEMPTS).option("--tool-timeout-seconds <seconds>", "Fail local tool execution after this many seconds", parsePositiveInteger, DEFAULT_TOOL_TIMEOUT_SECONDS).option("--no-stream", "Capture local tool output instead of streaming it").option("--verbose", "Print detailed runner errors").option("--dry-run", "Print the startup service descriptor without installing it").action(async (options) => {
   const context = await loadPairedApiContext(options.root, options.apiUrl);
   if (!context) {
     console.log("Repository is not paired. Run `amistio pair` first.");
@@ -10518,7 +10912,7 @@ runnerService.command("install").description("Install a user-level startup servi
     projectId: context.metadata.amistioProjectId,
     repositoryLinkId: context.metadata.repositoryLinkId,
     runnerId,
-    rootDir: path18.resolve(options.root),
+    rootDir: path19.resolve(options.root),
     apiUrl: options.apiUrl,
     args,
     platform
@@ -10607,6 +11001,8 @@ async function runWatchIteration({ command, context, options, runnerId }) {
       ...command.getOptionValueSource("modelVariant") === "cli" && options.modelVariant ? { explicitModelVariant: options.modelVariant } : {},
       ...command.getOptionValueSource("reasoningEffort") === "cli" && options.reasoningEffort ? { explicitReasoningEffort: options.reasoningEffort } : {},
       ...options.toolCommand ? { toolCommand: options.toolCommand } : {},
+      executionProfile: options.executionProfile,
+      ...options.setupPackageManagerInstall ? { setupPackageManagerInstall: options.setupPackageManagerInstall } : {},
       dryRun: Boolean(options.dryRun),
       stream: options.stream,
       commandContext: {
@@ -10739,6 +11135,8 @@ async function runNextWorkItem({
   explicitModelVariant,
   explicitProviderId,
   explicitReasoningEffort,
+  executionProfile,
+  setupPackageManagerInstall,
   explicitInvocationChannel,
   explicitTool,
   maxPreflightAttempts,
@@ -10811,9 +11209,52 @@ async function runNextWorkItem({
   }
   const executionRoot = worktreeIsolation.isolation?.worktreePath ?? root;
   const isolationTelemetry = workItemIsolationTelemetry(result.workItem, worktreeIsolation.isolation);
+  const environmentReadiness = await checkRunnerExecutionEnvironment({
+    executionRoot,
+    primaryCheckoutRoot: root,
+    profile: executionProfile,
+    setupCommands: runnerEnvironmentSetupCommands(setupPackageManagerInstall),
+    ...result.workItem.workKind ? { workKind: result.workItem.workKind } : {},
+    env: process.env
+  });
+  if (environmentReadiness.profile === "dockerWorkspace" && environmentReadiness.status === "ready") {
+    environmentReadiness.status = "blocked";
+    environmentReadiness.summary = "Runner execution environment dockerWorkspace is blocked: containerized harness execution is not enabled in this runner build.";
+    environmentReadiness.blockers.push({ reason: "unsupportedProfile", summary: "Containerized harness execution is not enabled in this runner build.", remediation: "Select hostWorktree or hostWorktreeWithSetup until Docker workspace execution is enabled.", safePaths: [] });
+    environmentReadiness.checks.push({ checkId: "docker-harness", title: "Docker harness", status: "blocked", reason: "unsupportedProfile", summary: "Docker workspace envelope is valid, but this runner cannot execute the harness inside the container yet.", safePaths: [] });
+  }
+  if (environmentReadiness.status === "blocked") {
+    const statusResult2 = await apiClient.updateWorkStatus(projectId, result.workItem.workItemId, "blocked", `environment_blocked_${result.workItem.workItemId}_${result.workItem.attempt}_${randomUUID3()}`, runnerId, {
+      ...isolationTelemetry,
+      executionEnvironmentProfile: environmentReadiness.profile,
+      executionEnvironmentReadiness: environmentReadiness,
+      blockerReason: environmentReadiness.summary,
+      message: environmentReadiness.summary
+    });
+    await recordRunnerMilestone(apiClient, projectId, statusResult2.workItem, runnerId, repositoryLinkId, {
+      status: "warning",
+      summary: environmentReadiness.summary,
+      idempotencyKey: `runner_milestone_environment_blocked_${result.workItem.workItemId}_${statusResult2.workItem.idempotencyKey}`,
+      metadata: { executionEnvironmentProfile: environmentReadiness.profile, blockerReasons: environmentReadiness.blockers.map((blocker) => blocker.reason) }
+    });
+    await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "blocked", {
+      ...runnerHeartbeatMetadata(toolConfig, currentRunnerMode(), heartbeatConcurrency),
+      currentWorkItemId: result.workItem.workItemId,
+      currentExecutionEnvironmentProfile: environmentReadiness.profile,
+      environmentReadiness,
+      preferenceMessage: environmentReadiness.summary,
+      ...isolationTelemetry.implementationScopeId ? { currentImplementationScopeId: isolationTelemetry.implementationScopeId } : {},
+      ...isolationTelemetry.executionWorktreeKey ? { currentWorktreeKey: isolationTelemetry.executionWorktreeKey } : {},
+      ...isolationTelemetry.executionBranch ? { currentBranch: isolationTelemetry.executionBranch } : {}
+    });
+    console.error(environmentReadiness.summary);
+    return { status: "blocked", exitCode: 1, message: environmentReadiness.summary };
+  }
   await apiClient.sendRunnerHeartbeat(projectId, runnerId, repositoryLinkId, "running", {
     ...runnerHeartbeatMetadata(toolConfig, currentRunnerMode(), heartbeatConcurrency),
     currentWorkItemId: result.workItem.workItemId,
+    currentExecutionEnvironmentProfile: environmentReadiness.profile,
+    environmentReadiness,
     ...isolationTelemetry.implementationScopeId ? { currentImplementationScopeId: isolationTelemetry.implementationScopeId } : {},
     ...isolationTelemetry.executionWorktreeKey ? { currentWorktreeKey: isolationTelemetry.executionWorktreeKey } : {},
     ...isolationTelemetry.executionBranch ? { currentBranch: isolationTelemetry.executionBranch } : {}
@@ -11549,6 +11990,9 @@ async function executeImplementationHandoffRecoveryCommand(apiClient, command, c
   if (workItem.repositoryLinkId && workItem.repositoryLinkId !== context.repositoryLinkId) {
     return { succeeded: false, message: "Handoff recovery command is not scoped to this repository link." };
   }
+  if (workItem.claimedByRunnerId && workItem.claimedByRunnerId !== context.runnerId) {
+    return { succeeded: false, message: `Handoff recovery command belongs to runner ${workItem.claimedByRunnerId}. Restart that runner or use Requeue fresh attempt.` };
+  }
   if (!workItem.implementationHandoff?.recovery?.availableActions.includes(command.handoffRecoveryAction)) {
     return { succeeded: false, message: "Handoff recovery action is no longer available for this work item." };
   }
@@ -13299,8 +13743,17 @@ function parseReasoningEffort(value) {
   }
   throw new Error(`Expected reasoning effort auto, low, medium, high, or xhigh; received ${value}.`);
 }
+function parseRunnerExecutionEnvironmentProfile(value) {
+  if (value === "hostWorktree" || value === "hostWorktreeWithSetup" || value === "dockerWorkspace") {
+    return value;
+  }
+  throw new Error(`Expected execution profile hostWorktree, hostWorktreeWithSetup, or dockerWorkspace; received ${value}.`);
+}
+function runnerEnvironmentSetupCommands(setupPackageManagerInstall) {
+  return setupPackageManagerInstall ? [{ id: "packageManager.install" }] : [];
+}
 function inferRepoName(root) {
-  return path18.basename(path18.resolve(root)) || "repository";
+  return path19.basename(path19.resolve(root)) || "repository";
 }
 function createRepoFingerprint(accountId, projectId, repositoryLinkId) {
   return createHash9("sha256").update(`${accountId}:${projectId}:${repositoryLinkId}`).digest("hex");
@@ -13567,6 +14020,7 @@ function runnerIsolationCapabilityMetadata(laneMetadata = {}) {
     supportedWorkKinds: runnerSupportedWorkKinds,
     supportsBranchIsolation: true,
     supportsGitWorktreeIsolation: true,
+    supportedExecutionEnvironmentProfiles: [...supportedRunnerExecutionEnvironmentProfiles],
     ...laneMetadata.claimLaneId ? { claimLaneId: laneMetadata.claimLaneId } : {},
     ...laneMetadata.maxConcurrentWork !== void 0 ? { maxConcurrentWork: laneMetadata.maxConcurrentWork } : {}
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amistio/cli",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "type": "module",
   "repository": {
     "type": "git",