@etiquekit/etq 0.0.1 → 1.0.1

package/templates/etiquette-vanilla-v0/source/control-seat/bin/hooks/post-tool-use

@@ -0,0 +1,64 @@
+#!/bin/sh
+# bin/hooks/post-tool-use — Etiquette Hook Adapter v0.1
+# Maps runtime lifecycle event to etiquette `hook post_tool_use`.
+#
+# DISABLED BY DEFAULT. Enable with:
+#   export ETIQUETTE_HOOKS_ENABLED=1
+#   export ETIQUETTE_WORKSPACE_ID=<opaque-workspace-id>
+#   export ETIQUETTE_CLI_SCRIPT=/path/to/etiquette/packages/control/src/cli.ts
+#
+# Optional input:
+#   stdin or $ETIQUETTE_HOOK_PAYLOAD = JSON object payload (sanitized server-side)
+#
+# Contract:
+#   - disabled-by-default: silent exit 0 when not opted in
+#   - fast-fail: any error is swallowed; never blocks the operator
+#   - non-authoritative: writes per-workspace outbox only; no ledger writes
+set -eu
+
+if [ "${ETIQUETTE_HOOKS_ENABLED:-0}" != "1" ]; then
+  exit 0
+fi
+
+CLI_BIN=${ETIQUETTE_CLI_BIN:-bun}
+CLI_SCRIPT=${ETIQUETTE_CLI_SCRIPT:-}
+
+if [ -z "$CLI_SCRIPT" ] || [ ! -f "$CLI_SCRIPT" ]; then
+  # hook enabled but no cli script located; non-blocking exit
+  exit 0
+fi
+
+# Payload via env var (preferred) or stdin
+if [ -n "${ETIQUETTE_HOOK_PAYLOAD:-}" ]; then
+  payload=$ETIQUETTE_HOOK_PAYLOAD
+elif [ ! -t 0 ]; then
+  payload=$(cat)
+else
+  payload='{}'
+fi
+
+if [ -n "${ETIQUETTE_WORKSPACE_ID:-}" ]; then
+  set -- hook post_tool_use --workspace "$ETIQUETTE_WORKSPACE_ID" --payload "$payload"
+else
+  set -- hook post_tool_use --payload "$payload"
+fi
+
+timeout_seconds=${ETIQUETTE_HOOK_TIMEOUT_SECONDS:-2}
+case "$timeout_seconds" in
+  ''|*[!0-9]*) timeout_seconds=2 ;;
+esac
+
+# Run with timeout safety. Output goes to /dev/null so a hook never pollutes the
+# runtime's stdout, and timeout/failure never blocks the operator.
+(
+  "$CLI_BIN" "$CLI_SCRIPT" "$@" >/dev/null 2>&1
+) &
+hook_pid=$!
+(
+  sleep "$timeout_seconds"
+  kill "$hook_pid" 2>/dev/null || true
+) &
+watchdog_pid=$!
+wait "$hook_pid" 2>/dev/null || true
+kill "$watchdog_pid" 2>/dev/null || true
+exit 0

package/templates/etiquette-vanilla-v0/source/control-seat/bin/hooks/session-end

