@mgeri1993/claude-task-manager 1.0.0

package/api/index.php

@@ -0,0 +1,173 @@
+<?php
+/**
+ * api/index.php — the task-manager board's WRITE ENDPOINT (multi-project version).
+ *
+ * The PHP built-in server runs this file directly. Started via docker compose (see
+ * docker-compose.yml), or manually (docroot = the project root):
+ *   php -S localhost:3333 -t /Users/mgeri1993/code/projects/claude-task-manager
+ *   → board:    http://localhost:3333/
+ *   → endpoint: http://localhost:3333/api/index.php
+ *
+ * Writes go EXCLUSIVELY through engine/task.sh (allowlisted commands, `--as <as>`,
+ * `TM_DIR=<project data dir>`), so tasks.json's ONLY writer remains task.sh (atomic lock,
+ * history, events.jsonl, per-agent inbox). The browser NEVER writes the JSON directly.
+ *
+ * The `project` field is allowlisted against data/projects.json's registered ids — this
+ * decides which project's data directory (TM_DIR) the engine gets.
+ *
+ * The optional `lang` field (the board's current UI language) is persisted as the
+ * project's preferred language in a small `.board-lang` file next to tasks.json — NOT
+ * inside any task. engine/task.sh reads it on every invocation and prints a reminder, so
+ * an agent running task.sh next knows which language to reply/work in.
+ *
+ * Security:
+ *   - proc_open ARRAY form → no shell, no injection (no escaping needed on POSIX).
+ *   - command allowlist: destructive commands (rm/restore/raw/archive) are NOT exposed.
+ *   - the real perimeter is docker-compose.yml's port binding (127.0.0.1:<port>:<port>) —
+ *     the container is unreachable from anywhere but the host's own loopback. Requests that
+ *     DO reach this script still show a private/link-local REMOTE_ADDR (the docker bridge's
+ *     gateway, e.g. 172.x.x.1), never a public one, since Docker NATs the host-loopback
+ *     connection — so this check accepts private ranges too, not just literal 127.0.0.1.
+ *   - the project id is checked against data/projects.json's registered list — the client
+ *     can never supply an arbitrary TM_DIR.
+ */
+
+header('Content-Type: application/json; charset=utf-8');
+
+/** True for 127.0.0.0/8, ::1, and the RFC1918 private ranges Docker's bridge networks use. */
+function is_local_or_private_addr(string $addr): bool
+{
+    if ($addr === '' || $addr === '::1') return true;
+    if (str_starts_with($addr, '127.')) return true;
+    $long = ip2long($addr);
+    if ($long === false) return false;
+    $inRange = static fn(string $cidr, int $bits) => ($long & ~((1 << (32 - $bits)) - 1)) === (ip2long($cidr) & ~((1 << (32 - $bits)) - 1));
+    return $inRange('10.0.0.0', 8) || $inRange('172.16.0.0', 12) || $inRange('192.168.0.0', 16);
+}
+
+$remote = $_SERVER['REMOTE_ADDR'] ?? '';
+if (!is_local_or_private_addr($remote)) {
+    http_response_code(403);
+    echo json_encode(['ok' => false, 'error' => 'localhost only']);
+    exit;
+}
+
+if (($_SERVER['REQUEST_METHOD'] ?? 'GET') !== 'POST') {
+    http_response_code(405);
+    echo json_encode(['ok' => false, 'error' => 'POST only']);
+    exit;
+}
+
+// task.sh commands exposed from the board. rm/restore/raw/archive are DELIBERATELY excluded.
+const ALLOWED = [
+    'status', 'note', 'priority', 'module', 'tag', 'assign', 'dep',
+    'status-many', 'reopen', 'add',
+];
+
+const ALLOWED_LANGS = ['en', 'hu'];
+
+$ROOT_DIR       = dirname(__DIR__);                       // claude-task-manager/
+$ENGINE_TASK_SH = $ROOT_DIR . '/engine/task.sh';
+$PROJECTS_FILE  = $ROOT_DIR . '/data/projects.json';
+
+$raw  = file_get_contents('php://input') ?: '';
+$body = json_decode($raw, true);
+if (!is_array($body)) {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => 'invalid JSON body']);
+    exit;
+}
+
+// Actor (--as): the board SENDS who the caller is — a selectable agent/reviewer, NOT a
+// fixed "human".
+$actor = isset($body['as']) ? preg_replace('/[^A-Za-z0-9_.-]/', '', (string) $body['as']) : '';
+if ($actor === '') {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => 'missing "as" (agent name) — set it on the board: "As …"']);
+    exit;
+}
+
+// Project: allowlisted against data/projects.json's registered ids — the client can never
+// supply an arbitrary path, only an already-registered project id.
+$projectId = isset($body['project']) ? preg_replace('/[^A-Za-z0-9_-]/', '', (string) $body['project']) : '';
+if ($projectId === '') {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => 'missing "project" (set it in the Source selector)']);
+    exit;
+}
+
+$projects = [];
+if (is_file($PROJECTS_FILE)) {
+    $decoded = json_decode((string) file_get_contents($PROJECTS_FILE), true);
+    if (is_array($decoded)) $projects = $decoded;
+}
+// Only used to check that $projectId is actually registered — NOT for its stored
+// "dataDir" value, which is a HOST-absolute path baked in by engine/projects.sh (run on
+// the host). Inside the docker container the filesystem root is /app, not the host's path,
+// so the real data dir is always computed relative to THIS script's own $ROOT_DIR instead
+// — that resolves correctly whether this file is running on the host or in the container.
+$known = false;
+foreach ($projects as $p) {
+    if (is_array($p) && ($p['id'] ?? null) === $projectId) { $known = true; break; }
+}
+if (!$known) {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => "unknown project: $projectId"]);
+    exit;
+}
+$dataDir = $ROOT_DIR . '/data/' . $projectId;
+
+// Persist the board's current UI language as this project's preferred language (best
+// effort — never fails the request). engine/task.sh reads this file on every run.
+$lang = isset($body['lang']) ? (string) $body['lang'] : '';
+if (in_array($lang, ALLOWED_LANGS, true)) {
+    @file_put_contents($dataDir . '/.board-lang', $lang);
+}
+
+// One or more operations: { cmd, args } OR { ops: [ {cmd,args}, ... ] }.
+$ops = [];
+if (isset($body['ops']) && is_array($body['ops'])) {
+    $ops = $body['ops'];
+} elseif (isset($body['cmd'])) {
+    $ops = [['cmd' => $body['cmd'], 'args' => $body['args'] ?? []]];
+}
+if (!$ops) {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => 'missing cmd/ops']);
+    exit;
+}
+
+/** Run one task.sh command as an argv array (no shell), with the project's TM_DIR. */
+function run_task_sh(string $taskSh, string $cmd, array $args, string $actor, string $tmDir): array
+{
+    $argv = array_merge([$taskSh, $cmd], array_map('strval', array_values($args)), ['--as', $actor]);
+    $desc = [1 => ['pipe', 'w'], 2 => ['pipe', 'w']];
+    $env  = ['TM_DIR' => $tmDir, 'PATH' => getenv('PATH') ?: '/usr/local/bin:/usr/bin:/bin'];
+    $proc = proc_open($argv, $desc, $pipes, dirname($taskSh), $env);
+    if (!is_resource($proc)) {
+        return ['ok' => false, 'code' => -1, 'out' => '', 'err' => 'proc_open failed'];
+    }
+    $out = stream_get_contents($pipes[1]); fclose($pipes[1]);
+    $err = stream_get_contents($pipes[2]); fclose($pipes[2]);
+    $code = proc_close($proc);
+    return ['ok' => $code === 0, 'code' => $code, 'out' => trim((string) $out), 'err' => trim((string) $err)];
+}
+
+$results = [];
+$allOk = true;
+foreach ($ops as $op) {
+    $cmd  = is_array($op) ? ($op['cmd'] ?? '') : '';
+    $args = (is_array($op) && isset($op['args']) && is_array($op['args'])) ? $op['args'] : [];
+    if (!in_array($cmd, ALLOWED, true)) {
+        $results[] = ['ok' => false, 'cmd' => $cmd, 'err' => "command not allowed: $cmd"];
+        $allOk = false;
+        break; // don't continue the chain after an invalid step
+    }
+    $r = run_task_sh($ENGINE_TASK_SH, $cmd, $args, $actor, $dataDir);
+    $r['cmd'] = $cmd;
+    $results[] = $r;
+    if (!$r['ok']) { $allOk = false; break; } // stop at the first failure (don't let note+status split)
+}
+
+http_response_code($allOk ? 200 : 422);
+echo json_encode(['ok' => $allOk, 'results' => $results]);

