agent-control-plane 0.1.0

package/npm/public-bin/agent-control-plane

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../bin/agent-control-plane.js");

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "agent-control-plane",
+  "version": "0.1.0",
+  "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
+  "homepage": "https://github.com/ducminhuyen0319/agent-control-plane",
+  "bugs": {
+    "url": "https://github.com/ducminhuyen0319/agent-control-plane/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ducminhuyen0319/agent-control-plane.git"
+  },
+  "license": "MIT",
+  "funding": [
+    "https://github.com/sponsors/ducminhnguyen0319"
+  ],
+  "directories": {
+    "bin": "npm/public-bin"
+  },
+  "files": [
+    "README.md",
+    "SKILL.md",
+    "assets/workflow-catalog.json",
+    "bin",
+    "hooks",
+    "npm/bin",
+    "npm/public-bin",
+    "tools/bin",
+    "tools/dashboard/app.js",
+    "tools/dashboard/dashboard_snapshot.py",
+    "tools/dashboard/index.html",
+    "tools/dashboard/server.py",
+    "tools/dashboard/styles.css",
+    "tools/templates",
+    "tools/tests",
+    "tools/vendor/codex-quota/LICENSE",
+    "tools/vendor/codex-quota/codex-quota.js",
+    "tools/vendor/codex-quota/lib",
+    "tools/vendor/codex-quota-manager/scripts"
+  ],
+  "scripts": {
+    "doctor": "node ./npm/bin/agent-control-plane.js doctor",
+    "smoke": "node ./npm/bin/agent-control-plane.js smoke",
+    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh"
+  },
+  "keywords": [
+    "agents",
+    "automation",
+    "background-jobs",
+    "dashboard",
+    "control-plane",
+    "developer-tools",
+    "github-actions",
+    "github",
+    "npx",
+    "runtime"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/tools/bin/agent-cleanup-worktree

@@ -0,0 +1,247 @@
+#!/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

@@ -0,0 +1,66 @@
+#!/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}"
+current_json="$(flow_github_api_repo "${repo_slug}" "${resource}")"
+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

@@ -0,0 +1,216 @@
+#!/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

@@ -0,0 +1,52 @@
+#!/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

@@ -0,0 +1,46 @@
+#!/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