@snappedly-tools/shipyard 0.4.4 → 0.5.0

package/dist/main.js

@@ -1,20 +1,22 @@
 #!/usr/bin/env node
-import { CODEX_MODELS, withFriendlyErrors } from './chunk-VDHZO5PP.js';
-import { buildImage, removeImage } from './chunk-OCJKONZ7.js';
-import { SANDBOX_REPO_DIR, Display, InitError, PRODUCT_NAME, CONFIG_DIR, CLI_NAME, ClackDisplay, defaultImageName, ExecHostError, LOCKS_DIR, ConfigDirError } from './chunk-2GT3OPO5.js';
+import { CODEX_MODELS, purgeRunLogs, withFriendlyErrors, DEFAULT_LOG_RETENTION_DAYS, resolveEnv } from './chunk-56TDSWFU.js';
+import { buildImage, removeImage, validateExistingRepositoryRunner, RunnerLifecycleError, RUNNER_INSTALL_METADATA, removeRepositoryRunner, RUNNER_CONTROLLER_LOCK, recoverRepositoryRunner, REPOSITORY_RUNNER_OWNER_ENV, removeOwnedRepositoryRunnerContainers, RUNNER_WORK_DIR } from './chunk-WAXEMZUV.js';
+import { SANDBOX_REPO_DIR, Display, InitError, ACTIVATION_LABEL, PRODUCT_NAME, CONFIG_DIR, CLI_NAME, ClackDisplay, RUNNER_DIR, RUNNER_SANDBOX_MASK_DIR, assertProtectedDirectoryIdentities, repositoryRunnerEnvironment, ConfigDirError, defaultImageName, ExecHostError, LOCKS_DIR } from './chunk-FDYOTN55.js';
 import './chunk-KMGNFXKN.js';
-import './chunk-WA7QPAXO.js';
-import { NodeContext, NodeRuntime } from '@effect/platform-node';
+import './chunk-ACD46ZM4.js';
+import { NodeContext, NodeRuntime, NodeFileSystem } from '@effect/platform-node';
 import { Effect, Layer, Option } from 'effect';
 import { Options, Command } from '@effect/cli';
 import * as clack from '@clack/prompts';
-import { execSync, spawn, execFileSync } from 'child_process';
-import { existsSync, statSync } from 'fs';
+import { execFile, execSync, spawn, execFileSync } from 'child_process';
+import { existsSync, constants, statSync } from 'fs';
 import { join, resolve, dirname } from 'path';
-import { styleText } from 'util';
+import { promisify, styleText } from 'util';
 import { FileSystem } from '@effect/platform';
 import { fileURLToPath } from 'url';
-import { homedir } from 'os';
+import { hostname, homedir } from 'os';
+import { createHash } from 'crypto';
+import { chmod, lstat, realpath, rm, mkdir, writeFile, readFile, access } from 'fs/promises';
 import 'module';
 
 var pathExists = (path) => Effect.gen(function* () {
@@ -262,16 +264,19 @@ var ISSUE_TRACKER_REGISTRY = [
     name: "github-issues",
     label: "GitHub Issues",
     templateArgs: {
-      LIST_TASKS_COMMAND: `gh issue list --state open --label ${PRODUCT_NAME} --limit 100 --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`,
+      LIST_TASKS_COMMAND: `gh issue list --state open --label ${ACTIVATION_LABEL} --limit 100 --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`,
       VIEW_TASK_COMMAND: "gh issue view <ID>",
       CLOSE_TASK_COMMAND: `gh issue close <ID> --comment "Completed by ${PRODUCT_NAME}"`,
       ISSUE_TRACKER_TOOLS: GITHUB_CLI_TOOLS
     },
     envExample: `# GitHub personal access token \u2014 the agent uses it to read and manage GitHub Issues
+# Runner installation/start uses the host \`gh\` login for repository administration.
 # Create a fine-grained token: https://github.com/settings/personal-access-tokens/new
 # Required repository permissions: Issues (Read and write) and Metadata (Read)
 # Or leave blank and run: GH_TOKEN="$(gh auth token)" npx shipyard run
-GH_TOKEN=`
+GH_TOKEN=
+# GitHub repository (owner/repository)
+GH_REPO=`
   }
 ];
 var listIssueTrackers = () => ISSUE_TRACKER_REGISTRY;
@@ -287,69 +292,15 @@ var SANDBOX_PROVIDER_REGISTRY = [
 ];
 var listSandboxProviders = () => SANDBOX_PROVIDER_REGISTRY;
 var getSandboxProvider = (name) => SANDBOX_PROVIDER_REGISTRY.find((p) => p.name === name);
-function getNextStepsLines(template, mainFilename, agent, packageManager, codexAuth = "api-key") {
-  const getAuthLines = (step) => {
-    if (agent.name === "codex") {
-      if (codexAuth === "chatgpt") {
-        return [
-          `${step}. Use your ChatGPT subscription with Codex: run \`codex login\` on the host and make sure \`~/.codex/auth.json\` exists`,
-          '   If it does not exist, set `cli_auth_credentials_store = "file"` in `~/.codex/config.toml`, then run the login again',
-          "   Shipyard mounts this credential read-only; use this mode only with trusted repositories.",
-          `   If subscription auth does not work, rerun init with \`--codex-auth api-key\` and set \`OPENAI_API_KEY\` in ${CONFIG_DIR}/.env instead.`,
-          `   Also set any issue-tracker variables shown in ${CONFIG_DIR}/.env.example.`
-        ];
-      }
-      return [
-        `${step}. Use your ChatGPT subscription with Codex (recommended): run \`codex login\` on the host, then initialize with \`--codex-auth chatgpt\` so Shipyard can mount \`~/.codex/auth.json\` read-only`,
-        `   If subscription auth does not work, use API-key billing instead by setting \`OPENAI_API_KEY\` in ${CONFIG_DIR}/.env (see ${CONFIG_DIR}/.env.example).`,
-        `   Also set any issue-tracker variables shown in ${CONFIG_DIR}/.env.example.`
-      ];
-    }
-    if (agent.name === "claude-code") {
-      return [
-        `${step}. Use your Claude subscription (recommended): run \`claude setup-token\` on the host and paste the result into \`CLAUDE_CODE_OAUTH_TOKEN\` in ${CONFIG_DIR}/.env`,
-        `   If subscription auth does not work, use API-key billing instead by uncommenting \`ANTHROPIC_API_KEY\` in ${CONFIG_DIR}/.env and setting it to your key.`,
-        `   Also set any issue-tracker variables shown in ${CONFIG_DIR}/.env.example.`
-      ];
-    }
-    return [
-      `${step}. Set the required env vars in ${CONFIG_DIR}/.env (see ${CONFIG_DIR}/.env.example)`
-    ];
-  };
-  if (template === "blank") {
-    const lines = ["Next steps:", ...getAuthLines(1)];
-    lines.push(
-      `2. Read and customize ${CONFIG_DIR}/prompt.md to describe what you want the agent to do`,
-      `3. Customize ${CONFIG_DIR}/${mainFilename} \u2014 it uses the JS API (\`run()\`) to control how the agent runs`,
-      `4. Run \`npx ${CLI_NAME} run\` to build the sandbox image and start the agent`
-    );
-    return lines;
-  } else {
-    const hasReviewer = template.includes("review");
-    const usesPlanSchema = getTemplateDependencies(template).includes("zod");
-    let step = 1;
-    const lines = ["Next steps:", ...getAuthLines(step++)];
-    lines.push(
-      `${step++}. Templates use \`copyToWorktree: ["node_modules"]\` to copy your host node_modules into the sandbox for fast startup \u2014 the \`npm install\` in the onSandboxReady hook is a safety net for platform-specific binaries. Adjust both if you use a different package manager`
-    );
-    if (usesPlanSchema) {
-      lines.push(
-        `${step++}. Install a schema validator for the planner's \`<plan>\` output \u2014 the template uses Zod (\`${addDependencyCommand(packageManager, "zod")}\`), but Valibot, ArkType, or any Standard Schema library works (https://standardschema.dev)`
-      );
-    }
-    lines.push(
-      `${step++}. Read and customize the prompt files in ${CONFIG_DIR}/ \u2014 they shape what the agent does`
-    );
-    if (hasReviewer) {
-      lines.push(
-        `${step++}. Customize ${CONFIG_DIR}/CODING_STANDARDS.md with your project's standards \u2014 the reviewer agent loads it during review`
-      );
-    }
-    lines.push(
-      `${step++}. Run \`npx ${CLI_NAME} run\` to build the sandbox image and start the workflow`
-    );
-    return lines;
-  }
+function getNextStepsLines() {
+  return [
+    "Next steps:",
+    `1. Fill in the values you need in \`${CONFIG_DIR}/.env\`.`,
+    "2. If using a model subscription, sign in. For Codex:",
+    `   codex --config 'cli_auth_credentials_store="file"' login`,
+    "   test -f ~/.codex/auth.json",
+    `3. Start with \`npx ${CLI_NAME} runner start\` (if installed) or \`npx ${CLI_NAME} run\``
+  ];
 }
 function getTemplatesDir() {
   const thisFile = fileURLToPath(import.meta.url);
@@ -426,27 +377,6 @@ var rewriteMainTs = (configDir, agent, model, sandboxProvider, mainFilename, cod
   content = content.replace(/\bdocker\b/g, sandboxProvider.name);
   yield* fs.writeFileString(mainTsPath, content).pipe(Effect.mapError((e) => new Error(e.message)));
 });
-var rewritePromptFiles = (configDir) => Effect.gen(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const files = yield* fs.readDirectory(configDir).pipe(Effect.mapError((e) => new Error(e.message)));
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  yield* Effect.all(
-    mdFiles.map(
-      (f) => Effect.gen(function* () {
-        const filePath = join(configDir, f);
-        const content = yield* fs.readFileString(filePath).pipe(Effect.mapError((e) => new Error(e.message)));
-        const updated = content.replace(
-          new RegExp(` --label ${PRODUCT_NAME}`, "g"),
-          ""
-        );
-        if (updated !== content) {
-          yield* fs.writeFileString(filePath, updated).pipe(Effect.mapError((e) => new Error(e.message)));
-        }
-      })
-    ),
-    { concurrency: "unbounded" }
-  );
-});
 var TEXT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".md",
   ".txt",