package/bin/add-agent.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# add-agent.sh — create a custom teammate agent definition in an ALREADY installed
+# (ctm init-ed) project.
+#
+# Naming convention: claude-task-manager's base set, installed by install.sh, is always
+# "ctm-*" (ctm-frontend-developer / ctm-backend-developer / ctm-code-investigator) —
+# generated/refreshed by "ctm init". Custom agents created with THIS script, as needed by
+# the user, are always named "tm-*" — so at a glance you can tell what's the auto-refreshed
+# base set apart from a custom, hand-edited addition ("ctm init" never touches these).
+#
+# Usage (typically invoked via the "ctm agent add" subcommand):
+#   /Users/mgeri1993/code/projects/claude-task-manager/bin/add-agent.sh [target-dir] <name> [description]
+#
+# target-dir  – defaults to the current directory's git root (or the cwd)
+# name        – the custom agent's name, WITH or WITHOUT the "tm-" prefix — the result is
+#               always "tm-<name>" (the "ctm-" prefix is reserved, you cannot use it).
+# description – a short, one-sentence role description (goes into the generated .md's
+#               description field)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+die() { echo "error: $*" >&2; exit 1; }
+
+# shellcheck source=engine/check-update.sh
+source "$ROOT_DIR/engine/check-update.sh"
+check_for_updates "$ROOT_DIR"
+
+TARGET_ARG="${1:-}"
+if [[ -n "$TARGET_ARG" && -d "$TARGET_ARG" ]]; then
+  TARGET_DIR="$(cd "$TARGET_ARG" && pwd)"
+  shift
+elif ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"; then
+  TARGET_DIR="$ROOT"
+else
+  TARGET_DIR="$(pwd)"
+fi
+
+RAW_NAME="${1:-}"
+[[ -n "$RAW_NAME" ]] || die "usage: add-agent.sh [target-dir] <name> [description]"
+shift || true
+DESCRIPTION="${*:-Custom, project-specific teammate.}"
+
+SKILL_DIR="$TARGET_DIR/.claude/skills/task-manager"
+TASK_SH="$SKILL_DIR/task.sh"
+[[ -x "$TASK_SH" ]] || die "this project is not installed — run first: ctm init (here: $TARGET_DIR)"
+
+# Normalize the name: always with a "tm-" prefix; "ctm-" is reserved (the base set's prefix).
+SHORT="${RAW_NAME#tm-}"
+[[ "$SHORT" == ctm-* || "$SHORT" == ctm ]] && die 'the "ctm-" prefix is reserved (for the base agents) — choose a different name'
+[[ "$SHORT" =~ ^[A-Za-z0-9_-]+$ ]] || die "invalid name (only A-Za-z0-9_- allowed): $RAW_NAME"
+AGENT_NAME="tm-$SHORT"
+
+# The project label, from the already-installed SKILL.md's "# Task Manager (Label)" heading
+# (more accurate than the folder name, if "ctm init" was given a custom label); falls back
+# to the folder name if there's no such line.
+LABEL="$(sed -n 's/^# Task Manager (\(.*\))$/\1/p' "$SKILL_DIR/SKILL.md" 2>/dev/null | head -1)"
+LABEL="${LABEL:-$(basename "$TARGET_DIR")}"
+
+AGENTS_DIR="$TARGET_DIR/.claude/agents"
+mkdir -p "$AGENTS_DIR"
+OUT="$AGENTS_DIR/$AGENT_NAME.md"
+[[ -e "$OUT" ]] && die "already exists: $OUT (delete it by hand if you want to regenerate it)"
+
+sed \
+  -e "s#__AGENT_NAME__#$AGENT_NAME#g" \
+  -e "s#__AGENT_SHORT__#$SHORT#g" \
+  -e "s#__AGENT_DESCRIPTION__#$DESCRIPTION#g" \
+  -e "s#__PROJECT_LABEL__#$LABEL#g" \
+  -e "s#__TASK_SH_PATH__#$TASK_SH#g" \
+  "$ROOT_DIR/templates/tm-custom.md.tmpl" > "$OUT"
+
+echo "created: $OUT"
+echo "(--as/assign value: \"$SHORT\" — edit the file if you need to refine its role/scope)"