@@ -0,0 +1,64 @@
+#!/bin/sh
+# bin/hooks/session-end — Etiquette Hook Adapter v0.1
+# Maps runtime lifecycle event to etiquette `hook session_end`.
+#
+# DISABLED BY DEFAULT. Enable with:
+#   export ETIQUETTE_HOOKS_ENABLED=1
+#   export ETIQUETTE_WORKSPACE_ID=<opaque-workspace-id>
+#   export ETIQUETTE_CLI_SCRIPT=/path/to/etiquette/packages/control/src/cli.ts
+#
+# Optional input:
+#   stdin or $ETIQUETTE_HOOK_PAYLOAD = JSON object payload (sanitized server-side)
+#
+# Contract:
+#   - disabled-by-default: silent exit 0 when not opted in
+#   - fast-fail: any error is swallowed; never blocks the operator
+#   - non-authoritative: writes per-workspace outbox only; no ledger writes
+set -eu
+
+if [ "${ETIQUETTE_HOOKS_ENABLED:-0}" != "1" ]; then
+  exit 0
+fi
+
+CLI_BIN=${ETIQUETTE_CLI_BIN:-bun}
+CLI_SCRIPT=${ETIQUETTE_CLI_SCRIPT:-}
+
+if [ -z "$CLI_SCRIPT" ] || [ ! -f "$CLI_SCRIPT" ]; then
+  # hook enabled but no cli script located; non-blocking exit
+  exit 0
+fi
+
+# Payload via env var (preferred) or stdin
+if [ -n "${ETIQUETTE_HOOK_PAYLOAD:-}" ]; then
+  payload=$ETIQUETTE_HOOK_PAYLOAD
+elif [ ! -t 0 ]; then
+  payload=$(cat)
+else
+  payload='{}'
+fi
+
+if [ -n "${ETIQUETTE_WORKSPACE_ID:-}" ]; then
+  set -- hook session_end --workspace "$ETIQUETTE_WORKSPACE_ID" --payload "$payload"
+else
+  set -- hook session_end --payload "$payload"
+fi
+
+timeout_seconds=${ETIQUETTE_HOOK_TIMEOUT_SECONDS:-2}
+case "$timeout_seconds" in
+  ''|*[!0-9]*) timeout_seconds=2 ;;
+esac
+
+# Run with timeout safety. Output goes to /dev/null so a hook never pollutes the
+# runtime's stdout, and timeout/failure never blocks the operator.
+(
+  "$CLI_BIN" "$CLI_SCRIPT" "$@" >/dev/null 2>&1
+) &
+hook_pid=$!
+(
+  sleep "$timeout_seconds"
+  kill "$hook_pid" 2>/dev/null || true
+) &
+watchdog_pid=$!
+wait "$hook_pid" 2>/dev/null || true
+kill "$watchdog_pid" 2>/dev/null || true
+exit 0

package/templates/etiquette-vanilla-v0/source/control-seat/bin/hooks/session-start

@@ -0,0 +1,64 @@
+#!/bin/sh
+# bin/hooks/session-start — Etiquette Hook Adapter v0.1
+# Maps runtime lifecycle event to etiquette `hook session_start`.
+#
+# DISABLED BY DEFAULT. Enable with:
+#   export ETIQUETTE_HOOKS_ENABLED=1
+#   export ETIQUETTE_WORKSPACE_ID=<opaque-workspace-id>
+#   export ETIQUETTE_CLI_SCRIPT=/path/to/etiquette/packages/control/src/cli.ts
+#
+# Optional input:
+#   stdin or $ETIQUETTE_HOOK_PAYLOAD = JSON object payload (sanitized server-side)
+#
+# Contract:
+#   - disabled-by-default: silent exit 0 when not opted in
+#   - fast-fail: any error is swallowed; never blocks the operator
+#   - non-authoritative: writes per-workspace outbox only; no ledger writes
+set -eu
+
+if [ "${ETIQUETTE_HOOKS_ENABLED:-0}" != "1" ]; then
+  exit 0
+fi
+
+CLI_BIN=${ETIQUETTE_CLI_BIN:-bun}
+CLI_SCRIPT=${ETIQUETTE_CLI_SCRIPT:-}
+
+if [ -z "$CLI_SCRIPT" ] || [ ! -f "$CLI_SCRIPT" ]; then
+  # hook enabled but no cli script located; non-blocking exit
+  exit 0
+fi
+
+# Payload via env var (preferred) or stdin
+if [ -n "${ETIQUETTE_HOOK_PAYLOAD:-}" ]; then
+  payload=$ETIQUETTE_HOOK_PAYLOAD
+elif [ ! -t 0 ]; then
+  payload=$(cat)
+else
+  payload='{}'
+fi
+
+if [ -n "${ETIQUETTE_WORKSPACE_ID:-}" ]; then
+  set -- hook session_start --workspace "$ETIQUETTE_WORKSPACE_ID" --payload "$payload"
+else
+  set -- hook session_start --payload "$payload"
+fi
+
+timeout_seconds=${ETIQUETTE_HOOK_TIMEOUT_SECONDS:-2}
+case "$timeout_seconds" in
+  ''|*[!0-9]*) timeout_seconds=2 ;;
+esac
+
+# Run with timeout safety. Output goes to /dev/null so a hook never pollutes the
+# runtime's stdout, and timeout/failure never blocks the operator.
+(
+  "$CLI_BIN" "$CLI_SCRIPT" "$@" >/dev/null 2>&1
+) &
+hook_pid=$!
+(
+  sleep "$timeout_seconds"
+  kill "$hook_pid" 2>/dev/null || true
+) &
+watchdog_pid=$!
+wait "$hook_pid" 2>/dev/null || true
+kill "$watchdog_pid" 2>/dev/null || true
+exit 0

package/templates/etiquette-vanilla-v0/source/control-seat/bin/hooks/stop

