agent-control-plane 0.3.0 → 0.6.0

package/references/repo-map.md

@@ -1,36 +0,0 @@
-# Repository Map
-
-This file maps the `agent-control-plane` repository itself.
-
-## Core Layout
-
-- `SKILL.md`
-  Shared operating manual for the control plane.
-- `assets/`
-  Workflow catalog and static non-profile assets.
-- `bin/`
-  Queue, label, and risk scripts shared by installed profiles.
-- `hooks/`
-  Heartbeat and reconcile hooks shared by installed profiles.
-- `tools/bin/`
-  Runtime wrappers, onboarding helpers, publication utilities, and doctor tools.
-- `tools/templates/`
-  Generic fallback prompts used when a profile does not override a template.
-- `tools/tests/`
-  Shell regression coverage for control-plane behavior.
-- `references/`
-  Control-plane docs, operator commands, and repository maps.
-
-## Operator Surfaces
-
-- `tools/bin/render-flow-config.sh`
-  Effective config viewer for the selected profile.
-- `tools/bin/profile-smoke.sh`
-  Installed-profile validation and collision detection.
-- `tools/bin/profile-adopt.sh`
-  Local runtime/bootstrap helper for onboarding a profile onto a workstation.
-- `tools/bin/sync-shared-agent-home.sh`
-  Publication repair for shared/runtime copies.
-
-Installed profiles live outside this repo under
-`~/.agent-runtime/control-plane/profiles/<id>/`.

package/tools/bin/agent-cleanup-worktree