package/bin/ctm

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+#
+# ctm — the claude-task-manager command-line entry point.
+#
+# This file typically runs as a SYMLINK from a directory on PATH (e.g. /usr/local/bin/ctm or
+# ~/.local/bin/ctm) — install.sh registers it automatically. Callable from any project
+# directory, no cd/absolute path needed.
+#
+# Usage:
+#   ctm init [project-id] [label]   Install the CURRENT directory (or its git root)
+#   ctm list                        Registered projects
+#   ctm rm <id> [--force]           Remove a registered project (data + wrapper) — asks first
+#   ctm wrapper <id>                Print a project's generated wrapper task.sh
+#   ctm agent add <name> [desc]     Create a custom ("tm-<name>") teammate definition
+#   ctm up [port]                   Start/check the board with docker; if running, only
+#                                    reconciles; if a port is given, sets it (writes .env)
+#                                    and restarts the container. Reports a busy port before
+#                                    calling docker at all.
+#   ctm down                        Stop the board.
+#   ctm autostart on|off            Auto-start the container on Docker/machine restart
+#                                    (docker restart-policy) — sets and applies it.
+
+set -euo pipefail
+
+# Resolve the real file behind the symlink (portable, works on macOS too — BSD readlink
+# doesn't support -f).
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+BIN_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ROOT_DIR="$(cd "$BIN_DIR/.." && pwd)"
+
+die() { echo "error: $*" >&2; exit 1; }
+
+# shellcheck source=engine/check-update.sh
+source "$ROOT_DIR/engine/check-update.sh"
+check_for_updates "$ROOT_DIR"
+
+# docker-compose.yml interpolates the .env CTM_PORT value from the project root into the
+# ports/command fields — this is where we write the desired port, if the caller gave one.
+set_env_var() {
+  local file="$1" key="$2" value="$3" tmp
+  tmp="$(mktemp)"
+  [[ -f "$file" ]] && grep -v "^${key}=" "$file" > "$tmp" || true
+  echo "${key}=${value}" >> "$tmp"
+  mv "$tmp" "$file"
+}
+current_port() {
+  grep '^CTM_PORT=' "$ROOT_DIR/.env" 2>/dev/null | head -1 | cut -d= -f2
+}
+
+# True if OUR OWN container (claude-task-manager) is already running and already listening
+# on this port — in that case there's no conflict, docker compose will just reconcile.
+our_container_already_on_port() {
+  local port="$1"
+  docker ps --filter "name=^claude-task-manager$" --format '{{.Ports}}' 2>/dev/null \
+    | grep -q "127.0.0.1:${port}->"
+}
+
+# If the requested port is already taken by a DIFFERENT process, fail clearly before even
+# calling docker compose (its own error message is less helpful here).
+check_port_free() {
+  local port="$1"
+  our_container_already_on_port "$port" && return 0
+  if command -v lsof >/dev/null 2>&1 && lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
+    die "port $port is already in use (by another process) — pick a different one: ctm up <other-port>"
+  fi
+}
+
+cmd="${1:-help}"; shift || true
+
+case "$cmd" in
+  init)
+    "$ROOT_DIR/install.sh" "$(pwd)" "$@"
+    ;;
+  list|ls)
+    "$ROOT_DIR/engine/projects.sh" list
+    ;;
+  rm|remove)
+    id="" force=0
+    for a in "$@"; do
+      case "$a" in
+        --force|-y|--yes) force=1 ;;
+        *) id="$a" ;;
+      esac
+    done
+    [[ -n "$id" ]] || die "usage: ctm rm <id> [--force]"
+    if [[ "$force" != "1" ]]; then
+      if [[ ! -t 0 ]]; then
+        die "project \"$id\" not removed — non-interactive session, pass --force to confirm"
+      fi
+      reply=""
+      read -r -p "Remove project \"$id\" (data + wrapper, cannot be undone)? [y/N] " reply || reply="n"
+      [[ "$reply" =~ ^[Yy]$ ]] || { echo "cancelled"; exit 0; }
+    fi
+    "$ROOT_DIR/engine/projects.sh" rm "$id"
+    ;;
+  wrapper)
+    "$ROOT_DIR/engine/projects.sh" wrapper "$@"
+    ;;
+  agent)
+    sub="${1:-}"; shift || true
+    case "$sub" in
+      add) "$ROOT_DIR/bin/add-agent.sh" "$(pwd)" "$@" ;;
+      *) die "usage: ctm agent add <name> [description]" ;;
+    esac
+    ;;
+  up)
+    port="${1:-$(current_port)}"
+    port="${port:-3333}"
+    [[ "$port" =~ ^[0-9]+$ ]] || die "invalid port: $port"
+    check_port_free "$port"
+    set_env_var "$ROOT_DIR/.env" "CTM_PORT" "$port"
+    # `docker compose up -d` is itself idempotent: if the container isn't running, it starts
+    # it; if it's running and the config (e.g. port) changed, it's automatically recreated
+    # with the new setting; if it's running and nothing changed, it does nothing.
+    (cd "$ROOT_DIR" && docker compose up -d --build)
+    echo "board: http://localhost:$(current_port)/"
+    ;;
+  down)
+    (cd "$ROOT_DIR" && docker compose down)
+    ;;
+  autostart)
+    mode="${1:-}"
+    case "$mode" in
+      on)  set_env_var "$ROOT_DIR/.env" "CTM_RESTART" "unless-stopped" ;;
+      off) set_env_var "$ROOT_DIR/.env" "CTM_RESTART" "no" ;;
+      *) die "usage: ctm autostart on|off" ;;
+    esac
+    (cd "$ROOT_DIR" && docker compose up -d --build)
+    echo "autostart: $mode (restart-policy: $(grep '^CTM_RESTART=' "$ROOT_DIR/.env" | cut -d= -f2))"
+    ;;
+  help|-h|--help|"")
+    cat <<'EOF'
+ctm — claude-task-manager CLI
+
+  ctm init [project-id] [label] [--force]
+                                   Register the CURRENT directory (or its git root) as a
+                                   project + install .claude/skills/task-manager/ (task.sh
+                                   wrapper + SKILL.md + ctm-* agents + hooks + allowlist).
+                                   Docker NOT required. Prompts before overwriting an
+                                   existing file (--force / -y skips the prompt).
+  ctm list                        List registered projects.
+  ctm rm <id> [--force]           Remove a registered project (data + wrapper). Asks for
+                                   confirmation first (or requires --force non-interactively).
+  ctm wrapper <id>                Print a project's generated wrapper task.sh.
+  ctm agent add <name> [desc]     Create a custom teammate definition in the CURRENT
+                                   (already "ctm init"-ed) project — always named "tm-<name>".
+  ctm up [port]                   Check/start the board with docker. Starts it if not
+                                   running; does nothing if already running; if you also give
+                                   a port, sets it and restarts if needed.
+  ctm down                        Stop the board.
+  ctm autostart on|off            Auto-start the container on Docker/machine restart.
+EOF
+    ;;
+  *) die "unknown command: $cmd (help: ctm help)" ;;
+esac