@@ -0,0 +1,64 @@
+#!/bin/sh
+# bin/hooks/stop — Etiquette Hook Adapter v0.1
+# Maps runtime lifecycle event to etiquette `hook stop`.
+#
+# DISABLED BY DEFAULT. Enable with:
+#   export ETIQUETTE_HOOKS_ENABLED=1
+#   export ETIQUETTE_WORKSPACE_ID=<opaque-workspace-id>
+#   export ETIQUETTE_CLI_SCRIPT=/path/to/etiquette/packages/control/src/cli.ts
+#
+# Optional input:
+#   stdin or $ETIQUETTE_HOOK_PAYLOAD = JSON object payload (sanitized server-side)
+#
+# Contract:
+#   - disabled-by-default: silent exit 0 when not opted in
+#   - fast-fail: any error is swallowed; never blocks the operator
+#   - non-authoritative: writes per-workspace outbox only; no ledger writes
+set -eu
+
+if [ "${ETIQUETTE_HOOKS_ENABLED:-0}" != "1" ]; then
+  exit 0
+fi
+
+CLI_BIN=${ETIQUETTE_CLI_BIN:-bun}
+CLI_SCRIPT=${ETIQUETTE_CLI_SCRIPT:-}
+
+if [ -z "$CLI_SCRIPT" ] || [ ! -f "$CLI_SCRIPT" ]; then
+  # hook enabled but no cli script located; non-blocking exit
+  exit 0
+fi
+
+# Payload via env var (preferred) or stdin
+if [ -n "${ETIQUETTE_HOOK_PAYLOAD:-}" ]; then
+  payload=$ETIQUETTE_HOOK_PAYLOAD
+elif [ ! -t 0 ]; then
+  payload=$(cat)
+else
+  payload='{}'
+fi
+
+if [ -n "${ETIQUETTE_WORKSPACE_ID:-}" ]; then
+  set -- hook stop --workspace "$ETIQUETTE_WORKSPACE_ID" --payload "$payload"
+else
+  set -- hook stop --payload "$payload"
+fi
+
+timeout_seconds=${ETIQUETTE_HOOK_TIMEOUT_SECONDS:-2}
+case "$timeout_seconds" in
+  ''|*[!0-9]*) timeout_seconds=2 ;;
+esac
+
+# Run with timeout safety. Output goes to /dev/null so a hook never pollutes the
+# runtime's stdout, and timeout/failure never blocks the operator.
+(
+  "$CLI_BIN" "$CLI_SCRIPT" "$@" >/dev/null 2>&1
+) &
+hook_pid=$!
+(
+  sleep "$timeout_seconds"
+  kill "$hook_pid" 2>/dev/null || true
+) &
+watchdog_pid=$!
+wait "$hook_pid" 2>/dev/null || true
+kill "$watchdog_pid" 2>/dev/null || true
+exit 0

package/templates/etiquette-vanilla-v0/source/control-seat/bin/hooks/user-prompt-submit

@@ -0,0 +1,64 @@
+#!/bin/sh
+# bin/hooks/user-prompt-submit — Etiquette Hook Adapter v0.1
+# Maps runtime lifecycle event to etiquette `hook user_prompt_submit`.
+#
+# DISABLED BY DEFAULT. Enable with:
+#   export ETIQUETTE_HOOKS_ENABLED=1
+#   export ETIQUETTE_WORKSPACE_ID=<opaque-workspace-id>
+#   export ETIQUETTE_CLI_SCRIPT=/path/to/etiquette/packages/control/src/cli.ts
+#
+# Optional input:
+#   stdin or $ETIQUETTE_HOOK_PAYLOAD = JSON object payload (sanitized server-side)
+#
+# Contract:
+#   - disabled-by-default: silent exit 0 when not opted in
+#   - fast-fail: any error is swallowed; never blocks the operator
+#   - non-authoritative: writes per-workspace outbox only; no ledger writes
+set -eu
+
+if [ "${ETIQUETTE_HOOKS_ENABLED:-0}" != "1" ]; then
+  exit 0
+fi
+
+CLI_BIN=${ETIQUETTE_CLI_BIN:-bun}
+CLI_SCRIPT=${ETIQUETTE_CLI_SCRIPT:-}
+
+if [ -z "$CLI_SCRIPT" ] || [ ! -f "$CLI_SCRIPT" ]; then
+  # hook enabled but no cli script located; non-blocking exit
+  exit 0
+fi
+
+# Payload via env var (preferred) or stdin
+if [ -n "${ETIQUETTE_HOOK_PAYLOAD:-}" ]; then
+  payload=$ETIQUETTE_HOOK_PAYLOAD
+elif [ ! -t 0 ]; then
+  payload=$(cat)
+else
+  payload='{}'
+fi
+
+if [ -n "${ETIQUETTE_WORKSPACE_ID:-}" ]; then
+  set -- hook user_prompt_submit --workspace "$ETIQUETTE_WORKSPACE_ID" --payload "$payload"
+else
+  set -- hook user_prompt_submit --payload "$payload"
+fi
+
+timeout_seconds=${ETIQUETTE_HOOK_TIMEOUT_SECONDS:-2}
+case "$timeout_seconds" in
+  ''|*[!0-9]*) timeout_seconds=2 ;;
+esac
+
+# Run with timeout safety. Output goes to /dev/null so a hook never pollutes the
+# runtime's stdout, and timeout/failure never blocks the operator.
+(
+  "$CLI_BIN" "$CLI_SCRIPT" "$@" >/dev/null 2>&1
+) &
+hook_pid=$!
+(
+  sleep "$timeout_seconds"
+  kill "$hook_pid" 2>/dev/null || true
+) &
+watchdog_pid=$!
+wait "$hook_pid" 2>/dev/null || true
+kill "$watchdog_pid" 2>/dev/null || true
+exit 0