@@ -1,247 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage:
-  agent-cleanup-worktree --branch <branch-name> [--merged-base <ref>] [--path <worktree-path>] [--remote <name>] [--keep-remote] [--allow-unmerged] [--dry-run]
-
-Safely cleans up a dedicated task branch/worktree:
-  - optionally prunes remote refs
-  - by default verifies the branch is merged into the base ref
-  - removes the dedicated worktree
-  - deletes the local branch
-  - deletes the remote branch if it still exists unless --keep-remote is set
-
-Run this from a retained checkout, not from the task worktree being removed.
-EOF
-}
-
-branch_name=""
-merged_base=""
-worktree_path=""
-remote_name="origin"
-keep_remote="false"
-allow_unmerged="false"
-dry_run="false"
-branch_delete_flag="-d"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --branch) branch_name="${2:-}"; shift 2 ;;
-    --merged-base) merged_base="${2:-}"; shift 2 ;;
-    --path) worktree_path="${2:-}"; shift 2 ;;
-    --remote) remote_name="${2:-}"; shift 2 ;;
-    --keep-remote) keep_remote="true"; shift ;;
-    --allow-unmerged) allow_unmerged="true"; shift ;;
-    --dry-run) dry_run="true"; shift ;;
-    --help|-h) usage; exit 0 ;;
-    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
-  esac
-done
-
-if [[ -z "$branch_name" ]]; then
-  echo "--branch is required" >&2
-  usage >&2
-  exit 1
-fi
-
-if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
-  echo "[agent-cleanup] Refusing to clean up protected branch: $branch_name" >&2
-  exit 1
-fi
-
-repo_root="$(git rev-parse --show-toplevel)"
-git_common_dir="$(cd "$(git rev-parse --git-common-dir)" && pwd)"
-source_root="$(dirname "$git_common_dir")"
-current_branch="$(git rev-parse --abbrev-ref HEAD)"
-current_worktree_root="$repo_root"
-local_branch_exists="false"
-remote_branch_exists="false"
-
-if [[ -z "$merged_base" ]]; then
-  remote_head="$(git symbolic-ref --quiet --short refs/remotes/${remote_name}/HEAD 2>/dev/null || true)"
-  if [[ -n "$remote_head" ]]; then
-    merged_base="${remote_head#${remote_name}/}"
-    merged_base="${remote_name}/${merged_base}"
-  elif git show-ref --verify --quiet "refs/remotes/${remote_name}/main"; then
-    merged_base="${remote_name}/main"
-  elif git show-ref --verify --quiet "refs/heads/main"; then
-    merged_base="main"
-  else
-    merged_base="HEAD"
-  fi
-fi
-
-canonicalize_existing_dir() {
-  local target="$1"
-  if [[ ! -d "$target" ]]; then
-    return 1
-  fi
-  (
-    cd "$target"
-    pwd -P
-  )
-}
-
-prune_worktree_runtime_artifacts() {
-  local target="${1:?target worktree required}"
-  local candidate=""
-  local -a paths=(
-    "$target/.openclaw-artifacts"
-    "$target/node_modules"
-    "$target/apps/api/node_modules"
-    "$target/apps/mobile/node_modules"
-    "$target/apps/web/node_modules"
-  )
-
-  if [[ -d "$target/packages" ]]; then
-    while IFS= read -r candidate; do
-      paths+=("$candidate")
-    done < <(find "$target/packages" -mindepth 2 -maxdepth 2 -type d -name node_modules | sort)
-  fi
-
-  for candidate in "${paths[@]}"; do
-    [[ -e "$candidate" ]] || continue
-    rm -rf "$candidate"
-  done
-}
-
-resolve_branch_worktree_path() {
-  local line=""
-  local worktree=""
-  local branch=""
-  local ref="refs/heads/${branch_name}"
-  while IFS= read -r line || [[ -n "$line" ]]; do
-    if [[ -z "$line" ]]; then
-      if [[ "$branch" == "$ref" ]]; then
-        printf '%s\n' "$worktree"
-        return 0
-      fi
-      worktree=""
-      branch=""
-      continue
-    fi
-    case "$line" in
-      worktree\ *) worktree="${line#worktree }" ;;
-      branch\ *) branch="${line#branch }" ;;
-    esac
-  done < <(git worktree list --porcelain)
-  if [[ "$branch" == "$ref" ]]; then
-    printf '%s\n' "$worktree"
-  fi
-}
-
-if [[ "$current_branch" == "$branch_name" ]]; then
-  echo "[agent-cleanup] Refusing to clean up the branch currently checked out: $branch_name" >&2
-  exit 1
-fi
-
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  local_branch_exists="true"
-fi
-
-resolved_branch_worktree_path=""
-if [[ -z "$worktree_path" ]]; then
-  worktree_path="$(resolve_branch_worktree_path || true)"
-  resolved_branch_worktree_path="$worktree_path"
-else
-  resolved_branch_worktree_path="$(resolve_branch_worktree_path || true)"
-  if [[ -z "$resolved_branch_worktree_path" ]]; then
-    echo "[agent-cleanup] Branch $branch_name is not associated with a dedicated worktree." >&2
-    echo "[agent-cleanup] Refusing to trust explicit --path '$worktree_path' without a Git-resolved branch worktree." >&2
-    exit 1
-  fi
-
-  explicit_canonical_path="$(canonicalize_existing_dir "$worktree_path" || true)"
-  branch_canonical_path="$(canonicalize_existing_dir "$resolved_branch_worktree_path" || true)"
-  if [[ -z "$explicit_canonical_path" ]]; then
-    echo "[agent-cleanup] Explicit --path '$worktree_path' does not exist as a directory." >&2
-    exit 1
-  fi
-  if [[ -z "$branch_canonical_path" ]]; then
-    echo "[agent-cleanup] Git resolved branch worktree '$resolved_branch_worktree_path' does not exist as a directory." >&2
-    exit 1
-  fi
-  if [[ "$explicit_canonical_path" != "$branch_canonical_path" ]]; then
-    echo "[agent-cleanup] Explicit --path '$worktree_path' does not match the worktree Git associates with branch '$branch_name' ('$resolved_branch_worktree_path')." >&2
-    exit 1
-  fi
-  worktree_path="$branch_canonical_path"
-fi
-
-if [[ "$dry_run" != "true" && "$remote_name" != "" ]]; then
-  git fetch --prune "$remote_name"
-fi
-
-if git show-ref --verify --quiet "refs/remotes/${remote_name}/${branch_name}"; then
-  remote_branch_exists="true"
-fi
-
-if [[ "$allow_unmerged" != "true" && "$local_branch_exists" == "true" ]]; then
-  if ! git merge-base --is-ancestor "$branch_name" "$merged_base"; then
-    echo "[agent-cleanup] Branch $branch_name is not merged into $merged_base" >&2
-    exit 1
-  fi
-fi
-
-if [[ "$allow_unmerged" == "true" ]]; then
-  branch_delete_flag="-D"
-fi
-
-if [[ -n "$worktree_path" && "$worktree_path" == "$current_worktree_root" ]]; then
-  echo "[agent-cleanup] Refusing to remove the current worktree: $worktree_path" >&2
-  exit 1
-fi
-
-if [[ -n "$worktree_path" ]]; then
-  canonical_worktree_path="$(canonicalize_existing_dir "$worktree_path" || true)"
-  if [[ -n "$canonical_worktree_path" && "$canonical_worktree_path" == "$source_root" ]]; then
-    echo "[agent-cleanup] Refusing to remove the canonical source checkout: $canonical_worktree_path" >&2
-    exit 1
-  fi
-fi
-
-if [[ "$dry_run" == "true" ]]; then
-  if [[ -n "$worktree_path" ]]; then
-    echo "git worktree remove --force '$worktree_path'"
-  fi
-  if [[ "$local_branch_exists" == "true" ]]; then
-    echo "git branch $branch_delete_flag '$branch_name'"
-  fi
-  if [[ "$remote_branch_exists" == "true" && "$keep_remote" != "true" ]]; then
-    echo "git push '$remote_name' --delete '$branch_name'"
-  fi
-  if [[ "$remote_name" != "" ]]; then
-    echo "git fetch --prune '$remote_name'"
-  fi
-  exit 0
-fi
-
-if [[ -n "$worktree_path" ]]; then
-  prune_worktree_runtime_artifacts "$worktree_path"
-  (
-    cd "$source_root"
-    git worktree remove --force "$worktree_path"
-  )
-fi
-if [[ "$local_branch_exists" == "true" ]]; then
-  git branch "$branch_delete_flag" "$branch_name"
-fi
-if [[ "$remote_branch_exists" == "true" && "$keep_remote" != "true" ]]; then
-  remote_delete_output="$(git push "$remote_name" --delete "$branch_name" 2>&1)" || remote_delete_status=$?
-  remote_delete_status="${remote_delete_status:-0}"
-  if [[ "$remote_delete_status" -ne 0 ]]; then
-    if rg -q "remote ref does not exist|unable to delete" <<<"$remote_delete_output"; then
-      :
-    else
-      printf '%s\n' "$remote_delete_output" >&2
-      exit "$remote_delete_status"
-    fi
-  fi
-fi
-if [[ "$remote_name" != "" ]]; then
-  git fetch --prune "$remote_name"
-fi
-
-echo "[agent-cleanup] cleanup complete for $branch_name"

