@snappedly-tools/shipyard 0.5.0 → 0.6.0

package/dist/templates/shared/setup.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n ${GH_REPO:-} ]]; then
+  [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
+  git remote set-url origin "https://github.com/$GH_REPO.git"
+fi
+
+# Install for this sandbox's checkout. Host node_modules can contain binaries
+# for a different OS and cannot cover dependencies added by the agent later.
+if [[ -f package.json ]]; then
+  manager=$(node -e 'try { const p = require("./package.json").packageManager; process.stdout.write(p ? p.split("@")[0] : "") } catch {}')
+  if [[ -z "$manager" ]]; then
+    if [[ -f bun.lock || -f bun.lockb ]]; then manager=bun
+    elif [[ -f pnpm-lock.yaml ]]; then manager=pnpm
+    elif [[ -f yarn.lock ]]; then manager=yarn
+    else manager=npm; fi
+  fi
+  case "$manager" in
+    npm) npm install ;;
+    pnpm) corepack pnpm install ;;
+    yarn) corepack yarn install ;;
+    bun)
+      if ! command -v bun >/dev/null; then curl -fsSL https://bun.com/install | bash; export PATH="$HOME/.bun/bin:$PATH"; fi
+      bun install ;;
+    *) echo "Unsupported package manager: $manager" >&2; exit 1 ;;
+  esac
+fi
+
+source_dir=$(mktemp -d)
+trap 'rm -rf "$source_dir"' EXIT
+if ! git clone --depth 1 https://github.com/snappedly/skills.git "$source_dir/repo"; then
+  echo "Could not install Snappedly skills; agent work has not started." >&2
+  exit 1
+fi
+
+mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills"
+while IFS= read -r -d '' skill_file; do
+  skill_dir=${skill_file%/SKILL.md}
+  skill_name=${skill_dir##*/}
+  rm -rf "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+  cp -R "$skill_dir" "$HOME/.agents/skills/$skill_name"
+  ln -sfn "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+done < <(find "$source_dir/repo/skills" -name SKILL.md -print0)
+
+for skill in triage implement implement-spec code-cleanup code-review tdd; do
+  if [[ ! -s "$HOME/.agents/skills/$skill/SKILL.md" || -z $(find "$source_dir/repo/skills" -path "*/$skill/SKILL.md" -print -quit) ]]; then
+    echo "Snappedly skill installation incomplete: $skill" >&2
+    exit 1
+  fi
+done

package/dist/templates/shared/triage-prompt.md

@@ -0,0 +1,5 @@
+Triage GitHub issue #{{TASK_ID}} before Shipyard implementation.
+
+Follow `/triage` and the repository's `docs/agents/triage.md` label mapping. Read the full issue and comments, verify its claim against the codebase, then apply the appropriate category and state label and post the brief or triage notes required by the skill. The maintainer has authorized Shipyard to apply an evidence-based recommendation during this unattended intake. If a decision requires maintainer judgment, use `needs-triage` and record the question. Do not implement the issue or start a PR in this phase.
+
+Report the applied state and evidence. Shipyard will independently re-read GitHub labels and implement only an open issue carrying both `shipyard` and the sole triage state `ready-for-agent`.

package/dist/templates/shared/verify-triage.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+repo=${2:?GitHub repository required}
+[[ "$issue" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+
+gh issue view "$issue" --repo "$repo" --json state,labels |
+  node -e '
+    const issue = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
+    const labels = new Set(issue.labels.map((label) => label.name));
+    const states = ["needs-triage", "needs-info", "ready-for-agent", "ready-for-human", "wontfix"];
+    if (issue.state !== "OPEN" || !labels.has("shipyard") ||
+        states.filter((state) => labels.has(state)).join() !== "ready-for-agent") {
+      console.error("Issue cannot be implemented: requires an open issue with shipyard and only ready-for-agent as its triage state");
+      process.exit(1);
+    }
+  '

package/dist/templates/simple-loop/block-scope.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=${1:?scope root required}
+failed=${2:?failed issue required}
+repo=${3:?GitHub repository required}
+scope=${4:?scope issue numbers required}
+branch=${5:-shipyard/issue-$root}
+[[ "$root" =~ ^[0-9]+$ && "$failed" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$root" || "$scope" == "$root,"* ) && ",$scope," == *",$failed,"* ]] || {
+  echo "Invalid blocked issue scope" >&2; exit 1;
+}
+[[ "$branch" == "shipyard/issue-$root" || "$branch" == "shipyard/spec-$root" ]] || { echo "Invalid scope branch" >&2; exit 1; }
+reason=$(cat)
+[[ -n "$reason" ]] || { echo "Missing failure reason" >&2; exit 1; }
+reason_hash=$(printf '%s' "$reason" | git hash-object --stdin)
+pending_dir=$(git rev-parse --git-path shipyard-pending)
+mkdir -p "$pending_dir"
+umask 077
+pending_file="$pending_dir/$root-$failed.pending"
+trap 'rm -f "${pending_tmp:-}"' EXIT
+confirmed=""
+if [[ -f "$pending_file" ]]; then
+  IFS=$'\t' read -r old_root old_failed old_repo old_scope old_branch old_confirmed < "$pending_file"
+  if [[ "$old_root" == "$root" && "$old_failed" == "$failed" && "$old_repo" == "$repo" && "$old_scope" == "$scope" && "$old_branch" == "$branch" ]]; then
+    confirmed=${old_confirmed:-}
+  fi
+fi
+write_pending() {
+  pending_tmp=$(mktemp "$pending_file.XXXXXX")
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n%s' "$root" "$failed" "$repo" "$scope" "$branch" "$confirmed" "$reason" > "$pending_tmp"
+  mv "$pending_tmp" "$pending_file"
+}
+confirm_blocked() {
+  if [[ ",$confirmed," != *",$1,"* ]]; then
+    confirmed=${confirmed:+$confirmed,}$1
+    write_pending
+  fi
+}
+write_pending
+
+remove_issue_status() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1" >&2
+    return 75
+  fi
+}
+remove_pr_status() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1" >&2
+    return 75
+  fi
+}
+comment_once() {
+  local comments
+  if comments=$(gh issue view "$1" --repo "$repo" --json comments --jq '.comments[].body'); then
+    if grep -Fq "$3" <<< "$comments"; then return 0; fi
+  fi
+  gh issue comment "$1" --repo "$repo" --body "$2"
+}
+
+gh label create shipyard:blocked --repo "$repo" --color B60205 --description 'Shipyard work needs intervention' --force
+status_synced=true
+IFS=',' read -ra affected_ids <<< "$scope"
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    gh issue edit "$affected_id" --repo "$repo" --add-label shipyard:blocked
+    confirm_blocked "$affected_id"
+  done
+  if ! gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update spec #$root status" >&2
+    status_synced=false
+  fi
+else
+  gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked
+  confirm_blocked "$root"
+fi
+
+status=0
+marker="shipyard:blocked:$root:$failed:$reason_hash"
+comment_once "$failed" "Shipyard could not complete this issue. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:failed -->" "$marker:failed" || status=75
+if [[ "$root" != "$failed" ]]; then
+  comment_once "$root" "Shipyard paused this spec because linked ticket #$failed failed. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to each unfinished ticket.
+
+<!-- $marker:parent -->" "$marker:parent" || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" && "$failed" == "$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    comment_once "$affected_id" "Shipyard could not complete this ticket during the spec attempt. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:ticket:$affected_id -->" "$marker:ticket:$affected_id" || status=75
+  done
+fi
+
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  if ! remove_issue_status "$root" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+  if ! remove_issue_status "$root" shipyard:complete; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+else
+  remove_issue_status "$root" shipyard:outstanding-tasks || status=75
+  remove_issue_status "$root" shipyard:complete || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    remove_issue_status "$affected_id" shipyard:pending || status=75
+  done
+else
+  remove_issue_status "$root" shipyard:pending || status=75
+fi
+
+if ! pr_number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty'); then
+  echo "Warning: could not inspect PR status" >&2
+  status_synced=false
+  pr_number=""
+fi
+if [[ -n "$pr_number" ]]; then
+  if ! gh pr edit "$pr_number" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:complete; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+fi
+if [[ "$status" -eq 0 && "$status_synced" == true ]]; then
+  IFS=',' read -ra scope_ids <<< "$scope"
+  for scope_id in "${scope_ids[@]}"; do
+    labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name')
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard
+    fi
+  done
+  rm -f "$pending_file"
+fi
+exit "$status"

package/dist/templates/simple-loop/handoff.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+branch=${2:?branch required}
+base=${3:?target branch required}
+repo=${4:?GitHub repository required}
+scope=${5:-$issue}
+outstanding=${6:--}
+previously_completed=${7:--}
+[[ "$issue" =~ ^[0-9]+$ && ( "$branch" == "shipyard/issue-$issue" || "$branch" == "shipyard/spec-$issue" ) ]] || {
+  echo "Invalid issue or branch for PR handoff" >&2; exit 1;
+}
+[[ "$base" =~ ^[A-Za-z0-9._/-]+$ ]] || {
+  echo "Invalid target branch for PR handoff" >&2; exit 1;
+}
+
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$issue" || "$scope" == "$issue,"* ) ]] || { echo "Invalid PR scope" >&2; exit 1; }
+[[ "$outstanding" == - || "$outstanding" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid outstanding tickets" >&2; exit 1; }
+[[ "$previously_completed" == - || "$previously_completed" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid completed tickets" >&2; exit 1; }
+evidence=$(cat)
+[[ -n "$evidence" ]] || { echo "Missing verification evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Checks:' <<< "$evidence" || { echo "Missing check evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Review:' <<< "$evidence" || { echo "Missing review evidence" >&2; exit 1; }
+[[ -z $(git status --porcelain) ]] || {
+  echo "Uncommitted changes prevent PR handoff" >&2; exit 1;
+}
+base_ref=$(git rev-parse --verify "refs/remotes/origin/$base^{commit}") || {
+  echo "Target branch is unavailable in the sandbox" >&2; exit 1;
+}
+branch_base=$base_ref
+if ! git merge-base --is-ancestor "$base_ref" HEAD; then
+  branch_base=$(git merge-base "$base_ref" HEAD) || {
+    echo "PR branch has no common base with the target branch" >&2; exit 1;
+  }
+fi
+[[ -n $(git log "$branch_base"..HEAD --format=%H) ]] || {
+  echo "No verified commit to publish" >&2; exit 1;
+}
+
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+remove_issue_label() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+remove_pr_label() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+title=$(gh issue view "$issue" --repo "$repo" --json title --jq .title)
+body=$(mktemp)
+trap 'rm -f "$body"' EXIT
+links=""
+implemented=""
+IFS=',' read -ra scope_ids <<< "$scope"
+for scope_id in "${scope_ids[@]}"; do links+="#$scope_id "; done
+for ((i=1; i<${#scope_ids[@]}; i++)); do implemented+="#${scope_ids[i]} "; done
+if [[ "$previously_completed" != - ]]; then
+  IFS=',' read -ra completed_ids <<< "$previously_completed"
+  for completed_id in "${completed_ids[@]}"; do links+="#$completed_id "; implemented+="#$completed_id "; done
+fi
+if [[ "$outstanding" != - ]]; then
+  IFS=',' read -ra outstanding_ids <<< "$outstanding"
+  for outstanding_id in "${outstanding_ids[@]}"; do links+="#$outstanding_id "; done
+fi
+printf 'Source issues: %s\nImplemented tickets: %s\n\n## Verification and review\n\n%s\n\nHuman review and merge required.\n\n<!-- shipyard:verified-handoff -->\n' "$links" "$implemented" "$evidence" > "$body"
+
+# Keep Git credentials inside the disposable sandbox, not in the host worktree.
+git remote set-url origin "https://github.com/$repo.git"
+git -c credential.helper='!gh auth git-credential' push -u origin "HEAD:refs/heads/$branch"
+number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+if [[ -z "$number" ]]; then
+  gh pr create --repo "$repo" --head "$branch" --base "$base" --title "$title" --body-file "$body" --draft
+  number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+fi
+[[ -n "$number" ]] || { echo "PR publication did not return an open PR" >&2; exit 1; }
+gh pr edit "$number" --repo "$repo" --body-file "$body"
+draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft)
+url=$(gh pr view "$number" --repo "$repo" --json url --jq .url)
+[[ -n "$url" ]] || { echo "PR publication did not return a URL" >&2; exit 1; }
+if [[ "$draft" == true ]]; then gh pr ready "$number" --repo "$repo" || true; fi
+if ! current_draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft) ||
+   ! current_state=$(gh pr view "$number" --repo "$repo" --json state --jq .state); then
+  echo "Could not confirm PR readiness; retry publication when GitHub is available" >&2
+  exit 75
+fi
+if [[ "$current_draft" != false || "$current_state" != OPEN ]]; then
+  echo "PR did not become ready for human review" >&2
+  exit 1
+fi
+for ((i=1; i<${#scope_ids[@]}; i++)); do
+  if ! gh issue edit "${scope_ids[i]}" --repo "$repo" --add-label shipyard:complete; then
+    echo "Could not mark ticket #${scope_ids[i]} complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  remove_issue_label "${scope_ids[i]}" shipyard:blocked
+  remove_issue_label "${scope_ids[i]}" shipyard:pending
+done
+status_label=shipyard:complete
+status_color=0E8A16
+status_description='Shipyard work ready for human review'
+if [[ "$outstanding" != - ]]; then
+  status_label=shipyard:outstanding-tasks
+  status_color=FBCA04
+  status_description='Spec has uncompleted tickets'
+  for outstanding_id in "${outstanding_ids[@]}"; do
+    labels=$(gh issue view "$outstanding_id" --repo "$repo" --json labels --jq '.labels[].name') || exit 75
+    if grep -Fxq shipyard:blocked <<< "$labels" && ! grep -Fxq shipyard:complete <<< "$labels"; then
+      status_label=shipyard:blocked
+      status_color=B60205
+      status_description='Shipyard work needs intervention'
+      break
+    fi
+  done
+fi
+status_synced=true
+if ! gh label create "$status_label" --repo "$repo" --color "$status_color" --description "$status_description" --force; then
+  echo "Warning: could not create $status_label" >&2
+  status_synced=false
+fi
+if ! gh issue edit "$issue" --repo "$repo" --add-label "$status_label"; then
+  if [[ "$branch" == "shipyard/issue-$issue" ]]; then
+    echo "Could not mark ticket #$issue complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  echo "Warning: could not update spec #$issue status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_issue_label "$issue" "$stale_label"; then
+      if [[ "$branch" == "shipyard/issue-$issue" ]]; then exit 75; fi
+      echo "Warning: could not clear $stale_label from spec #$issue" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$branch" == "shipyard/issue-$issue" ]]; then remove_issue_label "$issue" shipyard:pending; fi
+if ! gh pr edit "$number" --repo "$repo" --add-label "$status_label"; then
+  echo "Warning: could not update PR #$number status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_pr_label "$number" "$stale_label"; then
+      echo "Warning: could not clear $stale_label from PR #$number" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$status_synced" == true ]]; then
+  for scope_id in "${scope_ids[@]}"; do
+    if ! labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name'); then
+      echo "Warning: could not inspect activation on issue #$scope_id; the next invocation will retry cleanup" >&2
+      continue
+    fi
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard ||
+        echo "Warning: could not remove activation from issue #$scope_id; the next invocation will retry cleanup" >&2
+    fi
+  done
+else
+  echo "Warning: status labels need reconciliation; retaining ticket activation" >&2
+fi
+printf '%s\n' "$url"

package/dist/templates/simple-loop/main.mts

@@ -1,51 +1,196 @@
-import { CODEX_MODELS, run, codex } from "@snappedly-tools/shipyard";
+// Simple loop: select one activated issue scope per iteration, implement it,
+// then hand its verified commit to a human through a pull request.
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import * as shipyard from "@snappedly-tools/shipyard";
 import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
 
-// Simple loop: an agent that picks open issues one by one and closes them.
-// Generated entrypoint: .shipyard/main.mts
-// Run this with: npx shipyard run
-// Or add to package.json scripts: "shipyard": "shipyard run"
-
-await run({
-  // A name for this run, shown as a prefix in log output.
-  name: "worker",
-
-  // Sandbox provider — runs the agent inside an isolated container.
-  sandbox: docker(),
-
-  // The agent provider. The routine configured Codex model runs at max
-  // reasoning by default. Switch to CODEX_MODELS.strong for more demanding
-  // planning or review work.
-  agent: codex(CODEX_MODELS.routine),
-
-  // Path to the prompt file. Shell expressions inside are evaluated inside the
-  // sandbox at the start of each iteration, so the agent always sees fresh data.
-  promptFile: "./.shipyard/prompt.md",
+if (process.loadEnvFile && existsSync(".shipyard/.env"))
+  process.loadEnvFile(".shipyard/.env");
+const targetBranch = execFileSync("git", ["branch", "--show-current"], {
+  encoding: "utf8",
+}).trim();
+const repository = execFileSync(
+  "gh",
+  ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+  { encoding: "utf8" },
+).trim();
+if (
+  !/^[A-Za-z0-9._/-]+$/.test(targetBranch) ||
+  !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)
+) {
+  throw new Error("Invalid target branch or GitHub repository");
+}
+process.env.GH_REPO = repository;
+const hooks = {
+  sandbox: {
+    onSandboxReady: [
+      { command: "timeout 300 bash .shipyard/setup.sh", timeoutMs: 300_000 },
+    ],
+  },
+};
+const closeClean = async (sandbox: {
+  close: () => Promise<{ preservedWorktreePath?: string }>;
+}) => {
+  const { preservedWorktreePath } = await sandbox.close();
+  if (preservedWorktreePath)
+    throw new Error(`Sandbox has uncommitted work at ${preservedWorktreePath}`);
+};
+const verifyTriage = (ticketId: string) => {
+  try {
+    execFileSync("bash", [".shipyard/verify-triage.sh", ticketId, repository], {
+      encoding: "utf8",
+    });
+  } catch (error) {
+    const detail = (error as { stderr?: string | Buffer }).stderr
+      ?.toString()
+      .trim();
+    throw new Error(detail || `Could not verify triage for #${ticketId}`);
+  }
+};
 
-  // Maximum number of iterations (agent invocations) to run in a session.
-  // Each iteration works on a single issue. Increase this to process more issues
-  // per run, or set it to 1 for a single-shot mode.
-  maxIterations: 3,
+const blockScope = (
+  scope: { id: string; branch: string; tickets?: Array<{ id: string }> },
+  error: unknown,
+) => {
+  const reason = (error instanceof Error ? error.message : String(error)).slice(
+    0,
+    3000,
+  );
+  execFileSync(
+    "bash",
+    [
+      ".shipyard/block-scope.sh",
+      scope.id,
+      scope.id,
+      repository,
+      [scope.id, ...(scope.tickets ?? []).map((ticket) => ticket.id)].join(","),
+      scope.branch,
+    ],
+    { input: reason, encoding: "utf8" },
+  );
+  console.error(`Shipyard blocked issue #${scope.id}: ${reason}`);
+};
 
-  // Branch strategy — merge-to-head creates a temporary branch for the agent
-  // to work on, then merges the result back to HEAD when the run completes.
-  // This is required when using copyToWorktree, since head mode bind-mounts
-  // the host directory directly (no worktree to copy into).
-  branchStrategy: { type: "merge-to-head" },
+for (let iteration = 0; iteration < 3; iteration++) {
+  const issues = JSON.parse(
+    execFileSync("node", [".shipyard/select-issues.mjs"], { encoding: "utf8" }),
+  ) as Array<{
+    id: string;
+    title: string;
+    branch: string;
+    kind: "standalone" | "spec";
+    body?: string;
+    tickets?: Array<{
+      id: string;
+      title: string;
+      body: string;
+      state: string;
+      blockedBy: Array<{ id: string; title: string; state: string }>;
+    }>;
+    completedTicketIds?: string[];
+    outstandingTicketIds?: string[];
+  }>;
+  const issue = issues[0];
+  if (!issue) break;
 
-  // Copy node_modules from the host into the worktree before the sandbox
-  // starts. This avoids a full npm install from scratch on every iteration.
-  // The onSandboxReady hook still runs npm install as a safety net to handle
-  // platform-specific binaries and any packages added since the last copy.
-  copyToWorktree: ["node_modules"],
+  let handedOff = false;
+  let publicationUncertain = false;
+  try {
+    execFileSync("gh", [
+      "label",
+      "create",
+      "shipyard:pending",
+      "--repo",
+      repository,
+      "--color",
+      "1D76DB",
+      "--description",
+      "Shipyard is working on this ticket",
+      "--force",
+    ]);
+    for (const ticketId of issue.kind === "spec"
+      ? (issue.tickets ?? []).map((ticket) => ticket.id)
+      : [issue.id])
+      execFileSync("gh", [
+        "issue",
+        "edit",
+        ticketId,
+        "--repo",
+        repository,
+        "--add-label",
+        "shipyard:pending",
+      ]);
+    const sandbox = await shipyard.createSandbox({
+      branch: issue.branch,
+      sandbox: docker(),
+      hooks,
+    });
+    let evidence: string;
+    try {
+      for (const ticketId of issue.kind === "spec"
+        ? (issue.tickets ?? []).map((ticket) => ticket.id)
+        : [issue.id]) {
+        await sandbox.run({
+          name: `triage #${ticketId}`,
+          agent: shipyard.codex(shipyard.CODEX_MODELS.strong),
+          maxIterations: 1,
+          promptFile: "./.shipyard/triage-prompt.md",
+          promptArgs: { TASK_ID: ticketId },
+        });
+        verifyTriage(ticketId);
+      }
+      const result = await sandbox.run({
+        name: "implementer",
+        agent: shipyard.codex(shipyard.CODEX_MODELS.routine),
+        maxIterations: 1,
+        promptFile: "./.shipyard/prompt.md",
+        promptArgs: {
+          TASK_ID: issue.id,
+          ISSUE_TITLE: issue.title,
+          BRANCH: issue.branch,
+          SCOPE: JSON.stringify(issue),
+          SKILL: issue.kind === "spec" ? "/implement-spec" : "/implement",
+        },
+      });
+      const packet = [
+        ...result.stdout.matchAll(/<handoff>([\s\S]*?)<\/handoff>/g),
+      ]
+        .at(-1)?.[1]
+        ?.trim();
+      if (!result.completionSignal || !packet)
+        throw new Error(
+          `Issue #${issue.id} has no verified completion evidence: ${result.stdout.trim().slice(-1200)}`,
+        );
+      evidence = packet;
+    } finally {
+      await closeClean(sandbox);
+    }
 
-  // Lifecycle hooks — commands grouped by where they run (host or sandbox).
-  hooks: {
-    sandbox: {
-      // onSandboxReady runs once after the sandbox is initialised and the repo is
-      // synced in, before the agent starts. Use it to install dependencies or run
-      // any other setup steps your project needs.
-      onSandboxReady: [{ command: "npm install" }],
-    },
-  },
-});
+    // Sync-out rewrites sandbox commits on the host. Publish from the synced
+    // branch so a later invocation can fast-forward the same PR.
+    const publication = await shipyard.createSandbox({
+      branch: issue.branch,
+      sandbox: docker(),
+    });
+    try {
+      publicationUncertain = true;
+      const handoff = await publication.exec(
+        `bash .shipyard/handoff.sh ${issue.id} ${issue.branch} ${targetBranch} ${repository} ${[issue.id, ...(issue.tickets ?? []).map((ticket) => ticket.id)].join(",")} ${issue.outstandingTicketIds?.join(",") || "-"} ${issue.completedTicketIds?.join(",") || "-"}`,
+        { stdin: evidence },
+      );
+      publicationUncertain = handoff.exitCode === 75;
+      if (handoff.exitCode !== 0)
+        throw new Error(
+          `PR handoff for #${issue.id} failed: ${handoff.stderr || handoff.stdout}`,
+        );
+      console.log(handoff.stdout.trim());
+      handedOff = true;
+    } finally {
+      await publication.close();
+    }
+  } catch (error) {
+    if (handedOff || publicationUncertain) throw error;
+    blockScope(issue, error);
+  }
+}