package/templates/etiquette-vanilla-v0/source/control-seat/bin/local-event

@@ -0,0 +1,53 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ "$#" -lt 4 ]; then
+  echo "usage: sh bin/local-event <task-id> <actor> <action> <message...>" >&2
+  exit 2
+fi
+
+task_id=$1
+actor=$2
+action=$3
+shift 3
+message=$*
+
+event_log=${ETIQUETTE_EVENT_LOG:-"$ROOT/.etiquette/events/local.ndjson"}
+event_dir=$(dirname -- "$event_log")
+mkdir -p "$event_dir"
+
+lock_dir="$event_dir/.local-event.lock"
+lock_attempts=0
+while ! mkdir "$lock_dir" 2>/dev/null; do
+  lock_attempts=$((lock_attempts + 1))
+  if [ "$lock_attempts" -ge 100 ]; then
+    echo "timed out waiting for local event lock: $lock_dir" >&2
+    exit 1
+  fi
+  sleep 0.05
+done
+trap 'rmdir "$lock_dir" 2>/dev/null || true' EXIT INT TERM
+
+if [ -f "$event_log" ]; then
+  seq=$(wc -l < "$event_log" | tr -d ' ')
+else
+  seq=0
+fi
+seq=$((seq + 1))
+at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+task_id_json=$(json_escape "$task_id")
+actor_json=$(json_escape "$actor")
+action_json=$(json_escape "$action")
+message_json=$(json_escape "$message")
+
+printf '{"seq":%s,"at":"%s","task_id":"%s","actor":"%s","action":"%s","message":"%s"}\n' \
+  "$seq" "$at" "$task_id_json" "$actor_json" "$action_json" "$message_json" >> "$event_log"
+
+printf 'event: %s seq:%s\n' "$event_log" "$seq"

package/templates/etiquette-vanilla-v0/source/control-seat/bin/post-receipt