package/tools/bin/agent-github-update-labels

@@ -1,71 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=/dev/null
-source "${SCRIPT_DIR}/flow-config-lib.sh"
-
-usage() {
-  cat <<'EOF'
-Usage:
-  agent-github-update-labels --repo-slug <owner/repo> --number <issue-or-pr-number> [--add LABEL]... [--remove LABEL]...
-
-Merge requested label adds/removals into the current issue/PR labels and patch
-the final sorted label set back to GitHub.
-EOF
-}
-
-repo_slug=""
-number=""
-add_file="$(mktemp)"
-remove_file="$(mktemp)"
-trap 'rm -f "$add_file" "$remove_file"' EXIT
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --repo-slug) repo_slug="${2:-}"; shift 2 ;;
-    --number) number="${2:-}"; shift 2 ;;
-    --add)
-      printf '%s\n' "${2:?missing label after --add}" >>"$add_file"
-      shift 2
-      ;;
-    --remove)
-      printf '%s\n' "${2:?missing label after --remove}" >>"$remove_file"
-      shift 2
-      ;;
-    --help|-h) usage; exit 0 ;;
-    *)
-      echo "unknown argument: $1" >&2
-      usage >&2
-      exit 1
-      ;;
-  esac
-done
-
-if [[ -z "$repo_slug" || -z "$number" ]]; then
-  usage >&2
-  exit 1
-fi
-
-resource="issues/${number}"
-# Use caller-provided cached JSON if available to skip the GET call
-if [[ -n "${ACP_CACHED_ISSUE_JSON:-}" ]]; then
-  current_json="${ACP_CACHED_ISSUE_JSON}"
-else
-  current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"
-fi
-add_json="$(jq -R . <"$add_file" | jq -s .)"
-remove_json="$(jq -R . <"$remove_file" | jq -s .)"
-payload="$(
-  CURRENT_JSON="$current_json" ADD_JSON="$add_json" REMOVE_JSON="$remove_json" node <<'EOF'
-const current = JSON.parse(process.env.CURRENT_JSON || '{}');
-const add = JSON.parse(process.env.ADD_JSON || '[]');
-const remove = new Set(JSON.parse(process.env.REMOVE_JSON || '[]'));
-const labels = new Set((current.labels || []).map((label) => label.name));
-for (const label of remove) labels.delete(label);
-for (const label of add) labels.add(label);
-process.stdout.write(JSON.stringify({ labels: Array.from(labels).sort() }));
-EOF
-)"
-
-printf '%s' "$payload" | flow_github_api_repo "${repo_slug}" "${resource}" --method PATCH --input - >/dev/null

