@mgeri1993/claude-task-manager 1.0.0

package/engine/task.sh

@@ -0,0 +1,926 @@
+#!/usr/bin/env bash
+#
+# task.sh — token-efficient CLI for managing the task-manager tasks.json (and context.json).
+#
+# Goal: Claude Code should NOT re-read/re-write the whole JSON for every operation (expensive
+# in tokens); instead it should use terse commands. Every mutation is atomic (temp file + mv),
+# and timestamps + history/notes entries are maintained automatically.
+#
+# Usage:   ./task.sh <command> [arguments]
+# Help:    ./task.sh help
+#
+# The store defaults to the project's .claude/task-manager/ directory; overridable via the
+# TM_DIR environment variable (this is how the claude-task-manager wrapper scripts point each
+# project at its own data directory).
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Configuration / paths
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Project root: two levels up from the skill directory (.claude/skills/task-manager -> project).
+# Uses git if available, otherwise falls back to the relative path.
+default_dir() {
+  local root
+  if root="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null)"; then
+    echo "$root/.claude/task-manager"
+  else
+    echo "$SCRIPT_DIR/../../task-manager"
+  fi
+}
+
+TM_DIR="${TM_DIR:-$(default_dir)}"
+TASKS_FILE="$TM_DIR/tasks.json"
+CONTEXT_FILE="$TM_DIR/context.json"
+BACKUP_FILE="$TM_DIR/tasks.json.bak"
+CTX_BACKUP_FILE="$TM_DIR/context.json.bak"
+LOCK_DIR="$TM_DIR/.tm.lock"
+
+# --- Agent-notification (inbox) storage ----------------------------------------
+# events.jsonl: an append-only event feed (ALONGSIDE the per-task history, not replacing it),
+# from which the `inbox <agent>` command returns only NEW events generated by OTHER agents,
+# using a per-agent cursor. The PostToolUse hook injects this for the caller automatically.
+# This is ADDITIVE: it does not change the existing tasks.json/history logic.
+EVENTS_FILE="$TM_DIR/events.jsonl"
+CURSORS_DIR="$TM_DIR/.cursors"
+
+VALID_STATUSES="todo in_progress blocked review done"
+VALID_PRIORITIES="low normal high urgent"
+
+# The calling agent's name (--as <name>); main() fills this in from the command arguments.
+# emit_event writes this as `by`; inbox uses it to filter out the caller's own echo.
+ACTOR=""
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+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; }
+
+# --- Concurrency lock (mkdir-based, portable) --------------------------------
+# macOS has no built-in flock(1), so we use an atomic mkdir-lock (same pattern as the
+# agent-message-bus skill). This means two concurrently-writing agents don't clobber each
+# other (last-write-wins is eliminated). The lock is cleaned up by a trap if the process
+# exits early.
+LOCK_HELD=0
+
+# Determine the lock's age in seconds (based on dir mtime), portably (BSD/macOS
+# `stat -f %m`, GNU/Linux `stat -c %Y`). Empty if there's no lock.
+lock_age() {
+  local m now
+  m="$(stat -f %m "$LOCK_DIR" 2>/dev/null || stat -c %Y "$LOCK_DIR" 2>/dev/null || echo "")"
+  [[ -z "$m" ]] && { echo ""; return; }
+  now="$(date +%s)"
+  echo $(( now - m ))
+}
+
+acquire_lock() {
+  local waited=0 timeout="${TM_LOCK_TIMEOUT:-15}" stale="${TM_LOCK_STALE:-60}"
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    # Remove an orphaned lock ONLY based on age (after a real crash). On the hot path
+    # (fast, healthy writers) this never runs, so an active lock is never removed, and two
+    # writers can never be in the critical section at once.
+    local age; age="$(lock_age)"
+    if [[ -n "$age" && "$age" -ge "$stale" ]]; then
+      rm -rf "$LOCK_DIR" 2>/dev/null || true
+      continue
+    fi
+    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
+}
+
+# --- Pre-write backup --------------------------------------------------------
+# Before every mutation we save the previous state (one generation), so that `restore`
+# can undo a broken write.
+backup_tasks()   { [[ -f "$TASKS_FILE"   ]] && cp "$TASKS_FILE"   "$BACKUP_FILE"     2>/dev/null || true; }
+backup_context() { [[ -f "$CONTEXT_FILE" ]] && cp "$CONTEXT_FILE" "$CTX_BACKUP_FILE" 2>/dev/null || true; }
+
+ensure_tasks_file() {
+  if [[ ! -f "$TASKS_FILE" ]]; then
+    mkdir -p "$TM_DIR"
+    jq -n --arg now "$(now_iso)" \
+      '{schemaVersion:1, updatedAt:$now, tasks:[]}' > "$TASKS_FILE"
+  fi
+}
+
+require_tasks_file() {
+  [[ -f "$TASKS_FILE" ]] || die "no tasks.json: $TASKS_FILE (run: task.sh init)"
+}
+
+is_valid_status() {
+  local s="$1"
+  for v in $VALID_STATUSES; do [[ "$s" == "$v" ]] && return 0; done
+  return 1
+}
+
+# Atomic write: applies a jq filter to TASKS_FILE via a temp file. The filter also updates
+# the root updatedAt field.
+apply_jq() {
+  acquire_lock
+  backup_tasks
+  local tmp
+  tmp="$(mktemp "${TASKS_FILE}.XXXXXX")"
+  if jq "$@" "$TASKS_FILE" > "$tmp"; then
+    mv "$tmp" "$TASKS_FILE"
+  else
+    rm -f "$tmp"
+    release_lock
+    die "jq operation failed."
+  fi
+  release_lock
+}
+
+task_exists() {
+  local id="$1"
+  [[ "$(jq --arg id "$id" '[.tasks[]|select(.id==$id)]|length' "$TASKS_FILE")" != "0" ]]
+}
+
+# --- Event feed (inbox) ----------------------------------------------------
+# One line in events.jsonl: {seq, at, by, task, kind, text}. `seq` monotonically increases
+# (the file's line count + 1, consistent under the lock). `by` is the calling agent (ACTOR).
+# Only mutations call this; queries do not generate events. Swallows errors: notification is
+# best-effort and should never fail a task operation.
+emit_event() {
+  local task="$1" kind="$2" text="${3:-}"
+  [[ -n "$ACTOR" ]] || return 0
+  local now; now="$(now_iso)"
+  acquire_lock
+  mkdir -p "$TM_DIR" 2>/dev/null || true
+  touch "$EVENTS_FILE" 2>/dev/null || true
+  local seq; seq=$(( $(wc -l < "$EVENTS_FILE" 2>/dev/null || echo 0) + 1 ))
+  jq -cn --argjson seq "$seq" --arg at "$now" --arg by "$ACTOR" \
+     --arg task "$task" --arg kind "$kind" --arg text "$text" \
+     '{seq:$seq, at:$at, by:$by, task:$task, kind:$kind, text:$text}' \
+     >> "$EVENTS_FILE" 2>/dev/null || true
+  release_lock
+}
+
+# --- context.json helpers (same atomic pattern, separate file) ---------
+
+ensure_context_file() {
+  if [[ ! -f "$CONTEXT_FILE" ]]; then
+    mkdir -p "$TM_DIR"
+    jq -n --arg now "$(now_iso)" '{
+      schemaVersion:1, updatedAt:$now, initPrompt:"", goal:"",
+      currentFocus:"", constraints:[], decisions:[], openQuestions:[], notes:""
+    }' > "$CONTEXT_FILE"
+  fi
+}
+
+require_context_file() {
+  [[ -f "$CONTEXT_FILE" ]] || die "no context.json: $CONTEXT_FILE (run: task.sh ctx-init)"
+}
+
+# Atomic write to CONTEXT_FILE (like apply_jq, just for the other file).
+apply_ctx() {
+  acquire_lock
+  backup_context
+  local tmp
+  tmp="$(mktemp "${CONTEXT_FILE}.XXXXXX")"
+  if jq "$@" "$CONTEXT_FILE" > "$tmp"; then
+    mv "$tmp" "$CONTEXT_FILE"
+  else
+    rm -f "$tmp"
+    release_lock
+    die "jq operation failed (context)."
+  fi
+  release_lock
+}
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+cmd_help() {
+  cat <<'EOF'
+task.sh — token-efficient tasks.json manager
+
+STORAGE
+  Default: <project>/.claude/task-manager/tasks.json  (override: TM_DIR env)
+
+CALLER IDENTITY (--as) — REQUIRED for every non-meta command
+  Add to every call: --as <agent-name>   (your name; the main agent: main).
+  This is how the PostToolUse hook knows who to inject fresh events (inbox) for, and it's
+  written as every event's `by`. Meta commands are exempt (no --as needed):
+  help, inbox, init, validate, restore, raw.
+  Example:  task.sh status fix-login done --as backend-auth
+
+NOTIFICATION (inbox — the hook calls this automatically, but you can too)
+  inbox <agent>            Events generated by OTHER agents since <agent>'s cursor
+                           (not its own), then advances the cursor.
+                           SILENT if there's nothing new. The hook appends this as
+                           additionalContext.
+
+QUERIES (non-mutating, terse output)
+  list [status] [filters]  Terse list: "<id> [status] (prio) @module title #tag".
+                           Filters: --tag <t> --agent <a> --priority <p> --module <m>
+                                    --all (include archived)  --json (machine output)
+  ids [status]             Just the ids, one per line
+  get <id>                 ONE task's full JSON (not the whole file)
+  field <id> <field>       The raw value of one field of one task
+  summary                  Count by status + total
+  find <text>              Title/description search (case-insensitive), terse list
+  next                     Next recommended todo (no open dependency), by priority
+  deps <id>                What this task waits on and what it blocks (dependency view)
+  history <id>             One task's history entries, terse
+  validate                 Schema check (required fields, status, priority, broken
+                           dependency, duplicate id)
+  raw                      The whole file (rarely needed — token-expensive)
+
+MUTATIONS (atomic write under mkdir-lock; timestamp + history auto-maintained; pre-write backup)
+  init                     Create an empty tasks.json if missing
+  add <id> <title> [desc]  New task (todo, priority=normal, tags=[], dependsOn=[])
+  status <id> <status> [note]
+                           Status change + history entry (todo|in_progress|blocked|review|done)
+  status-many <status> <id...>
+                           Set multiple tasks to one status, in ONE atomic write
+  reopen <id> [status]     Reopen a closed/archived task (default: todo) with history
+  note <id> <text>         Append a note to the notes array ({at,text})
+  priority <id> <low|normal|high|urgent>
+                           Set priority
+  tag <id> <add|rm> <tag>
+                           Add/remove a label (tags array, unique)
+  module <id> <module>     Set the module/area label (assignedModule) — free text,
+                           empty string clears it. Use `list --module <m>` to filter.
+  assign <id> <agent>      Set assignedAgentId (more convenient than `set` for claiming)
+  dep <id> <add|rm> <other-id>
+                           Dependency (dependsOn): 'id' waits on 'other-id'; cycle- and
+                           existence-checked
+  set <id> <field> <json>  Set an arbitrary field to a RAW JSON value
+                           (e.g. set x assignedAgentId '"main"'  or  set x isInferred true)
+  archive <id>             isArchived=true
+  unarchive <id>           isArchived=false
+  restore                  Restore the latest pre-write backup (tasks.json.bak)
+  rm <id>                  Delete a task
+
+CONTEXT (session continuity — write context.json ONLY through these commands too, never directly)
+  ctx                      Print the whole context.json (small, cheap)
+  ctx-init [init] [goal]   Create context.json if missing (initPrompt, goal)
+  ctx-set <field> <json>   Set a top-level field (goal|currentFocus|initPrompt|notes ...)
+  ctx-decision <topic> <decision> [rationale]
+                           Append a decision to the decisions array (with timestamp)
+  ctx-constraint <text>    Append a standing constraint to the constraints array
+  ctx-question <add|rm> <text>
+                           Add / resolve an open question in the openQuestions array
+
+STATUSES:    todo, in_progress, blocked, review, done
+PRIORITIES:  low, normal, high, urgent
+
+EXAMPLES (--as is required for every non-meta command)
+  task.sh list todo --priority high --as main
+  task.sh add fix-login "Login fix" "Login returns 500" --as main
+  task.sh priority fix-login urgent --as main
+  task.sh module fix-login auth --as main
+  task.sh list --module auth --as main
+  task.sh dep deploy add fix-login --as main   # deploy waits on fix-login
+  task.sh next --as main                       # what should I do next?
+  task.sh status fix-login in_progress "started" --as backend-auth
+  task.sh status-many done fix-login deploy --as main
+  task.sh inbox backend-auth                    # (meta: no --as) fresh events
+  task.sh validate                              # (meta: no --as)
+  task.sh ctx-init "Port the legacy event editor" "Full port" --as main
+  task.sh ctx-constraint "Legacy: read-only, never click buttons" --as main
+EOF
+}
+
+cmd_init() {
+  ensure_tasks_file
+  echo "done: $TASKS_FILE"
+}
+
+cmd_list() {
+  require_tasks_file
+  local status="" tag="" agent="" prio="" module="" show_all=0 as_json=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --tag)                    tag="${2:-}"; shift 2 ;;
+      --agent)                  agent="${2:-}"; shift 2 ;;
+      --priority|--prio)        prio="${2:-}"; shift 2 ;;
+      --module|--mod)           module="${2:-}"; shift 2 ;;
+      --all|--include-archived) show_all=1; shift ;;
+      --json)                   as_json=1; shift ;;
+      --*)                      die "unknown flag: $1" ;;
+      *)                        status="$1"; shift ;;
+    esac
+  done
+  [[ -n "$status" ]] && { is_valid_status "$status" || die "invalid status: $status (valid: $VALID_STATUSES)"; }
+  local flt='.tasks[]
+    | select(($all==1) or ((.isArchived // false)|not))
+    | select($status=="" or (.status==$status))
+    | select($tag=="" or (((.tags//[]) | index($tag)) != null))
+    | select($agent=="" or (.assignedAgentId==$agent))
+    | select($prio=="" or ((.priority//"normal")==$prio))
+    | select($module=="" or ((.module//"")==$module))'
+  if [[ $as_json == 1 ]]; then
+    jq --arg status "$status" --arg tag "$tag" --arg agent "$agent" --arg prio "$prio" --arg module "$module" --argjson all "$show_all" \
+      "[ $flt | {id, status, title, priority:(.priority//\"normal\"), module:(.module//\"\"), tags:(.tags//[]), assignedAgentId, dependsOn:(.dependsOn//[])} ]" \
+      "$TASKS_FILE"
+  else
+    jq -r --arg status "$status" --arg tag "$tag" --arg agent "$agent" --arg prio "$prio" --arg module "$module" --argjson all "$show_all" \
+      "$flt | \"\(.id)\t[\(.status)]\t\((.priority//\"normal\") | if .==\"normal\" then \"\" else \"(\"+.+\")\" end)\t\((.module//\"\") | if .==\"\" then \"\" else \"@\"+. end)\t\(.title)\t\((.tags//[]) | if length>0 then \"#\"+join(\" #\") else \"\" end)\"" \
+      "$TASKS_FILE" | column -t -s $'\t'
+  fi
+}
+
+cmd_ids() {
+  require_tasks_file
+  if [[ $# -ge 1 ]]; then
+    jq -r --arg s "$1" '.tasks[]|select(.status==$s)|.id' "$TASKS_FILE"
+  else
+    jq -r '.tasks[].id' "$TASKS_FILE"
+  fi
+}
+
+cmd_get() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: get <id>"
+  local id="$1"
+  task_exists "$id" || die "no such task: $id"
+  jq --arg id "$id" '.tasks[]|select(.id==$id)' "$TASKS_FILE"
+}
+
+cmd_field() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: field <id> <field>"
+  local id="$1" f="$2"
+  task_exists "$id" || die "no such task: $id"
+  jq -r --arg id "$id" --arg f "$f" '.tasks[]|select(.id==$id)|.[$f]' "$TASKS_FILE"
+}
+
+cmd_summary() {
+  require_tasks_file
+  jq -r '
+    (.tasks|group_by(.status)|map("\(.[0].status)\t\(length)")|.[]),
+    "─\t─",
+    "total\t\(.tasks|length)"
+  ' "$TASKS_FILE" | column -t -s $'\t'
+}
+
+cmd_find() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: find <text>"
+  local q="$1"
+  jq -r --arg q "$q" '
+    .tasks[]
+    | select((.title|ascii_downcase|contains($q|ascii_downcase))
+             or ((.description//"")|ascii_downcase|contains($q|ascii_downcase)))
+    | "\(.id)\t[\(.status)]\t\(.title)"
+  ' "$TASKS_FILE" | column -t -s $'\t'
+}
+
+cmd_history() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: history <id>"
+  local id="$1"
+  task_exists "$id" || die "no such task: $id"
+  jq -r --arg id "$id" '
+    .tasks[]|select(.id==$id)|.history[]
+    | "\(.at)\t\(.type)\t\(.fromStatus // "-") -> \(.toStatus // "-")\t\(.note // "")"
+  ' "$TASKS_FILE" | column -t -s $'\t'
+}
+
+cmd_raw() {
+  require_tasks_file
+  cat "$TASKS_FILE"
+}
+
+cmd_add() {
+  ensure_tasks_file
+  [[ $# -ge 2 ]] || die "usage: add <id> <title> [description]"
+  local id="$1" title="$2" desc="${3:-}"
+  task_exists "$id" && die "a task with this id already exists: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg title "$title" --arg desc "$desc" --arg now "$now" '
+    .updatedAt = $now
+    | .tasks += [{
+        id: $id,
+        title: $title,
+        description: $desc,
+        status: "todo",
+        priority: "normal",
+        module: "",
+        tags: [],
+        dependsOn: [],
+        source: "claude_code",
+        sourceEventId: null,
+        assignedAgentId: "main",
+        createdAt: $now,
+        updatedAt: $now,
+        playbookJobId: null,
+        runId: null,
+        channel: null,
+        externalThreadId: null,
+        lastActivityAt: $now,
+        notes: [],
+        isArchived: false,
+        isInferred: false,
+        history: [ { at: $now, type: "created", note: "Task created.", fromStatus: null, toStatus: "todo" } ]
+      }]'
+  emit_event "$id" "created" "$title"
+  echo "added: $id [todo]"
+}
+
+cmd_status() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: status <id> <status> [note]"
+  local id="$1" new="$2" note="${3:-}"
+  task_exists "$id" || die "no such task: $id"
+  is_valid_status "$new" || die "invalid status: $new (valid: $VALID_STATUSES)"
+  local now; now="$(now_iso)"
+  local notval="null"; [[ -n "$note" ]] && notval="\$note"
+  apply_jq --arg id "$id" --arg new "$new" --arg now "$now" --arg note "$note" "
+    .updatedAt = \$now
+    | (.tasks[] | select(.id==\$id)) |= (
+        .history += [ { at: \$now, type: \"status_changed\", note: $notval, fromStatus: .status, toStatus: \$new } ]
+        | .status = \$new
+        | .updatedAt = \$now
+        | .lastActivityAt = \$now
+      )"
+  emit_event "$id" "status:$new" "$note"
+  echo "status: $id -> $new"
+}
+
+cmd_note() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: note <id> <text>"
+  local id="$1" text="$2"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg text "$text" --arg now "$now" '
+    .updatedAt = $now
+    | (.tasks[] | select(.id==$id)) |= (
+        .notes += [ { at: $now, text: $text } ]
+        | .updatedAt = $now
+        | .lastActivityAt = $now
+      )'
+  emit_event "$id" "note" "$text"
+  echo "note appended: $id"
+}
+
+cmd_set() {
+  require_tasks_file
+  [[ $# -ge 3 ]] || die "usage: set <id> <field> <json-value>"
+  local id="$1" field="$2" value="$3"
+  task_exists "$id" || die "no such task: $id"
+  # Is the value valid JSON?
+  echo "$value" | jq -e . >/dev/null 2>&1 || die "value is not valid JSON: $value (quote strings: '\"text\"')"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg field "$field" --argjson value "$value" --arg now "$now" '
+    .updatedAt = $now
+    | (.tasks[] | select(.id==$id)) |= (
+        .[$field] = $value
+        | .updatedAt = $now
+        | .lastActivityAt = $now
+      )'
+  emit_event "$id" "set:$field" "$value"
+  echo "set: $id.$field"
+}
+
+cmd_archive() { _set_archived "$1" true; }
+cmd_unarchive() { _set_archived "$1" false; }
+_set_archived() {
+  require_tasks_file
+  local id="$1" val="$2"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --argjson val "$val" --arg now "$now" '
+    .updatedAt = $now
+    | (.tasks[] | select(.id==$id)) |= (.isArchived = $val | .updatedAt = $now)'
+  emit_event "$id" "archived:$val" ""
+  echo "isArchived=$val: $id"
+}
+
+cmd_rm() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: rm <id>"
+  local id="$1"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg now "$now" '
+    .updatedAt = $now | .tasks |= map(select(.id != $id))'
+  emit_event "$id" "removed" ""
+  echo "removed: $id"
+}
+
+# --- Structured fields: priority / tag / module / assign / dep ------------------------
+
+cmd_priority() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: priority <id> <low|normal|high|urgent>"
+  local id="$1" p="$2"
+  task_exists "$id" || die "no such task: $id"
+  local ok=0; for v in $VALID_PRIORITIES; do [[ "$p" == "$v" ]] && ok=1; done
+  [[ $ok == 1 ]] || die "invalid priority: $p (valid: $VALID_PRIORITIES)"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg p "$p" --arg now "$now" '
+    .updatedAt=$now
+    | (.tasks[]|select(.id==$id)) |= (.priority=$p | .updatedAt=$now | .lastActivityAt=$now)'
+  emit_event "$id" "priority:$p" ""
+  echo "priority: $id -> $p"
+}
+
+cmd_module() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: module <id> <module-name>  (empty string clears it)"
+  local id="$1" m="$2"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg m "$m" --arg now "$now" '
+    .updatedAt=$now
+    | (.tasks[]|select(.id==$id)) |= (.module=$m | .updatedAt=$now | .lastActivityAt=$now)'
+  emit_event "$id" "module:$m" ""
+  echo "module: $id -> ${m:-<cleared>}"
+}
+
+cmd_tag() {
+  require_tasks_file
+  [[ $# -ge 3 ]] || die "usage: tag <id> <add|rm> <label>"
+  local id="$1" op="$2" t="$3"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  case "$op" in
+    add) apply_jq --arg id "$id" --arg t "$t" --arg now "$now" '
+        .updatedAt=$now
+        | (.tasks[]|select(.id==$id)) |= (.tags = (((.tags//[]) + [$t]) | unique) | .updatedAt=$now | .lastActivityAt=$now)'
+      echo "label added: $id +$t" ;;
+    rm)  apply_jq --arg id "$id" --arg t "$t" --arg now "$now" '
+        .updatedAt=$now
+        | (.tasks[]|select(.id==$id)) |= (.tags = ((.tags//[]) - [$t]) | .updatedAt=$now | .lastActivityAt=$now)'
+      echo "label removed: $id -$t" ;;
+    *) die "unknown tag operation: $op (add|rm)" ;;
+  esac
+  emit_event "$id" "tag:$op" "$t"
+}
+
+cmd_assign() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: assign <id> <agent>"
+  local id="$1" agent="$2"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg a "$agent" --arg now "$now" '
+    .updatedAt=$now
+    | (.tasks[]|select(.id==$id)) |= (.assignedAgentId=$a | .updatedAt=$now | .lastActivityAt=$now)'
+  emit_event "$id" "assign" "$agent"
+  echo "assigned: $id -> $agent"
+}
+
+cmd_dep() {
+  require_tasks_file
+  [[ $# -ge 3 ]] || die "usage: dep <id> <add|rm> <other-id>"
+  local id="$1" op="$2" other="$3"
+  task_exists "$id" || die "no such task: $id"
+  local now; now="$(now_iso)"
+  case "$op" in
+    add)
+      [[ "$id" == "$other" ]] && die "a task cannot depend on itself: $id"
+      task_exists "$other" || die "no such task (dependency): $other"
+      # Forbid a direct cycle: if 'other' already depends on 'id'.
+      local rev; rev="$(jq -r --arg o "$other" --arg id "$id" \
+        '[.tasks[]|select(.id==$o)|(.dependsOn//[])[]]|index($id)' "$TASKS_FILE")"
+      [[ "$rev" != "null" ]] && die "cyclic dependency: $other already depends on: $id"
+      apply_jq --arg id "$id" --arg o "$other" --arg now "$now" '
+        .updatedAt=$now
+        | (.tasks[]|select(.id==$id)) |= (.dependsOn = (((.dependsOn//[]) + [$o]) | unique) | .updatedAt=$now | .lastActivityAt=$now)'
+      emit_event "$id" "dep:add" "$other"
+      echo "dependency: $id ⛔ waits on: $other" ;;
+    rm)
+      apply_jq --arg id "$id" --arg o "$other" --arg now "$now" '
+        .updatedAt=$now
+        | (.tasks[]|select(.id==$id)) |= (.dependsOn = ((.dependsOn//[]) - [$o]) | .updatedAt=$now | .lastActivityAt=$now)'
+      emit_event "$id" "dep:rm" "$other"
+      echo "dependency removed: $id -$other" ;;
+    *) die "unknown dep operation: $op (add|rm)" ;;
+  esac
+}
+
+cmd_deps() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: deps <id>"
+  local id="$1"
+  task_exists "$id" || die "no such task: $id"
+  jq -r --arg id "$id" '
+    . as $root
+    | def stat($i): ($root.tasks[]|select(.id==$i)|.status) // "?";
+      ($root.tasks[]|select(.id==$id)) as $t
+    | "Task: \($id) [\($t.status)]",
+      "",
+      "Waiting on (dependsOn):",
+      ( if (($t.dependsOn//[])|length)==0 then "  – none"
+        else ($t.dependsOn[] | "  \(.) [\(stat(.))]") end ),
+      "",
+      "Blocks (referenced by):",
+      ( [ $root.tasks[] | select(((.dependsOn//[])|index($id)) != null) | "  \(.id) [\(.status)]" ]
+        | if length==0 then "  – none" else .[] end )
+  ' "$TASKS_FILE"
+}
+
+cmd_next() {
+  require_tasks_file
+  jq -r '
+    . as $root
+    | def doneish($i): ($root.tasks[]|select(.id==$i)) as $d
+        | ($d==null) or ($d.status=="done") or ($d.isArchived==true);
+      def prio_rank: {"urgent":0,"high":1,"normal":2,"low":3}[(.priority//"normal")] // 2;
+      [ $root.tasks[]
+        | select((.isArchived//false)|not)
+        | select(.status=="todo")
+        | select( ((.dependsOn//[]) | map(doneish(.)) | all) ) ]
+      | sort_by(prio_rank, .createdAt)
+      | if length==0 then "no available todo (all blocked, done, or none exist)"
+        else (.[] | "\(.id)\t[\(.priority//"normal")]\t\(.title)") end
+  ' "$TASKS_FILE" | column -t -s $'\t'
+}
+
+cmd_reopen() {
+  require_tasks_file
+  [[ $# -ge 1 ]] || die "usage: reopen <id> [status=todo]"
+  local id="$1" new="${2:-todo}"
+  task_exists "$id" || die "no such task: $id"
+  is_valid_status "$new" || die "invalid status: $new (valid: $VALID_STATUSES)"
+  local now; now="$(now_iso)"
+  apply_jq --arg id "$id" --arg new "$new" --arg now "$now" '
+    .updatedAt=$now
+    | (.tasks[]|select(.id==$id)) |= (
+        .history += [{at:$now, type:"reopened", note:"Task reopened.", fromStatus:.status, toStatus:$new}]
+        | .status=$new | .isArchived=false | .updatedAt=$now | .lastActivityAt=$now)'
+  emit_event "$id" "status:$new" "reopened"
+  echo "reopened: $id -> $new"
+}
+
+cmd_status_many() {
+  require_tasks_file
+  [[ $# -ge 2 ]] || die "usage: status-many <status> <id> [id...]"
+  local new="$1"; shift
+  is_valid_status "$new" || die "invalid status: $new (valid: $VALID_STATUSES)"
+  local id
+  for id in "$@"; do task_exists "$id" || die "no such task: $id"; done
+  local ids_json; ids_json="$(printf '%s\n' "$@" | jq -R . | jq -s .)"
+  local now; now="$(now_iso)"
+  apply_jq --arg new "$new" --arg now "$now" --argjson ids "$ids_json" '
+    .updatedAt=$now
+    | (.tasks[] | select((.id as $i | $ids | index($i)) != null)) |= (
+        .history += [{at:$now, type:"status_changed", note:null, fromStatus:.status, toStatus:$new}]
+        | .status=$new | .updatedAt=$now | .lastActivityAt=$now)'
+  for id in "$@"; do emit_event "$id" "status:$new" ""; done
+  echo "status (bulk): $* -> $new"
+}
+
+# --- Robustness: validate / restore ----------------------------------------
+
+cmd_validate() {
+  require_tasks_file
+  jq -e . "$TASKS_FILE" >/dev/null 2>&1 || { echo "VALIDATION: FAILED – invalid JSON"; return 1; }
+  local report
+  report="$(jq -r --arg statuses "$VALID_STATUSES" --arg prios "$VALID_PRIORITIES" '
+    ($statuses|split(" ")) as $vs
+    | ($prios|split(" ")) as $vp
+    | ([.tasks[].id]) as $ids
+    | ( [ .tasks[]
+          | . as $t
+          | ( if ($t.id//"")=="" then "a task has an empty/missing id" else empty end ),
+            ( if ($t.title//"")=="" then "\($t.id): missing title" else empty end ),
+            ( if ($vs|index($t.status)) then empty else "\($t.id): invalid status: \($t.status)" end ),
+            ( if (($t.priority//"normal") as $p | $vp|index($p)) then empty else "\($t.id): invalid priority: \($t.priority)" end ),
+            ( ($t.dependsOn//[])[] as $d | select(($ids|index($d))==null) | "\($t.id): broken dependency -> \($d)" )
+        ] )
+    + ( [.tasks[].id] | group_by(.) | map(select(length>1)|.[0]) | map("duplicate id: \(.)") )
+    | .[]
+  ' "$TASKS_FILE")"
+  if [[ -n "$report" ]]; then
+    echo "$report"
+    echo "─"
+    echo "VALIDATION: FAILED ($(printf '%s\n' "$report" | grep -c . ) issue(s))"
+    return 1
+  fi
+  echo "VALIDATION: OK ($(jq '.tasks|length' "$TASKS_FILE") task(s))"
+}
+
+cmd_restore() {
+  [[ -f "$BACKUP_FILE" ]] || die "no backup: $BACKUP_FILE"
+  acquire_lock
+  [[ -f "$TASKS_FILE" ]] && cp "$TASKS_FILE" "$TASKS_FILE.prerestore" 2>/dev/null || true
+  cp "$BACKUP_FILE" "$TASKS_FILE"
+  release_lock
+  echo "restored from backup: $BACKUP_FILE -> $TASKS_FILE (previous: $TASKS_FILE.prerestore)"
+}
+
+# --- Inbox: per-agent, deduplicated event notification ---------------------------
+# `inbox <agent>`: returns events generated by OTHER agents since <agent>'s cursor (not its
+# own), then advances the cursor. SILENT if there's nothing new (empty output) — so the hook
+# only injects when there's something to inject. On first connect it does NOT dump the whole
+# past: the cursor is set to the current end, and only events from then on are returned. The
+# caller agent is supplied by the PostToolUse hook (from the --as flag); this command itself
+# does NOT require --as.
+cmd_inbox() {
+  [[ $# -ge 1 ]] || die "usage: inbox <agent>"
+  local agent="$1"
+  [[ -f "$EVENTS_FILE" ]] || return 0
+  local maxseq; maxseq="$(wc -l < "$EVENTS_FILE" 2>/dev/null | tr -d ' ')"
+  [[ -z "$maxseq" ]] && maxseq=0
+  mkdir -p "$CURSORS_DIR" 2>/dev/null || true
+  # Filename-safe cursor key (agent names are typically [A-Za-z0-9_-], but be defensive).
+  local safe; safe="$(printf '%s' "$agent" | tr -c 'A-Za-z0-9_.-' '_')"
+  local cursor_file="$CURSORS_DIR/$safe"
+  if [[ ! -f "$cursor_file" ]]; then
+    printf '%s\n' "$maxseq" > "$cursor_file" 2>/dev/null || true
+    return 0
+  fi
+  local seen; seen="$(cat "$cursor_file" 2>/dev/null || echo 0)"
+  [[ "$seen" =~ ^[0-9]+$ ]] || seen=0
+  # Advance the cursor first (so we don't loop on our own events either), then filter.
+  printf '%s\n' "$maxseq" > "$cursor_file" 2>/dev/null || true
+  jq -r --argjson seen "$seen" --arg me "$agent" '
+      select(.seq > $seen and .by != $me)
+      | "📬 [\(.task)] \(.by) → \(.kind)" + (if ((.text//"")|length)==0 then "" else ": \(.text)" end)
+    ' "$EVENTS_FILE" 2>/dev/null || true
+}
+
+# ---------------------------------------------------------------------------
+# Commands — context.json (session continuity)
+# ---------------------------------------------------------------------------
+# context.json must ALSO only be written through these commands (never direct
+# Read/Write/Edit), so there's a single atomic writer for both stores.
+
+cmd_ctx() {  # the whole context.json (small, cheap to read)
+  require_context_file
+  cat "$CONTEXT_FILE"
+}
+
+cmd_ctx_init() {
+  local init="${1:-}" goal="${2:-}"
+  if [[ -f "$CONTEXT_FILE" ]]; then
+    echo "already exists: $CONTEXT_FILE"
+    return 0
+  fi
+  ensure_context_file
+  local now; now="$(now_iso)"
+  apply_ctx --arg init "$init" --arg goal "$goal" --arg now "$now" \
+    '.updatedAt=$now | .initPrompt=$init | .goal=$goal'
+  echo "done: $CONTEXT_FILE"
+}
+
+cmd_ctx_set() {
+  ensure_context_file
+  [[ $# -ge 2 ]] || die "usage: ctx-set <field> <json-value>"
+  local field="$1" value="$2"
+  echo "$value" | jq -e . >/dev/null 2>&1 \
+    || die "value is not valid JSON: $value (quote strings: '\"text\"')"
+  local now; now="$(now_iso)"
+  apply_ctx --arg field "$field" --argjson value "$value" --arg now "$now" \
+    '.updatedAt=$now | .[$field]=$value'
+  echo "context set: $field"
+}
+
+cmd_ctx_decision() {
+  ensure_context_file
+  [[ $# -ge 2 ]] || die "usage: ctx-decision <topic> <decision> [rationale]"
+  local topic="$1" decision="$2" rationale="${3:-}"
+  local now; now="$(now_iso)"
+  apply_ctx --arg topic "$topic" --arg decision "$decision" \
+            --arg rationale "$rationale" --arg now "$now" \
+    '.updatedAt=$now
+     | .decisions += [{at:$now, topic:$topic, decision:$decision, rationale:$rationale}]'
+  echo "decision recorded: $topic"
+}
+
+cmd_ctx_constraint() {
+  ensure_context_file
+  [[ $# -ge 1 ]] || die "usage: ctx-constraint <text>"
+  local text="$1"
+  local now; now="$(now_iso)"
+  apply_ctx --arg text "$text" --arg now "$now" \
+    '.updatedAt=$now | .constraints += [$text]'
+  echo "constraint added"
+}
+
+cmd_ctx_question() {
+  ensure_context_file
+  [[ $# -ge 2 ]] || die "usage: ctx-question <add|rm> <text>"
+  local op="$1" text="$2"
+  local now; now="$(now_iso)"
+  case "$op" in
+    add)
+      apply_ctx --arg text "$text" --arg now "$now" \
+        '.updatedAt=$now | .openQuestions += [$text]'
+      echo "open question added" ;;
+    rm|resolve)
+      apply_ctx --arg text "$text" --arg now "$now" \
+        '.updatedAt=$now | .openQuestions |= map(select(. != $text))'
+      echo "question resolved" ;;
+    *) die "unknown ctx-question operation: $op (add|rm)" ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+# Commands for which --as is NOT required (meta / diagnostic / called by the hook itself).
+# Every other command REQUIRES --as <agent> (identifies the caller, so the hook can inject
+# the right inbox, and emit_event records it as `by`).
+actor_optional() {
+  case "$1" in
+    help|-h|--help|inbox|init|validate|check|restore|raw) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Prints a reminder (stderr) of the project's preferred language, set from the board's
+# current UI language (api/index.php writes it to $TM_DIR/.board-lang on every write — see
+# ApiClient.js). Deliberately NOT stored in any task/note: this is board-level state, read
+# fresh on every task.sh invocation, so whichever agent runs the command next sees it.
+# Skipped for help/inbox to avoid noise on the hook's own (very frequent) inbox lookups.
+print_lang_hint() {
+  case "$1" in
+    help|-h|--help|inbox) return 0 ;;
+  esac
+  local f="$TM_DIR/.board-lang" lang
+  [[ -f "$f" ]] || return 0
+  lang="$(tr -d '[:space:]' < "$f" 2>/dev/null)"
+  case "$lang" in
+    hu) echo "[task-manager] Preferred language for this project: Hungarian — please reply and do the work in Hungarian." >&2 ;;
+  esac
+}
+
+main() {
+  local cmd="${1:-help}"
+  shift || true
+  print_lang_hint "$cmd"
+
+  # Extract --as <agent> from ANYWHERE in the arguments; the rest goes into array A.
+  local -a A=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --as) ACTOR="${2:-}"; shift 2 || shift ;;
+      --as=*) ACTOR="${1#--as=}"; shift ;;
+      *) A+=("$1"); shift ;;
+    esac
+  done
+
+  # Require --as (except for meta commands). This way the hook always knows the caller,
+  # and every event is written with a `by`.
+  if ! actor_optional "$cmd"; then
+    [[ -n "$ACTOR" ]] || die "--as <agent> is required (e.g. --as main). Command: $cmd"
+  fi
+
+  # "${A[@]}" would throw 'unbound variable' under bash 3.2 (macOS) + set -u when empty;
+  # the ${A[@]+...} guard avoids that.
+  set -- ${A[@]+"${A[@]}"}
+
+  case "$cmd" in
+    help|-h|--help) cmd_help ;;
+    inbox)     cmd_inbox "$@" ;;
+    init)      cmd_init "$@" ;;
+    list|ls)   cmd_list "$@" ;;
+    ids)       cmd_ids "$@" ;;
+    get)       cmd_get "$@" ;;
+    field)     cmd_field "$@" ;;
+    summary)   cmd_summary "$@" ;;
+    find)      cmd_find "$@" ;;
+    history)   cmd_history "$@" ;;
+    raw)       cmd_raw "$@" ;;
+    next)      cmd_next "$@" ;;
+    deps)      cmd_deps "$@" ;;
+    validate|check) cmd_validate "$@" ;;
+    add)       cmd_add "$@" ;;
+    status)    cmd_status "$@" ;;
+    status-many|status-multi) cmd_status_many "$@" ;;
+    reopen)    cmd_reopen "$@" ;;
+    note)      cmd_note "$@" ;;
+    set)       cmd_set "$@" ;;
+    priority|prio) cmd_priority "$@" ;;
+    module|mod) cmd_module "$@" ;;
+    tag)       cmd_tag "$@" ;;
+    assign)    cmd_assign "$@" ;;
+    dep)       cmd_dep "$@" ;;
+    archive)   cmd_archive "$@" ;;
+    unarchive) cmd_unarchive "$@" ;;
+    restore)   cmd_restore "$@" ;;
+    rm|remove) cmd_rm "$@" ;;
+    ctx|context)    cmd_ctx "$@" ;;
+    ctx-init)       cmd_ctx_init "$@" ;;
+    ctx-set)        cmd_ctx_set "$@" ;;
+    ctx-decision)   cmd_ctx_decision "$@" ;;
+    ctx-constraint) cmd_ctx_constraint "$@" ;;
+    ctx-question)   cmd_ctx_question "$@" ;;
+    *) die "unknown command: $cmd (help: task.sh help)" ;;
+  esac
+}
+
+main "$@"