@@ -0,0 +1,143 @@
+#!/bin/sh
+# post-receipt: push a receipt METADATA pointer to the hosted plane.
+#
+# Per hosted-plane-boundary.v0 — content stays in the repo; only the
+# pointer (task_id / seat_id / status / artifact_ref / receipt_ref /
+# validation_summary capped) is sent.  Sanitisers reject path/hostname/IP
+# leakage in the refs.
+#
+# Usage:
+#   sh bin/post-receipt --task-id DEMO-001 --status success \
+#     --artifact-ref repo:main --receipt-ref docs/work/receipts/DEMO-001.md \
+#     --validation-summary "product-doctor: ok"
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+# shellcheck source=_lib/sanitize.sh
+. "$ROOT/bin/_lib/sanitize.sh"
+# shellcheck source=_lib/state.sh
+. "$ROOT/bin/_lib/state.sh"
+# shellcheck source=_lib/http.sh
+. "$ROOT/bin/_lib/http.sh"
+
+ALLOWED_STATUSES="success partial blocked failed"
+
+task_id=""
+status=""
+artifact_ref=""
+receipt_ref=""
+validation_summary=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --task-id) task_id=$2; shift 2 ;;
+    --status) status=$2; shift 2 ;;
+    --artifact-ref) artifact_ref=$2; shift 2 ;;
+    --receipt-ref) receipt_ref=$2; shift 2 ;;
+    --validation-summary) validation_summary=$2; shift 2 ;;
+    -h|--help)
+      cat <<EOF
+post-receipt — push a receipt metadata pointer
+
+  sh bin/post-receipt --task-id <id> --status <s> \\
+    [--artifact-ref <ref>] [--receipt-ref <repo-relative-path>] \\
+    [--validation-summary <≤200 chars>]
+
+Status (4):
+$(printf '  - %s\n' $ALLOWED_STATUSES)
+
+Requires seat-consume-pass to have populated workspace.json.
+Only metadata flows over the wire; receipt body stays in your repo.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$task_id" ] || { echo "post-receipt: --task-id required" >&2; exit 2; }
+[ -n "$status" ] || { echo "post-receipt: --status required" >&2; exit 2; }
+
+# Status allowlist.
+ok=0
+for s in $ALLOWED_STATUSES; do
+  if [ "$s" = "$status" ]; then ok=1; break; fi
+done
+if [ "$ok" -ne 1 ]; then
+  printf 'post-receipt: --status "%s" not in allowlist:\n' "$status" >&2
+  printf '  - %s\n' $ALLOWED_STATUSES >&2
+  exit 2
+fi
+
+# task_id length cap (defence; api caps at 128).
+if [ "${#task_id}" -gt 128 ]; then
+  echo "post-receipt: --task-id length > 128" >&2
+  exit 2
+fi
+
+# Sanitise optional refs.
+clean_artifact=""
+if [ -n "$artifact_ref" ]; then
+  if ! clean_artifact=$(etq_sanitize_artifact_ref "$artifact_ref"); then
+    echo "post-receipt: --artifact-ref rejected" >&2
+    exit 2
+  fi
+fi
+clean_receipt=""
+if [ -n "$receipt_ref" ]; then
+  if ! clean_receipt=$(etq_sanitize_repo_relative "$receipt_ref"); then
+    echo "post-receipt: --receipt-ref rejected" >&2
+    exit 2
+  fi
+fi
+# Validation summary cap at 200 chars (server also enforces).
+if [ "${#validation_summary}" -gt 200 ]; then
+  validation_summary=$(printf '%s' "$validation_summary" | cut -c1-200)
+fi
+
+# Load workspace.json.
+workspace_file=$(etq_state_workspace_path)
+if [ ! -f "$workspace_file" ]; then
+  echo "post-receipt: workspace.json missing — run \`sh bin/seat-consume-pass --pass-id <id>\` first" >&2
+  exit 1
+fi
+workspace_id=$(etq_state_read_key "$workspace_file" workspace_id) || exit 1
+pass_id=$(etq_state_read_key "$workspace_file" pass_id) || exit 1
+host=$(etq_state_read_key "$workspace_file" hosted_host) || exit 1
+seat_id=$(etq_state_read_key "$(etq_state_seat_path)" seat_id) || exit 1
+seat_id=$(etq_sanitize_opaque_id "$seat_id") || {
+  echo "post-receipt: seat.json contains invalid seat_id; re-run seat-init --force" >&2
+  exit 1
+}
+
+# Build body with jq for safe JSON construction.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "post-receipt: jq required" >&2
+  exit 1
+fi
+body=$(jq -nc \
+  --arg pass_id "$pass_id" \
+  --arg task_id "$task_id" \
+  --arg seat_id "$seat_id" \
+  --arg status "$status" \
+  --arg artifact_ref "$clean_artifact" \
+  --arg receipt_ref "$clean_receipt" \
+  --arg validation_summary "$validation_summary" \
+  '
+    {pass_id: $pass_id, task_id: $task_id, seat_id: $seat_id, status: $status}
+    + (if $artifact_ref != "" then {artifact_ref: $artifact_ref} else {} end)
+    + (if $receipt_ref != "" then {receipt_ref: $receipt_ref} else {} end)
+    + (if $validation_summary != "" then {validation_summary: $validation_summary} else {} end)
+  ')
+
+url="$host/workspaces/$workspace_id/receipts"
+printf 'post-receipt: POST %s task=%s status=%s\n' "$url" "$task_id" "$status"
+
+response=$(etq_http_post "$url" "$body") || {
+  rc=$?
+  echo "post-receipt: ingest failed (http rc=$rc)" >&2
+  exit "$rc"
+}
+
+printf 'post-receipt: ingested\n'
+printf '%s\n' "$response" | jq -c . 2>/dev/null || printf '%s\n' "$response"

package/templates/etiquette-vanilla-v0/source/control-seat/bin/post-telemetry

@@ -0,0 +1,112 @@
+#!/bin/sh
+# post-telemetry: push a daily-grain telemetry event to the hosted plane.
+#
+# Per telemetry.v0 — event_type must be in the 8-event allowlist; meta is
+# bounded (keys ≤32 chars, string values ≤64 chars and reject path/hostname
+# patterns) before anything is sent over the wire.
+#
+# Usage:
+#   sh bin/post-telemetry --event-type seat_doctor_run
+#   sh bin/post-telemetry --event-type seat_doctor_run --count 1 --meta '{"p50_ms":140}'
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+# shellcheck source=_lib/sanitize.sh
+. "$ROOT/bin/_lib/sanitize.sh"
+# shellcheck source=_lib/state.sh
+. "$ROOT/bin/_lib/state.sh"
+# shellcheck source=_lib/http.sh
+. "$ROOT/bin/_lib/http.sh"
+
+ALLOWED_EVENTS="pass_issued pass_revoked pass_consumed seat_readiness_posted seat_verified receipt_submitted seat_doctor_run validate_vanilla_run"
+
+event_type=""
+count=1
+meta='{}'
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --event-type) event_type=$2; shift 2 ;;
+    --count) count=$2; shift 2 ;;
+    --meta) meta=$2; shift 2 ;;
+    -h|--help)
+      cat <<EOF
+post-telemetry — push a daily-grain telemetry event
+
+  sh bin/post-telemetry --event-type <type> [--count N] [--meta JSON]
+
+Allowed event_type values (8):
+$(printf '  - %s\n' $ALLOWED_EVENTS)
+
+Requires seat-consume-pass to have populated workspace.json.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$event_type" ]; then
+  echo "post-telemetry: --event-type is required" >&2
+  exit 2
+fi
+
+# Allowlist check client-side (saves a round trip).
+allowed=0
+for e in $ALLOWED_EVENTS; do
+  if [ "$e" = "$event_type" ]; then allowed=1; break; fi
+done
+if [ "$allowed" -ne 1 ]; then
+  printf 'post-telemetry: event_type "%s" not in allowlist:\n' "$event_type" >&2
+  printf '  - %s\n' $ALLOWED_EVENTS >&2
+  exit 2
+fi
+
+# count must be a positive integer.
+case "$count" in
+  *[!0-9]*) echo "post-telemetry: --count must be a positive integer" >&2; exit 2 ;;
+  '') echo "post-telemetry: --count empty" >&2; exit 2 ;;
+esac
+
+# Meta must be a JSON object.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "post-telemetry: jq required" >&2
+  exit 1
+fi
+if ! printf '%s' "$meta" | jq -e 'type == "object"' >/dev/null 2>&1; then
+  echo "post-telemetry: --meta must be a JSON object" >&2
+  exit 2
+fi
+if ! clean_meta=$(etq_sanitize_meta_json "$meta"); then
+  echo "post-telemetry: --meta sanitization failed" >&2
+  exit 2
+fi
+
+# Load workspace.json.
+workspace_file=$(etq_state_workspace_path)
+if [ ! -f "$workspace_file" ]; then
+  echo "post-telemetry: workspace.json missing — run \`sh bin/seat-consume-pass --pass-id <id>\` first" >&2
+  exit 1
+fi
+workspace_id=$(etq_state_read_key "$workspace_file" workspace_id) || exit 1
+pass_id=$(etq_state_read_key "$workspace_file" pass_id) || exit 1
+host=$(etq_state_read_key "$workspace_file" hosted_host) || exit 1
+
+body=$(jq -nc \
+  --arg pass_id "$pass_id" \
+  --arg event_type "$event_type" \
+  --argjson count "$count" \
+  --argjson meta "$clean_meta" \
+  '{pass_id: $pass_id, event_type: $event_type, count: $count, meta: $meta}')
+
+url="$host/workspaces/$workspace_id/telemetry"
+printf 'post-telemetry: POST %s event_type=%s count=%s\n' "$url" "$event_type" "$count"
+
+response=$(etq_http_post "$url" "$body") || {
+  rc=$?
+  echo "post-telemetry: ingest failed (http rc=$rc)" >&2
+  exit "$rc"
+}
+
+printf 'post-telemetry: ingested\n'
+printf '%s\n' "$response" | jq -c . 2>/dev/null || printf '%s\n' "$response"