package/tools/bin/agent-init-worktree

@@ -1,216 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage:
-  agent-init-worktree --branch <branch-name> --claim <task-id> [--base <ref>] [--path <worktree-path>] [--allow-unclaimed] [--no-bootstrap-deps] [--dry-run]
-
-Creates a dedicated agent branch + worktree and writes a namespaced env file:
-  .agent-session.env
-
-Options:
-  --branch <name>      Required branch name for the task
-  --base <ref>         Base ref for a new branch (default: remote HEAD, else origin/main, else main, else HEAD)
-  --path <path>        Explicit worktree path
-  --claim <task-id>    Required shared task claim, e.g. change-id:2.1
-  --allow-unclaimed    Explicitly allow bootstrap without a claim
-  --no-bootstrap-deps  Skip node_modules linking for the new worktree
-  --dry-run            Print actions without creating anything
-  --help               Show this help
-EOF
-}
-
-branch_name=""
-base_ref=""
-worktree_path=""
-claim_task_id=""
-bootstrap_deps="true"
-allow_unclaimed="false"
-dry_run="false"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --branch) branch_name="${2:-}"; shift 2 ;;
-    --base) base_ref="${2:-}"; shift 2 ;;
-    --path) worktree_path="${2:-}"; shift 2 ;;
-    --claim) claim_task_id="${2:-}"; shift 2 ;;
-    --allow-unclaimed) allow_unclaimed="true"; shift ;;
-    --no-bootstrap-deps) bootstrap_deps="false"; shift ;;
-    --dry-run) dry_run="true"; shift ;;
-    --help|-h) usage; exit 0 ;;
-    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
-  esac
-done
-
-if [[ -z "$branch_name" ]]; then
-  echo "--branch is required" >&2
-  usage >&2
-  exit 1
-fi
-
-if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
-  echo "[agent-init] Refusing to bootstrap protected branch: $branch_name" >&2
-  echo "[agent-init] Keep the retained checkout on $branch_name read-only for inspection only." >&2
-  echo "[agent-init] Create a dedicated task branch/worktree before doing any write work." >&2
-  exit 1
-fi
-
-if [[ -z "$claim_task_id" && "$allow_unclaimed" != "true" ]]; then
-  echo "--claim is required for agent task worktrees. Use --allow-unclaimed only for exceptional preserve/review cases." >&2
-  usage >&2
-  exit 1
-fi
-
-if [[ -z "$base_ref" ]]; then
-  remote_name="origin"
-  remote_head="$(git symbolic-ref --quiet --short "refs/remotes/${remote_name}/HEAD" 2>/dev/null || true)"
-  if [[ -n "$remote_head" ]]; then
-    base_ref="${remote_head}"
-  elif git show-ref --verify --quiet "refs/remotes/${remote_name}/main"; then
-    base_ref="${remote_name}/main"
-  elif git show-ref --verify --quiet "refs/heads/main"; then
-    base_ref="main"
-  else
-    base_ref="HEAD"
-  fi
-fi
-
-repo_root="$(git rev-parse --show-toplevel)"
-git_common_dir="$(cd "$(git rev-parse --git-common-dir)" && pwd)"
-source_root="$(dirname "$git_common_dir")"
-repo_name="$(basename "$source_root")"
-repo_parent="$(dirname "$source_root")"
-
-branch_slug="$(
-  printf '%s' "$branch_name" |
-    tr '[:upper:]' '[:lower:]' |
-    sed 's#[^a-z0-9._/-]#-#g; s#/#-#g; s/-\{2,\}/-/g; s/^-//; s/-$//'
-)"
-
-if [[ -z "$branch_slug" ]]; then
-  echo "Failed to derive branch slug from: $branch_name" >&2
-  exit 1
-fi
-
-if [[ -z "$worktree_path" ]]; then
-  worktree_path="${repo_parent}/${repo_name}-${branch_slug}"
-fi
-
-namespace="$(
-  printf '%s' "$branch_slug" |
-    sed 's/[^a-z0-9]/-/g; s/-\{2,\}/-/g; s/^-//; s/-$//' |
-    cut -c1-24
-)"
-
-if [[ -z "$namespace" ]]; then
-  namespace="agent-local"
-fi
-
-run_id_raw="${AO_SESSION_ID:-${branch_slug}-$$}"
-env_file="${worktree_path}/.agent-session.env"
-
-branch_exists="false"
-if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
-  branch_exists="true"
-fi
-
-if [[ -e "$worktree_path" ]]; then
-  echo "Worktree path already exists: $worktree_path" >&2
-  exit 1
-fi
-
-cat <<EOF
-[agent-init] repo=$repo_root
-[agent-init] source_root=$source_root
-[agent-init] branch=$branch_name
-[agent-init] base_ref=$base_ref
-[agent-init] worktree_path=$worktree_path
-[agent-init] test_namespace=$namespace
-[agent-init] branch_exists=$branch_exists
-[agent-init] bootstrap_deps=$bootstrap_deps
-[agent-init] claim_task_id=${claim_task_id:-<none>}
-[agent-init] allow_unclaimed=$allow_unclaimed
-EOF
-
-if [[ "$dry_run" == "true" ]]; then
-  echo "[agent-init] dry-run only"
-  echo
-  echo "Planned commands:"
-  if [[ "$branch_exists" == "false" ]]; then
-    echo "  git worktree add -b $branch_name $worktree_path $base_ref"
-  else
-    echo "  git worktree add $worktree_path $branch_name"
-  fi
-  cat <<EOF
-
-Planned env file: $env_file
-  export AGENT_TASK_BRANCH='$branch_name'
-  export AGENT_WORKTREE_PATH='$worktree_path'
-  export TEST_RUN_ID='$run_id_raw'
-  export API_TEST_RUN_ID='$run_id_raw'
-  export TEST_SEED_NAMESPACE='$namespace'
-  export E2E_SEED_NAMESPACE='$namespace'
-  export MOBILE_SEED_NAMESPACE='$namespace'
-EOF
-  if [[ "$bootstrap_deps" == "true" ]]; then
-    echo "  agent-bootstrap-worktree --source-root '$source_root' --path '$worktree_path'"
-  fi
-  if [[ -n "$claim_task_id" ]]; then
-    echo "  agent-claim-task --task '$claim_task_id' --branch '$branch_name' --worktree '$worktree_path'"
-  fi
-  exit 0
-fi
-
-if [[ "$branch_exists" == "true" ]]; then
-  git worktree add "$worktree_path" "$branch_name"
-else
-  git worktree add -b "$branch_name" "$worktree_path" "$base_ref"
-fi
-
-cat >"$env_file" <<EOF
-export AGENT_TASK_BRANCH='$branch_name'
-export AGENT_WORKTREE_PATH='$worktree_path'
-export TEST_RUN_ID='$run_id_raw'
-export API_TEST_RUN_ID='$run_id_raw'
-export TEST_SEED_NAMESPACE='$namespace'
-export E2E_SEED_NAMESPACE='$namespace'
-export MOBILE_SEED_NAMESPACE='$namespace'
-EOF
-
-if [[ -n "$claim_task_id" ]]; then
-  printf "export AGENT_TASK_CLAIM='%s'\n" "$claim_task_id" >>"$env_file"
-fi
-
-if [[ "$bootstrap_deps" == "true" ]]; then
-  agent-bootstrap-worktree \
-    --source-root "$source_root" \
-    --path "$worktree_path"
-fi
-
-if [[ -n "$claim_task_id" ]]; then
-  agent-claim-task \
-    --task "$claim_task_id" \
-    --branch "$branch_name" \
-    --worktree "$worktree_path"
-fi
-
-if [[ -f "$HOME/.ao/bin/ao-metadata-helper.sh" ]]; then
-  # shellcheck source=/dev/null
-  source "$HOME/.ao/bin/ao-metadata-helper.sh" || true
-  if declare -F update_ao_metadata >/dev/null 2>&1; then
-    update_ao_metadata branch "$branch_name" || true
-    update_ao_metadata worktree "$worktree_path" || true
-    update_ao_metadata test_seed_namespace "$namespace" || true
-  fi
-fi
-
-cat <<EOF
-[agent-init] created worktree: $worktree_path
-[agent-init] wrote env file: $env_file
-$(if [[ -n "$claim_task_id" ]]; then printf "[agent-init] claimed task: %s\n" "$claim_task_id"; fi)
-
-Next:
-  cd '$worktree_path'
-  source .agent-session.env
-EOF