@@ -505,7 +435,6 @@ var scaffold = (repoDir, options) => Effect.gen(function* () {
     agent,
     model,
     templateName = "blank",
-    createLabel = true,
     issueTracker = ISSUE_TRACKER_REGISTRY[0],
     // default: github-issues
     sandboxProvider = SANDBOX_PROVIDER_REGISTRY[0],
@@ -532,6 +461,7 @@ var scaffold = (repoDir, options) => Effect.gen(function* () {
     envExampleParts.push(issueTracker.envExample);
   }
   const envExampleContent = envExampleParts.join("\n") + "\n";
+  const envExamplePath = join(configDir, ".env.example");
   yield* Effect.all(
     [
       fs.writeFileString(
@@ -539,7 +469,8 @@ var scaffold = (repoDir, options) => Effect.gen(function* () {
         agent.dockerfileTemplate
       ).pipe(Effect.mapError((e) => new Error(e.message))),
       fs.writeFileString(join(configDir, ".gitignore"), GITIGNORE).pipe(Effect.mapError((e) => new Error(e.message))),
-      fs.writeFileString(join(configDir, ".env.example"), envExampleContent).pipe(Effect.mapError((e) => new Error(e.message))),
+      fs.writeFileString(envExamplePath, envExampleContent).pipe(Effect.mapError((e) => new Error(e.message))),
+      fs.writeFileString(join(configDir, ".env"), envExampleContent).pipe(Effect.mapError((e) => new Error(e.message))),
       copyTemplateFiles(templateDir, configDir, mainFilename)
     ],
     { concurrency: "unbounded" }
@@ -553,9 +484,6 @@ var scaffold = (repoDir, options) => Effect.gen(function* () {
     codexAuth
   );
   yield* substituteTemplateArgs(configDir, issueTracker);
-  if (!createLabel) {
-    yield* rewritePromptFiles(configDir);
-  }
   return { mainFilename };
 });
 var resolveCodexAuthMode = async (options) => {
@@ -634,7 +562,1704 @@ var ensureCodexChatGptAuth = (options) => {
     });
   }
 };
-var VERSION = "0.4.4" ;
+var REPOSITORY_RUNNER_WORKFLOW_PATH = ".github/workflows/shipyard-wake.yml";
+var REPOSITORY_RUNNER_WAKE_EXECUTABLE = "shipyard-wake";
+var REPOSITORY_RUNNER_WORKFLOW = `name: Shipyard wake-up
+
+on:
+  issues:
+    types: [labeled]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  filter:
+    name: Check wake eligibility
+    runs-on: ubuntu-latest
+    outputs:
+      wake: \${{ steps.filter.outputs.wake }}
+    steps:
+      - name: Match the wake-up trigger
+        id: filter
+        shell: bash
+        env:
+          EVENT_NAME: \${{ github.event_name }}
+          LABEL_NAME: \${{ github.event.label.name }}
+        run: |
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]] || [[ "$EVENT_NAME" == "issues" && "$LABEL_NAME" == "shipyard" ]]; then
+            echo "wake=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "wake=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  wake:
+    name: Deliver wake-up
+    needs: filter
+    if: needs.filter.outputs.wake == 'true'
+    runs-on: [self-hosted, macOS, shipyard]
+    steps:
+      - name: Signal the foreground repository runner
+        shell: bash
+        run: '"$RUNNER_TEMP/../../shipyard-wake"'
+`;
+var REPOSITORY_RUNNER_WAKE_SCRIPT = `#!/bin/bash
+set -euo pipefail
+
+runner_dir="$(cd -- "$(dirname -- "$0")" && pwd)"
+lock_path="$runner_dir/.shipyard-controller.lock"
+
+if [[ ! -r "$lock_path" ]]; then
+  echo "::error::The Shipyard repository runner controller is unavailable. Start it with npx shipyard runner start."
+  exit 1
+fi
+
+controller_pid="$(sed -n 's/.*"pid"[[:space:]]*:[[:space:]]*\\([0-9][0-9]*\\).*/\\1/p' "$lock_path" | head -n 1)"
+controller_started_at="$(sed -n 's/.*"processStartedAt"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' "$lock_path" | head -n 1)"
+if [[ -z "$controller_pid" ]] || [[ -z "$controller_started_at" ]]; then
+  echo "::error::The Shipyard repository runner controller is unavailable. Start it with npx shipyard runner start."
+  exit 1
+fi
+current_started_at="$(ps -p "$controller_pid" -o lstart= 2>/dev/null | awk '{$1=$1; print}' || true)"
+if [[ "$current_started_at" != "$controller_started_at" ]] || ! kill -0 "$controller_pid" 2>/dev/null; then
+  echo "::error::The Shipyard repository runner controller is unavailable. Start it with npx shipyard runner start."
+  exit 1
+fi
+
+if ! kill -USR1 "$controller_pid"; then
+  echo "::error::The Shipyard repository runner controller could not receive the wake-up."
+  exit 1
+fi
+
+echo "Wake-up delivered to the Shipyard repository runner controller."
+`;
+var RepositoryRunnerWakeError = class extends Error {
+  name = "RepositoryRunnerWakeError";
+};
+var workflowCollisionMessage = () => `Refusing to overwrite the differing workflow at ${REPOSITORY_RUNNER_WORKFLOW_PATH}. Replace it with the required Shipyard wake-only workflow, then retry:
+
+${REPOSITORY_RUNNER_WORKFLOW}`;
+var publishedWorkflowFailureMessage = (repository, defaultBranch, error) => {
+  const details = error instanceof Error ? error.message : String(error);
+  if (/HTTP 403|Resource not accessible by personal access token/i.test(details)) {
+    return `The Shipyard wake workflow could not be read for ${repository} on the default branch (${defaultBranch}). GitHub denied Contents: Read access for the host gh login. Authenticate gh with repository administration access, then start the runner again. GitHub reported: ${details}`;
+  }
+  return `The Shipyard wake workflow is not active for ${repository}. Commit and push ${REPOSITORY_RUNNER_WORKFLOW_PATH} to the default branch (${defaultBranch}), then start the runner again. GitHub reported: ${details}`;
+};
+var assertRepositoryRunnerWorkflowCanBeInstalled = async (repoDir, adapters) => {
+  const workflowPath = join(repoDir, REPOSITORY_RUNNER_WORKFLOW_PATH);
+  if (!await adapters.exists(workflowPath)) return;
+  if (await adapters.readText(workflowPath) !== REPOSITORY_RUNNER_WORKFLOW) {
+    throw new RepositoryRunnerWakeError(workflowCollisionMessage());
+  }
+};
+var ensureDirectory = async (path, adapters) => {
+  if (!await adapters.exists(path)) await adapters.makeDirectory(path);
+};
+var installRepositoryRunnerWakeFiles = async (options, adapters) => {
+  await assertRepositoryRunnerWorkflowCanBeInstalled(options.repoDir, adapters);
+  const githubDir = join(options.repoDir, ".github");
+  const workflowsDir = join(githubDir, "workflows");
+  await ensureDirectory(githubDir, adapters);
+  await ensureDirectory(workflowsDir, adapters);
+  await adapters.writeText(
+    join(options.repoDir, REPOSITORY_RUNNER_WORKFLOW_PATH),
+    REPOSITORY_RUNNER_WORKFLOW
+  );
+  const wakeExecutable = join(
+    options.runnerDir,
+    REPOSITORY_RUNNER_WAKE_EXECUTABLE
+  );
+  await adapters.writeText(wakeExecutable, REPOSITORY_RUNNER_WAKE_SCRIPT);
+  await adapters.chmod(wakeExecutable, 448);
+};
+var requirePublishedRepositoryRunnerWorkflow = async (options, adapter) => {
+  let defaultBranch;
+  try {
+    const result = await adapter.run(
+      "gh",
+      ["api", `repos/${options.repository}`, "--jq", ".default_branch"],
+      { cwd: options.repoDir, env: options.environment }
+    );
+    defaultBranch = result.stdout.trim();
+    if (defaultBranch.length === 0) throw new Error("empty default branch");
+  } catch (error) {
+    throw new RepositoryRunnerWakeError(
+      `Could not determine the GitHub default branch for ${options.repository}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let publishedWorkflow;
+  try {
+    const result = await adapter.run(
+      "gh",
+      [
+        "api",
+        "--method",
+        "GET",
+        "-H",
+        "Accept: application/vnd.github.raw+json",
+        `repos/${options.repository}/contents/${REPOSITORY_RUNNER_WORKFLOW_PATH}?ref=${encodeURIComponent(defaultBranch)}`
+      ],
+      { cwd: options.repoDir, env: options.environment }
+    );
+    publishedWorkflow = result.stdout;
+  } catch (error) {
+    throw new RepositoryRunnerWakeError(
+      publishedWorkflowFailureMessage(options.repository, defaultBranch, error)
+    );
+  }
+  if (publishedWorkflow !== REPOSITORY_RUNNER_WORKFLOW) {
+    throw new RepositoryRunnerWakeError(
+      `The Shipyard wake workflow on the default branch (${defaultBranch}) does not match the required workflow. Update and push ${REPOSITORY_RUNNER_WORKFLOW_PATH}, then start the runner again.
+
+${REPOSITORY_RUNNER_WORKFLOW}`
+    );
+  }
+};
+var createRepositoryRunnerWakeSubscription = (subscribe = (listener) => {
+  process.on("SIGUSR1", listener);
+  return () => process.removeListener("SIGUSR1", listener);
+}) => {
+  let pending = false;
+  let closed = false;
+  let resolveNext;
+  const unsubscribe = subscribe(() => {
+    if (closed || pending) return;
+    pending = true;
+    resolveNext?.();
+    resolveNext = void 0;
+  });
+  return {
+    next: async () => {
+      if (closed) return;
+      if (!pending) {
+        await new Promise((resolve2) => {
+          resolveNext = resolve2;
+        });
+      }
+      pending = false;
+    },
+    close: () => {
+      if (closed) return;
+      closed = true;
+      unsubscribe();
+      resolveNext?.();
+      resolveNext = void 0;
+    }
+  };
+};
+
+// src/RepositoryRunner.ts
+var execFileAsync = promisify(execFile);
+var RUNNER_ARCHIVE = "runner.tgz";
+var RELEASES_API = "https://api.github.com/repos/actions/runner/releases/latest";
+var RunnerInstallError = class extends Error {
+  name = "RunnerInstallError";
+};
+var defaultAdapters = {
+  platform: () => process.platform,
+  arch: () => process.arch,
+  hostname,
+  environment: () => process.env,
+  exists: async (path) => {
+    try {
+      await access(path, constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  readText: (path) => readFile(path, "utf8"),
+  writeText: (path, content) => writeFile(path, content, { mode: 384 }),
+  writeBytes: (path, content) => writeFile(path, content, { mode: 384 }),
+  makeDirectory: (path) => mkdir(path, { recursive: false, mode: 448 }),
+  remove: (path) => rm(path, { recursive: true, force: true }),
+  chmod,
+  commandExists: async (command) => {
+    try {
+      await execFileAsync("which", [command]);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  inspectDirectory: async (path) => {
+    const [stat, resolved] = await Promise.all([lstat(path), realpath(path)]);
+    return {
+      realPath: resolved,
+      directory: stat.isDirectory(),
+      symbolicLink: stat.isSymbolicLink()
+    };
+  },
+  fetchJson: async (url) => {
+    const response = await fetch(url, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "User-Agent": "shipyard-runner-installer",
+        "X-GitHub-Api-Version": "2022-11-28"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`GitHub returned HTTP ${response.status}`);
+    }
+    return response.json();
+  },
+  fetchBytes: async (url) => {
+    const response = await fetch(url, {
+      headers: { "User-Agent": "shipyard-runner-installer" }
+    });
+    if (!response.ok) {
+      throw new Error(`GitHub returned HTTP ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  },
+  run: async (command, args, options) => {
+    const result = await execFileAsync(command, [...args], {
+      cwd: options.cwd,
+      env: options.env,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return { stdout: result.stdout, stderr: result.stderr };
+  }
+};
+var parseGitHubRepository = (remote) => {
+  const trimmed = remote.trim();
+  const sshMatch = trimmed.match(
+    /^(?:git@github\.com:|ssh:\/\/git@github\.com\/)([^/]+)\/([^/]+?)(?:\.git)?$/
+  );
+  const httpsMatch = trimmed.match(
+    /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/
+  );
+  const match = sshMatch ?? httpsMatch;
+  if (!match) {
+    throw new RunnerInstallError(
+      "The origin remote must be a GitHub.com repository (github.com/owner/repository). GitHub Enterprise and other hosts are not supported yet."
+    );
+  }
+  return { owner: match[1], repository: match[2] };
+};
+var normalizeNamePart = (value) => {
+  const normalized = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-");
+  return normalized || "unknown";
+};
+var requireCommand = async (adapters, command, purpose) => {
+  if (!await adapters.commandExists(command)) {
+    throw new RunnerInstallError(
+      `Missing required command \`${command}\` (${purpose}). Install it and retry.`
+    );
+  }
+};
+var asRelease = (value) => {
+  if (typeof value !== "object" || value === null) {
+    throw new RunnerInstallError(
+      "GitHub returned invalid runner release metadata."
+    );
+  }
+  const release = value;
+  if (typeof release.tag_name !== "string" || !Array.isArray(release.assets)) {
+    throw new RunnerInstallError(
+      "GitHub returned invalid runner release metadata."
+    );
+  }
+  return release;
+};
+var selectArm64Asset = (release) => {
+  const asset = release.assets.find(
+    (candidate) => /^actions-runner-osx-arm64-[\d.]+\.tar\.gz$/.test(candidate.name)
+  );
+  if (!asset || !asset.browser_download_url.startsWith(
+    "https://github.com/actions/runner/releases/download/"
+  ) || !/^sha256:[a-f0-9]{64}$/i.test(asset.digest)) {
+    throw new RunnerInstallError(
+      "The latest official GitHub Actions runner release has no verifiable macOS ARM64 archive."
+    );
+  }
+  return asset;
+};
+var appendRunnerIgnores = async (gitignorePath, adapters) => {
+  const current = await adapters.exists(gitignorePath) ? await adapters.readText(gitignorePath) : "";
+  const lines = new Set(current.split(/\r?\n/));
+  const additions = [`${RUNNER_DIR}/`, `${RUNNER_SANDBOX_MASK_DIR}/`].filter(
+    (line) => !lines.has(line)
+  );
+  if (additions.length === 0) return;
+  const prefix = current.length === 0 || current.endsWith("\n") ? current : `${current}
+`;
+  await adapters.writeText(gitignorePath, `${prefix}${additions.join("\n")}
+`);
+};
+var commandFailure = (purpose, error) => new RunnerInstallError(
+  `${purpose} failed: ${error instanceof Error ? error.message : String(error)}`
+);
+var reportProgress = (options, current, total, message) => options.onProgress?.({ current, total, message });
+var installRepositoryRunner = async (options, adapters = defaultAdapters) => {
+  if (adapters.platform() !== "darwin" || adapters.arch() !== "arm64") {
+    throw new RunnerInstallError(
+      "Repository runners currently require Apple Silicon macOS (darwin/arm64)."
+    );
+  }
+  const configDir = join(options.repoDir, CONFIG_DIR);
+  const runnerDir = join(configDir, RUNNER_DIR);
+  const maskDir = join(configDir, RUNNER_SANDBOX_MASK_DIR);
+  if (!await adapters.exists(configDir)) {
+    throw new RunnerInstallError(
+      `No ${CONFIG_DIR}/ found. Run \`shipyard init\` in this repository first.`
+    );
+  }
+  const runnerExists = await adapters.exists(runnerDir);
+  const progressTotal = runnerExists ? 3 : 8;
+  try {
+    await assertRepositoryRunnerWorkflowCanBeInstalled(
+      options.repoDir,
+      adapters
+    );
+  } catch (error) {
+    throw new RunnerInstallError(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+  await requireCommand(adapters, "git", "reading the repository remote");
+  if (!runnerExists) {
+    await requireCommand(adapters, "tar", "extracting the runner archive");
+  }
+  await requireCommand(adapters, "gh", "checking repository runner uniqueness");
+  const hostEnv = adapters.environment();
+  const gitRemote = await adapters.run("git", ["remote", "get-url", "origin"], {
+    cwd: options.repoDir,
+    env: hostEnv
+  }).catch((error) => {
+    throw commandFailure("Reading the origin remote", error);
+  });
+  const identity = parseGitHubRepository(gitRemote.stdout);
+  const repository = `${identity.owner}/${identity.repository}`;
+  const repoUrl = `https://github.com/${repository}`;
+  const runnerName = `shipyard-${normalizeNamePart(identity.repository)}-${normalizeNamePart(adapters.hostname())}`;
+  await adapters.run("gh", ["auth", "status", "--hostname", "github.com"], {
+    cwd: options.repoDir,
+    env: hostEnv
+  }).catch((error) => {
+    throw commandFailure(
+      "GitHub CLI authentication (repository administration is required)",
+      error
+    );
+  });
+  reportProgress(
+    options,
+    1,
+    progressTotal,
+    "Validated repository and GitHub access"
+  );
+  if (runnerExists) {
+    let metadata;
+    try {
+      metadata = await validateExistingRepositoryRunner(
+        {
+          repoDir: options.repoDir,
+          runnerDir,
+          maskDir,
+          repository,
+          runnerName
+        },
+        adapters
+      );
+    } catch (error) {
+      throw new RunnerInstallError(
+        error instanceof RunnerLifecycleError ? error.message : `Validating the existing repository runner failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    await appendRunnerIgnores(join(configDir, ".gitignore"), adapters);
+    await adapters.chmod(runnerDir, 448);
+    await adapters.chmod(maskDir, 448);
+    await assertProtectedDirectoryIdentities(
+      runnerDir,
+      maskDir,
+      adapters.inspectDirectory
+    ).catch((error) => {
+      throw commandFailure("Validating protected runner directories", error);
+    });
+    reportProgress(options, 2, progressTotal, "Validated existing runner");
+    try {
+      await installRepositoryRunnerWakeFiles(
+        { repoDir: options.repoDir, runnerDir },
+        adapters
+      );
+    } catch (error) {
+      throw new RunnerInstallError(
+        `The existing runner is valid, but its wake-up files could not be refreshed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    reportProgress(options, 3, progressTotal, "Refreshed wake-up workflow");
+    return {
+      name: metadata.name,
+      repository: metadata.repository,
+      version: metadata.version,
+      runnerDir
+    };
+  }
+  const existing = await adapters.run(
+    "gh",
+    [
+      "api",
+      "--paginate",
+      `repos/${repository}/actions/runners`,
+      "--jq",
+      `.runners[] | select(any(.labels[]; .name == "${ACTIVATION_LABEL}")) | .name`
+    ],
+    { cwd: options.repoDir, env: hostEnv }
+  ).catch((error) => {
+    throw commandFailure(
+      "Checking existing repository runners (repository administration is required)",
+      error
+    );
+  });
+  if (existing.stdout.trim().length > 0) {
+    throw new RunnerInstallError(
+      `A repository runner labeled \`${ACTIVATION_LABEL}\` is already registered for ${repository}. Remove it before installing another.`
+    );
+  }
+  reportProgress(
+    options,
+    2,
+    progressTotal,
+    "Checked for conflicting repository runners"
+  );
+  let registrationToken = options.registrationToken;
+  if (!registrationToken) {
+    const tokenResult = await adapters.run(
+      "gh",
+      [
+        "api",
+        "--method",
+        "POST",
+        `repos/${repository}/actions/runners/registration-token`
+      ],
+      { cwd: options.repoDir, env: hostEnv }
+    ).catch((error) => {
+      throw commandFailure(
+        "Requesting a one-time runner registration token (repository administration is required)",
+        error
+      );
+    });
+    try {
+      const parsed = JSON.parse(tokenResult.stdout);
+      if (typeof parsed.token !== "string" || parsed.token.length === 0) {
+        throw new Error("response did not contain a token");
+      }
+      registrationToken = parsed.token;
+    } catch (error) {
+      throw commandFailure("Reading the one-time registration token", error);
+    }
+  }
+  reportProgress(
+    options,
+    3,
+    progressTotal,
+    "Prepared runner registration token"
+  );
+  let release;
+  try {
+    release = asRelease(await adapters.fetchJson(RELEASES_API));
+  } catch (error) {
+    if (error instanceof RunnerInstallError) throw error;
+    throw commandFailure("Fetching official runner release metadata", error);
+  }
+  const asset = selectArm64Asset(release);
+  const version = release.tag_name.replace(/^v/, "");
+  let archive;
+  try {
+    archive = await adapters.fetchBytes(asset.browser_download_url);
+  } catch (error) {
+    throw commandFailure("Downloading the official runner archive", error);
+  }
+  const actualDigest = createHash("sha256").update(archive).digest("hex");
+  const expectedDigest = asset.digest.slice("sha256:".length).toLowerCase();
+  if (actualDigest !== expectedDigest) {
+    throw new RunnerInstallError(
+      `Runner archive digest mismatch: expected ${expectedDigest}, received ${actualDigest}. Nothing was installed.`
+    );
+  }
+  reportProgress(
+    options,
+    4,
+    progressTotal,
+    "Downloaded and verified official runner archive"
+  );
+  await appendRunnerIgnores(join(configDir, ".gitignore"), adapters);
+  await adapters.makeDirectory(runnerDir).catch((error) => {
+    throw commandFailure("Creating the protected runner directory", error);
+  });
+  if (!await adapters.exists(maskDir)) {
+    await adapters.makeDirectory(maskDir);
+  }
+  await assertProtectedDirectoryIdentities(
+    runnerDir,
+    maskDir,
+    adapters.inspectDirectory
+  ).catch((error) => {
+    throw commandFailure("Validating protected runner directories", error);
+  });
+  await adapters.chmod(runnerDir, 448);
+  await adapters.chmod(maskDir, 448);
+  reportProgress(
+    options,
+    5,
+    progressTotal,
+    "Prepared protected runner directories"
+  );
+  const archivePath = join(runnerDir, RUNNER_ARCHIVE);
+  await adapters.writeBytes(archivePath, archive);
+  try {
+    await adapters.run("tar", ["-xzf", archivePath, "--directory", runnerDir], {
+      cwd: options.repoDir,
+      env: repositoryRunnerEnvironment(hostEnv)
+    });
+  } catch (error) {
+    await adapters.remove(runnerDir);
+    throw commandFailure("Extracting the verified runner archive", error);
+  } finally {
+    await adapters.remove(archivePath);
+  }
+  reportProgress(options, 6, progressTotal, "Extracted runner archive");
+  try {
+    await adapters.run(
+      "./config.sh",
+      [
+        "--url",
+        repoUrl,
+        "--token",
+        registrationToken,
+        "--name",
+        runnerName,
+        "--labels",
+        ACTIVATION_LABEL,
+        "--work",
+        "_work",
+        "--unattended"
+      ],
+      { cwd: runnerDir, env: repositoryRunnerEnvironment(hostEnv) }
+    );
+  } catch {
+    const cleanup = await Promise.allSettled([
+      adapters.remove(runnerDir),
+      adapters.remove(maskDir)
+    ]);
+    const cleanupSucceeded = cleanup.every(
+      (result) => result.status === "fulfilled"
+    );
+    throw new RunnerInstallError(
+      cleanupSucceeded ? `Registering ${runnerName} failed. Partial local runner files were removed so installation can be retried. Check GitHub Settings > Actions > Runners for an orphan registration; the one-time token was not stored.` : `Registering ${runnerName} failed and partial local runner files could not be fully removed. Remove only ${runnerDir} and ${maskDir}, check GitHub Settings > Actions > Runners for an orphan registration, then retry. The one-time token was not stored.`
+    );
+  }
+  reportProgress(options, 7, progressTotal, "Registered runner with GitHub");
+  await adapters.writeText(
+    join(runnerDir, RUNNER_INSTALL_METADATA),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        repository,
+        repositoryUrl: repoUrl,
+        name: runnerName,
+        label: ACTIVATION_LABEL,
+        version
+      },
+      null,
+      2
+    )}
+`
+  );
+  try {
+    await installRepositoryRunnerWakeFiles(
+      { repoDir: options.repoDir, runnerDir },
+      adapters
+    );
+  } catch (error) {
+    throw new RunnerInstallError(
+      `The runner was registered, but its wake-up files could not be installed. Runner files were retained at ${runnerDir}; fix the error and retry: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  reportProgress(options, 8, progressTotal, "Installed wake-up workflow");
+  return { name: runnerName, repository, version, runnerDir };
+};
+
+// src/InitRepositoryRunner.ts
+var initializeRepositoryRunner = async (options) => {
+  let shouldInstall = options.requested;
+  if (shouldInstall === void 0) {
+    shouldInstall = options.interactive ? await options.confirm({
+      message: "Install a foreground repository runner for labelled GitHub issues?",
+      initialValue: true
+    }) : false;
+  }
+  if (!shouldInstall) return { status: "declined" };
+  try {
+    return { status: "installed", result: await options.install() };
+  } catch (error) {
+    return {
+      status: "failed",
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+var repositoryRunnerNextSteps = () => [
+  `First, commit and push ${REPOSITORY_RUNNER_WORKFLOW_PATH} to the repository's default branch`,
+  `Keep the foreground controller open with \`npx ${CLI_NAME} runner start\``,
+  `Inspect it from another terminal with \`npx ${CLI_NAME} runner status\``,
+  `Stop it with \`npx ${CLI_NAME} runner stop\``,
+  `Unregister and delete its protected files with \`npx ${CLI_NAME} runner remove\``
+];
+var execFileAsync2 = promisify(execFile);
+var CONTROLLER_STATE = ".shipyard-state.json";
+var LAST_FAILURE = ".shipyard-last-failure.json";
+var LOG_PURGE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var RunnerControlError = class extends Error {
+  name = "RunnerControlError";
+};
+var retainedFailures = /* @__PURE__ */ new WeakSet();
+var spawnForegroundChild = (command, args, options) => {
+  const child = spawn(command, [...args], {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: "inherit",
+    detached: true
+  });
+  const pid = child.pid;
+  if (pid === void 0) {
+    throw new RunnerControlError(`Could not start ${command}.`);
+  }
+  const result = new Promise((resolve2, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => resolve2({ code, signal }));
+  });
+  return {
+    pid,
+    wait: () => result,
+    terminate: (signal) => {
+      try {
+        process.kill(-pid, signal);
+      } catch {
+        child.kill(signal);
+      }
+    }
+  };
+};
+var registerRunnerShutdown = (handler) => {
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  let handling = false;
+  const listeners = /* @__PURE__ */ new Map();
+  const unregister = () => {
+    for (const [signal, listener] of listeners) {
+      process.removeListener(signal, listener);
+    }
+    listeners.clear();
+  };
+  for (const signal of signals) {
+    const listener = () => {
+      if (handling) return;
+      handling = true;
+      void handler().finally(() => {
+        unregister();
+        process.exit(
+          signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 129
+        );
+      });
+    };
+    listeners.set(signal, listener);
+    process.once(signal, listener);
+  }
+  return unregister;
+};
+var defaultAdapters2 = {
+  platform: () => process.platform,
+  arch: () => process.arch,
+  environment: () => process.env,
+  currentPid: () => process.pid,
+  processIdentity: async (pid) => {
+    try {
+      const result = await execFileAsync2("ps", [
+        "-p",
+        String(pid),
+        "-o",
+        "lstart="
+      ]);
+      const identity = result.stdout.trim().replace(/\s+/g, " ");
+      return identity.length > 0 ? identity : void 0;
+    } catch {
+      return void 0;
+    }
+  },
+  exists: async (path) => {
+    try {
+      await access(path, constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  inspectDirectory: async (path) => {
+    const [stat, resolved] = await Promise.all([lstat(path), realpath(path)]);
+    return {
+      realPath: resolved,
+      directory: stat.isDirectory(),
+      symbolicLink: stat.isSymbolicLink()
+    };
+  },
+  readText: (path) => readFile(path, "utf8"),
+  writeText: (path, content) => writeFile(path, content, { mode: 384 }),
+  writeExclusive: (path, content) => writeFile(path, content, { encoding: "utf8", mode: 384, flag: "wx" }),
+  remove: (path) => rm(path, { force: true }),
+  makeDirectory: async (path) => {
+    await mkdir(path, { recursive: true, mode: 448 });
+  },
+  removeTree: (path) => rm(path, { recursive: true, force: true }),
+  commandExists: async (command) => {
+    try {
+      await execFileAsync2("which", [command]);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  resolveEnvironment: (repoDir) => Effect.runPromise(
+    resolveEnv(repoDir).pipe(Effect.provide(NodeFileSystem.layer))
+  ),
+  run: async (command, args, options) => {
+    const result = await execFileAsync2(command, [...args], {
+      cwd: options.cwd,
+      env: options.env,
+      maxBuffer: 10 * 1024 * 1024
+    });
+    return { stdout: result.stdout, stderr: result.stderr };
+  },
+  spawn: spawnForegroundChild,
+  isProcessRunning: (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  signalProcess: (pid, signal) => process.kill(pid, signal),
+  onShutdown: registerRunnerShutdown,
+  pause: (milliseconds) => new Promise((resolve2) => setTimeout(resolve2, milliseconds)),
+  now: () => /* @__PURE__ */ new Date(),
+  purgeRunLogs,
+  scheduleRecurring: (task, milliseconds) => {
+    const timer = setInterval(() => {
+      void task();
+    }, milliseconds);
+    return () => clearInterval(timer);
+  },
+  report: (message) => console.log(message)
+};
+var readJson = async (path, adapters) => {
+  if (!await adapters.exists(path)) return void 0;
+  try {
+    return JSON.parse(await adapters.readText(path));
+  } catch (error) {
+    throw new RunnerControlError(
+      `Could not read repository runner state at ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+};
+var writeJson = (path, value, adapters) => adapters.writeText(path, `${JSON.stringify(value, null, 2)}
+`);
+var controlFailure = (purpose, error) => error instanceof RunnerControlError ? error : new RunnerControlError(
+  `${purpose} failed: ${error instanceof Error ? error.message : String(error)}`
+);
+var runCommand = async (adapters, purpose, command, args, options) => {
+  try {
+    return await adapters.run(command, args, options);
+  } catch (error) {
+    throw controlFailure(purpose, error);
+  }
+};
+var requireCommand2 = async (adapters, command, purpose) => {
+  if (!await adapters.commandExists(command)) {
+    throw new RunnerControlError(
+      `Missing required command \`${command}\` (${purpose}). Install it and retry.`
+    );
+  }
+};
+var requireRunnerContext = async (repoDir, adapters) => {
+  if (adapters.platform() !== "darwin" || adapters.arch() !== "arm64") {
+    throw new RunnerControlError(
+      "Repository runners currently require Apple Silicon macOS (darwin/arm64)."
+    );
+  }
+  const configDir = join(repoDir, CONFIG_DIR);
+  const runnerDir = join(configDir, RUNNER_DIR);
+  const maskDir = join(configDir, RUNNER_SANDBOX_MASK_DIR);
+  if (!await adapters.exists(configDir)) {
+    throw new RunnerControlError(
+      `No ${CONFIG_DIR}/ found. Run \`shipyard init\` in this repository first.`
+    );
+  }
+  if (!await adapters.exists(runnerDir)) {
+    throw new RunnerControlError(
+      `No repository runner is installed at ${runnerDir}. Run \`shipyard runner install\` first.`
+    );
+  }
+  if (adapters.inspectDirectory) {
+    const runnerIdentity = await adapters.inspectDirectory(runnerDir).catch((error) => {
+      throw controlFailure(
+        "Inspecting the protected runner directory",
+        error
+      );
+    });
+    if (!runnerIdentity.directory || runnerIdentity.symbolicLink) {
+      throw new RunnerControlError(
+        `The protected repository runner path must be a real directory: ${runnerDir}`
+      );
+    }
+  }
+  const metadata = await readJson(
+    join(runnerDir, RUNNER_INSTALL_METADATA),
+    adapters
+  );
+  if (metadata?.schemaVersion !== 1 || typeof metadata.repository !== "string" || typeof metadata.name !== "string" || metadata.label !== ACTIVATION_LABEL) {
+    throw new RunnerControlError(
+      "The repository runner installation metadata is missing or invalid. Reinstall the repository runner."
+    );
+  }
+  if (!await adapters.exists(join(runnerDir, "run.sh"))) {
+    throw new RunnerControlError(
+      "The official repository runner executable is missing. Reinstall the repository runner."
+    );
+  }
+  for (const [command, purpose] of [
+    ["git", "reading the repository remote"],
+    ["npx", "running the local Shipyard package"],
+    ["docker", "checking the Docker runtime"],
+    ["gh", "checking GitHub access"]
+  ]) {
+    await requireCommand2(adapters, command, purpose);
+  }
+  const hostEnvironment = adapters.environment();
+  const resolvedEnvironment = await adapters.resolveEnvironment(repoDir).catch((error) => {
+    throw controlFailure("Resolving repository credentials", error);
+  });
+  const runtimeEnvironment = {
+    ...hostEnvironment,
+    ...resolvedEnvironment,
+    [REPOSITORY_RUNNER_OWNER_ENV]: metadata.repository
+  };
+  const remote = await runCommand(
+    adapters,
+    "Reading the origin remote",
+    "git",
+    ["remote", "get-url", "origin"],
+    { cwd: repoDir, env: runtimeEnvironment }
+  );
+  let identity;
+  try {
+    identity = parseGitHubRepository(remote.stdout);
+  } catch (error) {
+    throw new RunnerControlError(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+  const repository = `${identity.owner}/${identity.repository}`;
+  if (repository !== metadata.repository) {
+    throw new RunnerControlError(
+      `The installed repository runner belongs to ${metadata.repository}, but this repository origin is ${repository}. Reinstall it for this repository.`
+    );
+  }
+  await runCommand(
+    adapters,
+    "Checking the local Shipyard package",
+    "npx",
+    ["--no-install", "shipyard", "--version"],
+    { cwd: repoDir, env: runtimeEnvironment }
+  );
+  await runCommand(
+    adapters,
+    "Checking Docker availability",
+    "docker",
+    ["info"],
+    { cwd: repoDir, env: runtimeEnvironment }
+  );
+  await runCommand(
+    adapters,
+    "Checking GitHub authentication",
+    "gh",
+    ["auth", "status", "--hostname", "github.com"],
+    { cwd: repoDir, env: hostEnvironment }
+  );
+  const label = await runCommand(
+    adapters,
+    "Checking the activation label",
+    "gh",
+    [
+      "label",
+      "list",
+      "--repo",
+      repository,
+      "--json",
+      "name",
+      "--jq",
+      `.[] | select(.name == "${ACTIVATION_LABEL}") | .name`
+    ],
+    { cwd: repoDir, env: hostEnvironment }
+  );
+  if (label.stdout.trim() !== ACTIVATION_LABEL) {
+    await runCommand(
+      adapters,
+      "Creating the activation label",
+      "gh",
+      [
+        "label",
+        "create",
+        ACTIVATION_LABEL,
+        "--repo",
+        repository,
+        "--color",
+        "1D76DB",
+        "--description",
+        "Tasks available to the Shipyard repository runner",
+        "--force"
+      ],
+      { cwd: repoDir, env: hostEnvironment }
+    );
+  }
+  await requirePublishedRepositoryRunnerWorkflow(
+    {
+      repoDir,
+      repository,
+      // The published workflow is an administrative runner preflight. Keep
+      // it on the host's gh login instead of the issue-agent token from
+      // .shipyard/.env, which intentionally only needs issue permissions.
+      environment: hostEnvironment
+    },
+    adapters
+  ).catch((error) => {
+    throw new RunnerControlError(
+      error instanceof Error ? error.message : String(error)
+    );
+  });
+  return {
+    runnerDir,
+    maskDir,
+    repository,
+    metadata,
+    hostEnvironment,
+    runtimeEnvironment
+  };
+};
+var childFailure = (command, result) => new RunnerControlError(
+  result.signal === null ? `${command} exited with code ${result.code ?? "unknown"}.` : `${command} was terminated by ${result.signal}.`
+);
+var stopChildBounded = async (child, pause) => {
+  child.terminate("SIGTERM");
+  const stopped = await Promise.race([
+    child.wait().then(() => true),
+    pause(5e3).then(() => false)
+  ]);
+  if (stopped) return;
+  child.terminate("SIGKILL");
+  const killed = await Promise.race([
+    child.wait().then(() => true),
+    pause(1e3).then(() => false)
+  ]);
+  if (!killed) {
+    throw new RunnerControlError(
+      `Process ${child.pid} did not exit after SIGKILL.`
+    );
+  }
+};
+var lockOwnsProcess = async (lock, adapters) => lock !== void 0 && Number.isInteger(lock.pid) && typeof lock.processStartedAt === "string" && lock.processStartedAt.length > 0 && adapters.isProcessRunning(lock.pid) && await adapters.processIdentity(lock.pid) === lock.processStartedAt;
+var bestEffort = async (operation) => {
+  try {
+    await operation();
+  } catch {
+  }
+};
+var startRepositoryRunnerManaged = async (options, adapters = defaultAdapters2) => {
+  const context = await requireRunnerContext(options.repoDir, adapters);
+  const lifecycleAdapters = {
+    environment: adapters.environment,
+    exists: adapters.exists,
+    readText: adapters.readText,
+    makeDirectory: adapters.makeDirectory,
+    inspectDirectory: adapters.inspectDirectory,
+    remove: adapters.removeTree,
+    run: adapters.run,
+    isProcessRunning: adapters.isProcessRunning,
+    signalProcess: adapters.signalProcess,
+    pause: adapters.pause,
+    processIdentity: adapters.processIdentity
+  };
+  await recoverRepositoryRunner(
+    {
+      repoDir: options.repoDir,
+      runnerDir: context.runnerDir,
+      maskDir: context.maskDir,
+      metadata: context.metadata,
+      runnerEnvironment: repositoryRunnerEnvironment(context.hostEnvironment),
+      dockerEnvironment: context.runtimeEnvironment
+    },
+    lifecycleAdapters
+  ).catch((error) => {
+    throw new RunnerControlError(
+      error instanceof RunnerLifecycleError ? error.message : `Repository runner recovery failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  });
+  const lockPath = join(context.runnerDir, RUNNER_CONTROLLER_LOCK);
+  const statePath = join(context.runnerDir, CONTROLLER_STATE);
+  const failurePath = join(context.runnerDir, LAST_FAILURE);
+  const existingLock = await readJson(lockPath, adapters);
+  if (await lockOwnsProcess(existingLock, adapters)) {
+    throw new RunnerControlError(
+      `The repository runner is already running with process ${existingLock.pid}.`
+    );
+  }
+  if (existingLock) {
+    throw new RunnerControlError(
+      "The repository runner has stale process state. Run it again after recovery or remove the stale installation."
+    );
+  }
+  const controllerPid = adapters.currentPid();
+  const processStartedAt = await adapters.processIdentity(controllerPid);
+  if (!processStartedAt) {
+    throw new RunnerControlError(
+      "Could not establish the repository runner controller process identity."
+    );
+  }
+  const lock = {
+    schemaVersion: 1,
+    pid: controllerPid,
+    repository: context.repository,
+    processStartedAt
+  };
+  try {
+    await adapters.writeExclusive(lockPath, `${JSON.stringify(lock)}
+`);
+  } catch (error) {
+    throw controlFailure("Claiming the repository runner process", error);
+  }
+  let listenerChild;
+  let shipyardChild;
+  let cancelLogPurge;
+  let stopping = false;
+  let lastWake;
+  let shutdownPromise;
+  let primaryFailure;
+  const saveState = async (state, lastOutcome) => {
+    await writeJson(
+      statePath,
+      {
+        schemaVersion: 1,
+        repository: context.repository,
+        state,
+        lastOutcome,
+        ...lastWake ? { lastWake } : {}
+      },
+      adapters
+    );
+    adapters.report(`[repository runner] ${state}: ${lastOutcome}`);
+  };
+  const purgeLogs = async () => {
+    if (stopping || shipyardChild !== void 0) return;
+    try {
+      const result = await adapters.purgeRunLogs({
+        repoDir: options.repoDir,
+        retentionDays: DEFAULT_LOG_RETENTION_DAYS,
+        now: adapters.now()
+      });
+      const removed = result.removedCount;
+      if (removed > 0) {
+        adapters.report(
+          `[repository runner] purged ${removed} outdated run-log ${removed === 1 ? "entry" : "entries"}`
+        );
+      }
+    } catch (error) {
+      adapters.report(
+        `[repository runner] log purge skipped: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  };
+  const removeTransientWork = () => adapters.removeTree(join(context.runnerDir, RUNNER_WORK_DIR));
+  const removeOwnedContainers = () => removeOwnedRepositoryRunnerContainers(
+    {
+      repoDir: options.repoDir,
+      repository: context.repository,
+      environment: context.runtimeEnvironment
+    },
+    lifecycleAdapters
+  );
+  const attemptCleanup = async (failures, purpose, operation) => {
+    try {
+      await operation();
+    } catch (error) {
+      const message = `${purpose} failed: ${error instanceof Error ? error.message : String(error)}`;
+      failures.push(message);
+      adapters.report(`[repository runner] cleanup error: ${message}`);
+    }
+  };
+  const persistCleanupFailures = async (failures) => {
+    if (failures.length === 0) return;
+    const cleanupMessage = `Repository runner cleanup failed: ${failures.join("; ")}`;
+    const message = primaryFailure ? `${primaryFailure.message} ${cleanupMessage}` : cleanupMessage;
+    await bestEffort(
+      () => writeJson(
+        failurePath,
+        {
+          schemaVersion: 1,
+          repository: context.repository,
+          message,
+          recordedAt: adapters.now().toISOString()
+        },
+        adapters
+      ).then(() => {
+        if (primaryFailure) retainedFailures.add(primaryFailure);
+      })
+    );
+    await bestEffort(() => saveState("stopped", cleanupMessage));
+  };
+  const shutdown = () => {
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = (async () => {
+      stopping = true;
+      const failures = [];
+      const children = [listenerChild, shipyardChild].filter(
+        (child) => child !== void 0
+      );
+      listenerChild = void 0;
+      shipyardChild = void 0;
+      await Promise.all(
+        children.map(
+          (child) => attemptCleanup(
+            failures,
+            `Stopping process ${child.pid}`,
+            () => stopChildBounded(child, adapters.pause)
+          )
+        )
+      );
+      await attemptCleanup(
+        failures,
+        "Removing repository-runner containers",
+        removeOwnedContainers
+      );
+      await attemptCleanup(
+        failures,
+        "Removing transient runner work",
+        removeTransientWork
+      );
+      await attemptCleanup(
+        failures,
+        "Removing controller lock",
+        () => adapters.remove(lockPath)
+      );
+      if (failures.length === 0) {
+        try {
+          await saveState("stopped", "Stopped by signal");
+        } catch (error) {
+          const message = `Persisting stopped state failed: ${error instanceof Error ? error.message : String(error)}`;
+          failures.push(message);
+          adapters.report(`[repository runner] cleanup error: ${message}`);
+        }
+      }
+      await persistCleanupFailures(failures);
+    })();
+    return shutdownPromise;
+  };
+  const unregisterShutdown = adapters.onShutdown(shutdown);
+  const wakeSubscription = createRepositoryRunnerWakeSubscription(
+    adapters.onWake
+  );
+  let initialWorkFound = false;
+  try {
+    await purgeLogs();
+    cancelLogPurge = adapters.scheduleRecurring(
+      purgeLogs,
+      LOG_PURGE_CHECK_INTERVAL_MS
+    );
+    const listEligibleIssueNumbers = async () => {
+      const issues = await runCommand(
+        adapters,
+        "Checking for eligible GitHub issues",
+        "gh",
+        [
+          "api",
+          "--method",
+          "GET",
+          "--paginate",
+          `repos/${context.repository}/issues`,
+          "-f",
+          "state=open",
+          "-f",
+          `labels=${ACTIVATION_LABEL}`,
+          "-f",
+          "per_page=100",
+          "--jq",
+          ".[] | select(.pull_request == null) | .number"
+        ],
+        { cwd: options.repoDir, env: context.runtimeEnvironment }
+      );
+      return [...new Set(issues.stdout.split(/\s+/).filter(Boolean))].sort(
+        (left, right) => Number(left) - Number(right)
+      );
+    };
+    const sameIssueNumbers = (left, right) => left.length === right.length && left.every((issue, index) => issue === right[index]);
+    const processEligibleWork = async () => {
+      let issueNumbers = await listEligibleIssueNumbers();
+      const workFound = issueNumbers.length > 0;
+      while (!stopping && issueNumbers.length > 0) {
+        await saveState("processing", "Shipyard is processing eligible issues");
+        shipyardChild = adapters.spawn("npx", ["shipyard", "run"], {
+          cwd: options.repoDir,
+          env: context.runtimeEnvironment
+        });
+        const runResult = await shipyardChild.wait();
+        shipyardChild = void 0;
+        if (stopping) {
+          await shutdownPromise;
+          return workFound;
+        }
+        if (runResult.code !== 0) {
+          const failure = childFailure("npx shipyard run", runResult);
+          await writeJson(
+            failurePath,
+            {
+              schemaVersion: 1,
+              repository: context.repository,
+              message: failure.message,
+              recordedAt: adapters.now().toISOString()
+            },
+            adapters
+          );
+          await saveState("stopped", failure.message);
+          throw failure;
+        }
+        const nextIssueNumbers = await listEligibleIssueNumbers();
+        if (nextIssueNumbers.length === 0) {
+          await saveState("idle", "Shipyard completed; no eligible issues");
+          break;
+        }
+        if (sameIssueNumbers(issueNumbers, nextIssueNumbers)) {
+          await saveState(
+            "stalled",
+            "Shipyard made no progress; eligible issues are unchanged"
+          );
+          break;
+        }
+        issueNumbers = nextIssueNumbers;
+      }
+      return workFound;
+    };
+    lastWake = {
+      source: "startup",
+      recordedAt: adapters.now().toISOString()
+    };
+    initialWorkFound = await processEligibleWork();
+    if (stopping) {
+      await shutdownPromise;
+      return { repository: context.repository, initialWorkFound };
+    }
+    if (!initialWorkFound) {
+      await saveState("idle", "No eligible issues; listening");
+    }
+    listenerChild = adapters.spawn("./run.sh", [], {
+      cwd: context.runnerDir,
+      env: repositoryRunnerEnvironment(context.hostEnvironment)
+    });
+    const listenerExit = listenerChild.wait().then((result) => ({
+      type: "listener",
+      result
+    }));
+    let listenerResult;
+    while (!listenerResult && !stopping) {
+      const event = await Promise.race([
+        listenerExit,
+        wakeSubscription.next().then(() => ({ type: "wake" }))
+      ]);
+      if (event.type === "listener") {
+        listenerResult = event.result;
+        listenerChild = void 0;
+        break;
+      }
+      if (stopping) break;
+      lastWake = {
+        source: "signal",
+        recordedAt: adapters.now().toISOString()
+      };
+      const workFound = await processEligibleWork();
+      if (!workFound && !stopping) {
+        await saveState("idle", "Wake-up delivered; no eligible issues");
+      }
+    }
+    if (stopping) {
+      await shutdownPromise;
+      return { repository: context.repository, initialWorkFound };
+    }
+    if (!listenerResult) {
+      throw new RunnerControlError(
+        "The repository runner listener stopped without an exit result."
+      );
+    }
+    if (listenerResult.code !== 0) {
+      const failure = childFailure(
+        "Repository runner listener",
+        listenerResult
+      );
+      await writeJson(
+        failurePath,
+        {
+          schemaVersion: 1,
+          repository: context.repository,
+          message: failure.message,
+          recordedAt: adapters.now().toISOString()
+        },
+        adapters
+      );
+      await saveState("stopped", failure.message);
+      throw failure;
+    }
+    await saveState("stopped", "Repository runner listener exited");
+    return { repository: context.repository, initialWorkFound };
+  } catch (error) {
+    const failure = controlFailure("Repository runner controller", error);
+    primaryFailure = failure;
+    await bestEffort(
+      () => writeJson(
+        failurePath,
+        {
+          schemaVersion: 1,
+          repository: context.repository,
+          message: failure.message,
+          recordedAt: adapters.now().toISOString()
+        },
+        adapters
+      ).then(() => retainedFailures.add(failure))
+    );
+    await bestEffort(() => saveState("stopped", failure.message));
+    throw failure;
+  } finally {
+    if (cancelLogPurge !== void 0) {
+      cancelLogPurge();
+      cancelLogPurge = void 0;
+    }
+    wakeSubscription.close();
+    unregisterShutdown();
+    if (shutdownPromise) {
+      await shutdownPromise;
+    } else {
+      const failures = [];
+      if (listenerChild) {
+        await attemptCleanup(
+          failures,
+          `Stopping process ${listenerChild.pid}`,
+          () => stopChildBounded(listenerChild, adapters.pause)
+        );
+      }
+      if (shipyardChild) {
+        await attemptCleanup(
+          failures,
+          `Stopping process ${shipyardChild.pid}`,
+          () => stopChildBounded(shipyardChild, adapters.pause)
+        );
+      }
+      await attemptCleanup(
+        failures,
+        "Removing repository-runner containers",
+        removeOwnedContainers
+      );
+      await attemptCleanup(
+        failures,
+        "Removing transient runner work",
+        removeTransientWork
+      );
+      await attemptCleanup(
+        failures,
+        "Removing controller lock",
+        () => adapters.remove(lockPath)
+      );
+      await persistCleanupFailures(failures);
+    }
+  }
+};
+var startRepositoryRunner = async (options, adapters = defaultAdapters2) => {
+  try {
+    return await startRepositoryRunnerManaged(options, adapters);
+  } catch (error) {
+    const failure = controlFailure("Repository runner startup", error);
+    if (retainedFailures.has(failure)) throw failure;
+    const runnerDir = join(options.repoDir, CONFIG_DIR, RUNNER_DIR);
+    if (await adapters.exists(runnerDir)) {
+      const metadata = await readJson(
+        join(runnerDir, RUNNER_INSTALL_METADATA),
+        adapters
+      ).catch(() => void 0);
+      const repository = metadata?.repository ?? "unknown";
+      for (const [purpose, operation] of [
+        [
+          "failure diagnostics",
+          () => writeJson(
+            join(runnerDir, LAST_FAILURE),
+            {
+              schemaVersion: 1,
+              repository,
+              message: failure.message,
+              recordedAt: adapters.now().toISOString()
+            },
+            adapters
+          )
+        ],
+        [
+          "stopped state",
+          () => writeJson(
+            join(runnerDir, CONTROLLER_STATE),
+            {
+              schemaVersion: 1,
+              repository,
+              state: "stopped",
+              lastOutcome: failure.message
+            },
+            adapters
+          )
+        ]
+      ]) {
+        try {
+          await operation();
+        } catch (persistenceError) {
+          adapters.report(
+            `[repository runner] Could not persist ${purpose}: ${persistenceError instanceof Error ? persistenceError.message : String(persistenceError)}`
+          );
+        }
+      }
+    }
+    throw failure;
+  }
+};
+var getRepositoryRunnerStatus = async (options, adapters = defaultAdapters2) => {
+  const runnerDir = join(options.repoDir, CONFIG_DIR, RUNNER_DIR);
+  const metadata = await readJson(
+    join(runnerDir, RUNNER_INSTALL_METADATA),
+    adapters
+  );
+  if (!metadata) {
+    return {
+      installed: false,
+      running: false,
+      github: "not-installed",
+      state: "not-installed",
+      lastOutcome: "Repository runner is not installed"
+    };
+  }
+  const lock = await readJson(
+    join(runnerDir, RUNNER_CONTROLLER_LOCK),
+    adapters
+  );
+  const state = await readJson(
+    join(runnerDir, CONTROLLER_STATE),
+    adapters
+  );
+  const running = await lockOwnsProcess(lock, adapters);
+  let github = "unreachable";
+  try {
+    const response = await adapters.run(
+      "gh",
+      [
+        "api",
+        `repos/${metadata.repository}/actions/runners`,
+        "--jq",
+        `.runners[] | select(.name == "${metadata.name}") | .status`
+      ],
+      {
+        cwd: options.repoDir,
+        // Runner connectivity is an administrative check. Do not let the
+        // issue-agent token from .shipyard/.env shadow the host gh login.
+        env: adapters.environment()
+      }
+    );
+    github = response.stdout.trim() === "online" ? "online" : "offline";
+  } catch {
+    github = "unreachable";
+  }
+  return {
+    installed: true,
+    running,
+    ...lock ? { pid: lock.pid } : {},
+    github,
+    repository: metadata.repository,
+    state: state?.state ?? (running ? "idle" : "stopped"),
+    lastOutcome: state?.lastOutcome ?? "No repository runner outcome recorded",
+    ...state?.lastWake ? { lastWake: state.lastWake } : {}
+  };
+};
+var stopRepositoryRunner = async (options, adapters = defaultAdapters2) => {
+  const lockPath = join(
+    options.repoDir,
+    CONFIG_DIR,
+    RUNNER_DIR,
+    RUNNER_CONTROLLER_LOCK
+  );
+  const lock = await readJson(lockPath, adapters);
+  if (!lock || !Number.isInteger(lock.pid)) {
+    throw new RunnerControlError("The repository runner is not running.");
+  }
+  if (!adapters.isProcessRunning(lock.pid)) {
+    throw new RunnerControlError(
+      `The recorded repository runner process ${lock.pid} is no longer running.`
+    );
+  }
+  try {
+    adapters.signalProcess(lock.pid, "SIGTERM");
+  } catch (error) {
+    throw controlFailure("Stopping the repository runner", error);
+  }
+  return { pid: lock.pid };
+};
+
+// src/RepositoryRunnerCommands.ts
+var registrationTokenOption = Options.text("registration-token").pipe(
+  Options.withDescription(
+    "one-time runner registration token (not stored; administrative gh access is still required for uniqueness checks)"
+  ),
+  Options.optional
+);
+var installRunnerCommand = Command.make(
+  "install",
+  { registrationToken: registrationTokenOption },
+  ({ registrationToken }) => Effect.gen(function* () {
+    const display = yield* Display;
+    const result = yield* display.progress(
+      "Installing repository runner",
+      (report) => Effect.tryPromise({
+        try: () => installRepositoryRunner({
+          repoDir: process.cwd(),
+          registrationToken: registrationToken._tag === "Some" ? registrationToken.value : void 0,
+          onProgress: report
+        }),
+        catch: (error) => new InitError({
+          message: error instanceof RunnerInstallError ? error.message : `Repository runner installation failed: ${error instanceof Error ? error.message : String(error)}`
+        })
+      })
+    );
+    yield* display.status(
+      `Installed ${result.name} for ${result.repository}.`,
+      "success"
+    );
+  })
+);
+var runnerControlEffect = (operation) => Effect.tryPromise({
+  try: operation,
+  catch: (error) => new InitError({
+    message: error instanceof RunnerControlError || error instanceof RunnerLifecycleError ? error.message : `Repository runner operation failed: ${error instanceof Error ? error.message : String(error)}`
+  })
+});
+var startRunnerCommand = Command.make(
+  "start",
+  {},
+  () => Effect.gen(function* () {
+    const display = yield* Display;
+    const cwd = process.cwd();
+    yield* display.status(
+      "Starting the repository runner in this terminal...",
+      "info"
+    );
+    const result = yield* runnerControlEffect(
+      () => startRepositoryRunner({ repoDir: cwd })
+    );
+    yield* display.status(
+      result.initialWorkFound ? `Repository runner for ${result.repository} stopped after processing startup work.` : `Repository runner for ${result.repository} stopped.`,
+      "info"
+    );
+  })
+);
+var statusRunnerCommand = Command.make(
+  "status",
+  {},
+  () => Effect.gen(function* () {
+    const display = yield* Display;
+    const status = yield* runnerControlEffect(
+      () => getRepositoryRunnerStatus({ repoDir: process.cwd() })
+    );
+    yield* display.summary("Repository runner", {
+      Installed: status.installed ? "yes" : "no",
+      "Local process": status.running ? `running (PID ${status.pid ?? "unknown"})` : "stopped",
+      GitHub: status.github,
+      Repository: status.repository ?? "unknown",
+      State: status.state,
+      "Last outcome": status.lastOutcome,
+      "Last wake": status.lastWake ? `${status.lastWake.source} at ${status.lastWake.recordedAt}` : "none recorded"
+    });
+  })
+);
+var stopRunnerCommand = Command.make(
+  "stop",
+  {},
+  () => Effect.gen(function* () {
+    const display = yield* Display;
+    const result = yield* runnerControlEffect(
+      () => stopRepositoryRunner({ repoDir: process.cwd() })
+    );
+    yield* display.status(
+      `Stopping repository runner process ${result.pid}...`,
+      "success"
+    );
+  })
+);
+var forceRemoveRunnerOption = Options.boolean("force").pipe(
+  Options.withDescription(
+    "delete local runner files if GitHub unregistration fails"
+  )
+);
+var removeRunnerCommand = Command.make(
+  "remove",
+  { force: forceRemoveRunnerOption },
+  ({ force }) => Effect.gen(function* () {
+    const display = yield* Display;
+    const result = yield* runnerControlEffect(
+      () => removeRepositoryRunner({ repoDir: process.cwd(), force })
+    );
+    yield* display.status("Repository runner removed.", "success");
+    if (result.manualCleanup) {
+      yield* display.status(result.manualCleanup, "warn");
+    }
+  })
+);
+var purgeRunnerCommand = Command.make(
+  "purge",
+  {},
+  () => Effect.gen(function* () {
+    const display = yield* Display;
+    const repoDir = process.cwd();
+    yield* requireCanonicalConfigDir(repoDir);
+    const result = yield* Effect.tryPromise({
+      try: () => purgeRunLogs({ repoDir }),
+      catch: (error) => new InitError({
+        message: `Run-log purge failed: ${error instanceof Error ? error.message : String(error)}`
+      })
+    });
+    const removed = result.removedCount;
+    yield* display.status(
+      removed === 0 ? "No run logs found." : `Purged ${removed} run-log ${removed === 1 ? "entry" : "entries"}.`,
+      "success"
+    );
+  })
+);
+var runnerCommand = Command.make(
+  "runner",
+  {},
+  () => Effect.gen(function* () {
+    const display = yield* Display;
+    yield* display.status(
+      "Repository runner and run-log commands. Use --help to see available subcommands.",
+      "info"
+    );
+  })
+).pipe(
+  Command.withSubcommands([
+    installRunnerCommand,
+    startRunnerCommand,
+    statusRunnerCommand,
+    stopRunnerCommand,
+    removeRunnerCommand,
+    purgeRunnerCommand
+  ])
+);
+var VERSION = "0.5.0" ;
 
 // src/cli.ts
 var imageNameOption = Options.text("image-name").pipe(
@@ -651,6 +2276,27 @@ var defaultUidBuildArgs = () => {
   return args;
 };
 var requireConfigDir = (cwd) => requireCanonicalConfigDir(cwd);
+var purgeRunLogsBestEffort = (display, repoDir) => Effect.tryPromise({
+  try: () => purgeRunLogs({
+    repoDir,
+    retentionDays: DEFAULT_LOG_RETENTION_DAYS
+  }),
+  catch: (error) => error
+}).pipe(
+  Effect.flatMap((result) => {
+    const removed = result.removedCount;
+    return removed === 0 ? Effect.void : display.status(
+      `Purged ${removed} outdated run-log ${removed === 1 ? "entry" : "entries"}.`,
+      "info"
+    );
+  }),
+  Effect.catchAll(
+    (error) => display.status(
+      `Automatic run-log purge skipped: ${error instanceof Error ? error.message : String(error)}`,
+      "warn"
+    )
+  )
+);
 var runSandboxOption = Options.choice("sandbox", ["docker"]).pipe(
   Options.withDescription(
     "Sandbox provider to build (inferred from Dockerfile)"
@@ -738,7 +2384,7 @@ var executeEntrypoint = (cwd, entrypoint) => Effect.async((resume, signal) => {
     );
   });
 });
-var runCommand = Command.make(
+var runCommand2 = Command.make(
   "run",
   {
     imageName: imageNameOption,
@@ -750,6 +2396,7 @@ var runCommand = Command.make(
     const d = yield* Display;
     const cwd = process.cwd();
     const configDir = yield* requireConfigDir(cwd);
+    yield* purgeRunLogsBestEffort(d, cwd);
     const resolvedEntrypoint = resolveRunEntrypoint(
       cwd,
       configDir,
@@ -811,25 +2458,25 @@ var issueTrackerOption = Options.text("issue-tracker").pipe(
   Options.withDescription("Issue tracker to use (github-issues)"),
   Options.optional
 );
-var createLabelOption = Options.choice("create-label", [
+var buildImageOption = Options.choice("build-image", ["true", "false"]).pipe(
+  Options.withDescription("Whether to build the sandbox image now"),
+  Options.optional
+);
+var installTemplateDepsOption = Options.choice("install-template-deps", [
   "true",
   "false"
 ]).pipe(
   Options.withDescription(
-    `Whether to create the "${PRODUCT_NAME}" GitHub label (only meaningful with --issue-tracker github-issues)`
+    "Whether to install the template's host dependencies (e.g. zod for the planner templates)"
   ),
   Options.optional
 );
-var buildImageOption = Options.choice("build-image", ["true", "false"]).pipe(
-  Options.withDescription("Whether to build the sandbox image now"),
-  Options.optional
-);
-var installTemplateDepsOption = Options.choice("install-template-deps", [
+var installRunnerOption = Options.choice("install-runner", [
   "true",
   "false"
 ]).pipe(
   Options.withDescription(
-    "Whether to install the template's host dependencies (e.g. zod for the planner templates)"
+    "Whether to install a foreground repository runner after scaffolding"
   ),
   Options.optional
 );
@@ -844,9 +2491,9 @@ var initCommand = Command.make(
     model: initModelOption,
     sandbox: sandboxOption,
     issueTracker: issueTrackerOption,
-    createLabel: createLabelOption,
     buildImage: buildImageOption,
-    installTemplateDeps: installTemplateDepsOption
+    installTemplateDeps: installTemplateDepsOption,
+    installRunner: installRunnerOption
   },
   ({
     imageName: imageNameFlag,
@@ -856,9 +2503,9 @@ var initCommand = Command.make(
     model: modelFlag,
     sandbox: sandboxFlag,
     issueTracker: issueTrackerFlag,
-    createLabel: createLabelFlag,
     buildImage: buildImageFlag,
-    installTemplateDeps: installTemplateDepsFlag
+    installTemplateDeps: installTemplateDepsFlag,
+    installRunner: installRunnerFlag
   }) => Effect.gen(function* () {
     const d = yield* Display;
     const cwd = process.cwd();
@@ -897,11 +2544,11 @@ var initCommand = Command.make(
         );
       }
     }
-    const createLabelChoice = choiceToTriBool(createLabelFlag);
     const buildImageChoice = choiceToTriBool(buildImageFlag);
     const installTemplateDepsChoice = choiceToTriBool(
       installTemplateDepsFlag
     );
+    const installRunnerChoice = choiceToTriBool(installRunnerFlag);
     const isInteractive = process.stdin.isTTY === true;
     const failIfNonInteractive = (flag) => Effect.fail(
       new InitError({
@@ -1080,31 +2727,21 @@ var initCommand = Command.make(
       }
       selectedTemplate = selected;
     }
-    let shouldCreateLabel = false;
     if (selectedIssueTracker.name === "github-issues") {
-      shouldCreateLabel = yield* resolveConfirmFlag({
-        choice: createLabelChoice,
-        flag: "--create-label",
-        promptMessage: `Create a "${PRODUCT_NAME}" GitHub label? (Templates filter issues by this label)`,
-        cancelMessage: "Label selection cancelled."
-      });
-      if (shouldCreateLabel) {
-        yield* Effect.try({
-          try: () => execSync(
-            `gh label create "${PRODUCT_NAME}" --description "Issues for ${PRODUCT_NAME} to work on" --color "F9A825" 2>/dev/null`,
-            { cwd, stdio: "ignore" }
-          ),
-          catch: () => void 0
-        }).pipe(Effect.ignore);
-      }
+      yield* Effect.try({
+        try: () => execSync(
+          `gh label create "${ACTIVATION_LABEL}" --description "Issues for ${PRODUCT_NAME} to work on" --color "F9A825" --force 2>/dev/null`,
+          { cwd, stdio: "ignore" }
+        ),
+        catch: () => void 0
+      }).pipe(Effect.ignore);
     }
-    const scaffoldResult = yield* d.spinner(
+    yield* d.spinner(
       `Scaffolding ${CONFIG_DIR}/ config directory...`,
       scaffold(cwd, {
         agent: selectedAgent,
         model: selectedModel,
         templateName: selectedTemplate,
-        createLabel: shouldCreateLabel,
         issueTracker: selectedIssueTracker,
         sandboxProvider: selectedSandboxProvider,
         codexAuth: selectedCodexAuth
@@ -1158,20 +2795,66 @@ var initCommand = Command.make(
           buildArgs: defaultUidBuildArgs()
         })
       );
-      yield* d.status("Init complete! Image built successfully.", "success");
+      yield* d.status("Image built successfully.", "success");
     } else {
       yield* d.status(
-        `Init complete! Run \`${CLI_NAME} ${selectedSandboxProvider.cliNamespace} build-image\` to build the ${providerLabel} image later.`,
+        `Run \`${CLI_NAME} ${selectedSandboxProvider.cliNamespace} build-image\` to build the ${providerLabel} image later.`,
+        "info"
+      );
+    }
+    const runnerInit = yield* Effect.tryPromise({
+      try: () => initializeRepositoryRunner({
+        interactive: isInteractive,
+        requested: installRunnerChoice._tag === "Some" ? installRunnerChoice.value : void 0,
+        confirm: async ({ message, initialValue }) => {
+          const confirmed = await clack.confirm({ message, initialValue });
+          if (clack.isCancel(confirmed)) {
+            throw new InitError({
+              message: "Repository-runner installation selection cancelled."
+            });
+          }
+          return confirmed === true;
+        },
+        install: () => Effect.runPromise(
+          d.progress(
+            "Installing repository runner",
+            (report) => Effect.tryPromise({
+              try: () => installRepositoryRunner({
+                repoDir: cwd,
+                onProgress: report
+              }),
+              catch: (error) => new InitError({
+                message: error instanceof RunnerInstallError ? error.message : `Repository runner installation failed: ${error instanceof Error ? error.message : String(error)}`
+              })
+            })
+          )
+        )
+      }),
+      catch: (error) => error instanceof InitError ? error : new InitError({
+        message: `Repository-runner setup failed: ${error instanceof Error ? error.message : String(error)}`
+      })
+    });
+    if (runnerInit.status === "installed") {
+      yield* d.status(
+        `Installed ${runnerInit.result.name} for ${runnerInit.result.repository}.`,
         "success"
       );
+      yield* d.text("Repository runner next steps:");
+      for (const [index, line] of repositoryRunnerNextSteps().entries()) {
+        yield* d.text(styleText("dim", `${index + 1}. ${line}`));
+      }
+    } else if (runnerInit.status === "failed") {
+      yield* d.status(
+        `Shipyard scaffolding is ready, but repository runner installation failed: ${runnerInit.message}`,
+        "warn"
+      );
+      yield* d.status(
+        `Retry from this repository with \`npx ${CLI_NAME} runner install\`.`,
+        "warn"
+      );
     }
-    const nextSteps = getNextStepsLines(
-      selectedTemplate,
-      scaffoldResult.mainFilename,
-      selectedAgent,
-      packageManager,
-      selectedCodexAuth
-    );
+    yield* d.status("Init complete!", "success");
+    const nextSteps = getNextStepsLines();
     for (const [i, line] of nextSteps.entries()) {
       yield* d.text(i === 0 ? line : styleText("dim", line));
     }
@@ -1243,7 +2926,12 @@ var rootCommand = Command.make(
   })
 );
 var shipyard = rootCommand.pipe(
-  Command.withSubcommands([initCommand, runCommand, dockerCommand])
+  Command.withSubcommands([
+    initCommand,
+    runCommand2,
+    dockerCommand,
+    runnerCommand
+  ])
 );
 var cli = Command.run(shipyard, {
   name: CLI_NAME,