package/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  task-manager:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: claude-task-manager
+    restart: ${CTM_RESTART:-no}   # "unless-stopped"-re állítva: ctm autostart on
+    ports:
+      - "127.0.0.1:${CTM_PORT:-3333}:${CTM_PORT:-3333}"   # csak a host loopbackjén, ne a LAN-on
+    volumes:
+      - .:/app
+    environment:
+      - PHP_CLI_SERVER_WORKERS=4
+    command: ["sh", "-c", "php -S 0.0.0.0:${CTM_PORT:-3333} -t /app"]

package/engine/check-update.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# check-update.sh — sourced (not executed) by the other scripts to print a yellow notice
+# when origin's default branch has commits the local checkout doesn't have yet.
+#
+# Deliberately NOT sourced by engine/task.sh: that script is called on every single task
+# mutation (often many times per agent session), and a network round-trip on every call
+# would add real, repeated latency to the hot path. It IS sourced by the admin-facing
+# entry points (ctm, install.sh, add-agent.sh, projects.sh), which run far less often.
+#
+# IMPORTANT: this is sourced into callers that run under `set -e` — every command that
+# could plausibly fail (offline, no origin/HEAD set, first commit not yet pushed, etc.)
+# is guarded with `|| true` so a failure here can NEVER abort the calling script.
+#
+# Usage (from a script that has already resolved ROOT_DIR to the repo root):
+#   source "$ROOT_DIR/engine/check-update.sh"
+#   check_for_updates "$ROOT_DIR"
+#
+# Silent on: no git, not a git checkout, no "origin" remote, offline/unreachable remote,
+# or local already up to date. Only prints when the remote genuinely has something new.
+
+check_for_updates() {
+  local root="${1:-.}"
+  command -v git >/dev/null 2>&1 || return 0
+  [[ -d "$root/.git" ]] || return 0
+  git -C "$root" remote get-url origin >/dev/null 2>&1 || return 0
+
+  # origin/HEAD may not be set locally (git push -u doesn't set it the way git clone does)
+  # — fall back to "main" when it's missing, rather than letting the lookup fail.
+  local branch
+  branch="$(git -C "$root" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+  branch="${branch#origin/}"
+  branch="${branch:-main}"
+
+  # Lightweight ref lookup (no object transfer) with a short low-speed timeout, so a slow
+  # or unreachable remote never noticeably delays the command that triggered this check.
+  local remote_sha local_sha
+  remote_sha="$( (git -C "$root" -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=2 \
+    ls-remote origin "refs/heads/$branch" 2>/dev/null || true) | cut -f1)"
+  [[ -n "$remote_sha" ]] || return 0
+  local_sha="$(git -C "$root" rev-parse HEAD 2>/dev/null || true)"
+  [[ -n "$local_sha" ]] || return 0
+  [[ "$remote_sha" == "$local_sha" ]] && return 0
+
+  printf '\033[33m[claude-task-manager] A newer version is available on origin/%s — update with: git -C %s pull\033[0m\n' \
+    "$branch" "$root" >&2
+  return 0
+}

package/engine/projects.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# projects.sh — project-registration admin CLI for claude-task-manager.
+#
+# For every registered project, creates its own data directory (data/<id>/tasks.json etc.,
+# using the existing task.sh init) and an absolute-path wrapper script with the project id
+# "baked in" (wrappers/<id>.sh), which can be copied into the target project so its agents
+# can call it directly, without needing TM_DIR.
+#
+# Usage:
+#   ./projects.sh add <id> <label>
+#   ./projects.sh list
+#   ./projects.sh rm <id>
+#   ./projects.sh wrapper <id>
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+DATA_ROOT="$ROOT_DIR/data"
+WRAPPERS_DIR="$ROOT_DIR/wrappers"
+ENGINE_TASK_SH="$ROOT_DIR/engine/task.sh"
+PROJECTS_FILE="$DATA_ROOT/projects.json"
+LOCK_DIR="$DATA_ROOT/.projects.lock"
+
+# shellcheck source=engine/check-update.sh
+source "$ROOT_DIR/engine/check-update.sh"
+check_for_updates "$ROOT_DIR"
+
+die() { echo "error: $*" >&2; exit 1; }
+
+command -v jq >/dev/null 2>&1 || die "jq is not installed (required for this script)."
+
+now_iso() { date -u +%Y-%m-%dT%H:%M:%S.000Z; }
+
+is_valid_id() {
+  [[ "$1" =~ ^[A-Za-z0-9_-]+$ ]]
+}
+
+# --- Concurrency lock (same mkdir-based pattern as the engine task.sh) --------------
+LOCK_HELD=0
+acquire_lock() {
+  local waited=0 timeout=15
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    waited=$((waited + 1))
+    [[ $waited -ge $((timeout * 20)) ]] && die "could not acquire lock within ${timeout}s: $LOCK_DIR"
+    sleep 0.05
+  done
+  LOCK_HELD=1
+  trap release_lock EXIT INT TERM
+}
+release_lock() {
+  [[ "$LOCK_HELD" == "1" ]] && rm -rf "$LOCK_DIR" 2>/dev/null || true
+  LOCK_HELD=0
+}
+
+ensure_projects_file() {
+  mkdir -p "$DATA_ROOT"
+  [[ -f "$PROJECTS_FILE" ]] || echo '[]' > "$PROJECTS_FILE"
+}
+
+project_exists() {
+  local id="$1"
+  [[ "$(jq --arg id "$id" '[.[]|select(.id==$id)]|length' "$PROJECTS_FILE")" != "0" ]]
+}
+
+# Atomic write to PROJECTS_FILE (jq filter, via a temp file).
+apply_jq() {
+  acquire_lock
+  local tmp
+  tmp="$(mktemp "${PROJECTS_FILE}.XXXXXX")"
+  if jq "$@" "$PROJECTS_FILE" > "$tmp"; then
+    mv "$tmp" "$PROJECTS_FILE"
+  else
+    rm -f "$tmp"
+    release_lock
+    die "jq operation failed."
+  fi
+  release_lock
+}
+
+wrapper_path() { echo "$WRAPPERS_DIR/$1.sh"; }
+data_dir()     { echo "$DATA_ROOT/$1"; }
+
+write_wrapper() {
+  local id="$1" label="$2" dataDir="$3" wpath="$4"
+  mkdir -p "$WRAPPERS_DIR"
+  cat > "$wpath" <<EOF
+#!/usr/bin/env bash
+# Auto-generated for the claude-task-manager "${label}" project — do not edit by hand.
+# Regenerate with: engine/projects.sh add ${id} "${label}"  (overwrites)
+exec env TM_DIR="${dataDir}" \\
+  "${ENGINE_TASK_SH}" "\$@"
+EOF
+  chmod +x "$wpath"
+}
+
+cmd_add() {
+  [[ $# -ge 2 ]] || die "usage: add <id> <label>"
+  local id="$1" label="$2"
+  is_valid_id "$id" || die "invalid id (only A-Za-z0-9_- allowed): $id"
+  ensure_projects_file
+  local dataDir wpath now
+  dataDir="$(data_dir "$id")"
+  wpath="$(wrapper_path "$id")"
+  now="$(now_iso)"
+
+  mkdir -p "$dataDir"
+  TM_DIR="$dataDir" "$ENGINE_TASK_SH" init >/dev/null
+  TM_DIR="$dataDir" "$ENGINE_TASK_SH" ctx-init "" "" --as projects-admin >/dev/null
+
+  write_wrapper "$id" "$label" "$dataDir" "$wpath"
+
+  if project_exists "$id"; then
+    apply_jq --arg id "$id" --arg label "$label" --arg dataDir "$dataDir" \
+             --arg wpath "$wpath" --arg now "$now" \
+      '(.[]|select(.id==$id)) |= (.label=$label | .dataDir=$dataDir | .wrapperPath=$wpath)'
+    echo "updated: $id"
+  else
+    apply_jq --arg id "$id" --arg label "$label" --arg dataDir "$dataDir" \
+             --arg wpath "$wpath" --arg now "$now" \
+      '. += [{id:$id, label:$label, dataDir:$dataDir, wrapperPath:$wpath, createdAt:$now}]'
+    echo "added: $id -> $dataDir (wrapper: $wpath)"
+  fi
+}
+
+cmd_list() {
+  ensure_projects_file
+  jq -r '.[] | "\(.id)\t\(.label)\t\(.dataDir)"' "$PROJECTS_FILE" | column -t -s $'\t'
+}
+
+cmd_rm() {
+  [[ $# -ge 1 ]] || die "usage: rm <id>"
+  local id="$1"
+  ensure_projects_file
+  project_exists "$id" || die "no such project: $id"
+  apply_jq --arg id "$id" '[.[]|select(.id!=$id)]'
+  rm -rf "$(data_dir "$id")"
+  rm -f "$(wrapper_path "$id")"
+  echo "removed: $id (data and wrapper too)"
+}
+
+cmd_wrapper() {
+  [[ $# -ge 1 ]] || die "usage: wrapper <id>"
+  local id="$1"
+  ensure_projects_file
+  project_exists "$id" || die "no such project: $id"
+  cat "$(wrapper_path "$id")"
+}
+
+main() {
+  local cmd="${1:-}"
+  shift || true
+  case "$cmd" in
+    add)     cmd_add "$@" ;;
+    list|ls) cmd_list "$@" ;;
+    rm|remove) cmd_rm "$@" ;;
+    wrapper) cmd_wrapper "$@" ;;
+    *) die "unknown command: $cmd (add|list|rm|wrapper)" ;;
+  esac
+}
+
+main "$@"