package/tools/bin/agent-project-archive-run

@@ -1,52 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage:
-  agent-project-archive-run --runs-root <path> --history-root <path> --session <id> [--remove-file <path>]
-
-Moves a completed run directory into the history root and optionally removes an
-extra file such as a sandbox result file.
-EOF
-}
-
-runs_root="${AGENT_PROJECT_RUNS_ROOT:-}"
-history_root="${AGENT_PROJECT_HISTORY_ROOT:-}"
-session=""
-remove_file=""
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --runs-root) runs_root="${2:-}"; shift 2 ;;
-    --history-root) history_root="${2:-}"; shift 2 ;;
-    --session) session="${2:-}"; shift 2 ;;
-    --remove-file) remove_file="${2:-}"; shift 2 ;;
-    --help|-h) usage; exit 0 ;;
-    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
-  esac
-done
-
-if [[ -z "$runs_root" || -z "$history_root" || -z "$session" ]]; then
-  usage >&2
-  exit 1
-fi
-
-run_dir="${runs_root}/${session}"
-archived_dir=""
-
-mkdir -p "$history_root"
-
-if [[ -d "$run_dir" && "$run_dir" == "${runs_root}/"* ]]; then
-  archived_dir="${history_root}/${session}-$(date +%Y%m%d-%H%M%S)"
-  mv "$run_dir" "$archived_dir"
-fi
-
-if [[ -n "$remove_file" && -f "$remove_file" ]]; then
-  rm -f "$remove_file"
-fi
-
-printf 'SESSION=%s\n' "$session"
-printf 'RUN_DIR=%s\n' "$run_dir"
-printf 'ARCHIVED_DIR=%s\n' "$archived_dir"
-printf 'REMOVED_FILE=%s\n' "$remove_file"

package/tools/bin/agent-project-capture-worker

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<'EOF'
-Usage:
-  agent-project-capture-worker --runs-root <path> --session <id> [--lines <n>]
-
-Print the latest worker transcript, preferring a live tmux session and falling
-back to the persisted run log.
-EOF
-}
-
-runs_root="${AGENT_PROJECT_RUNS_ROOT:-}"
-session=""
-lines="80"
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --runs-root) runs_root="${2:-}"; shift 2 ;;
-    --session) session="${2:-}"; shift 2 ;;
-    --lines) lines="${2:-}"; shift 2 ;;
-    --help|-h) usage; exit 0 ;;
-    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
-  esac
-done
-
-if [[ -z "$runs_root" || -z "$session" ]]; then
-  usage >&2
-  exit 1
-fi
-
-output_file="${runs_root}/${session}/${session}.log"
-
-if tmux has-session -t "$session" 2>/dev/null; then
-  tmux capture-pane -t "$session" -p | tail -n "$lines"
-  exit 0
-fi
-
-if [[ -f "$output_file" ]]; then
-  tail -n "$lines" "$output_file"
-  exit 0
-fi
-
-echo "no tmux session or log found for $session" >&2
-exit 1