@etiquekit/etq 0.0.1 → 1.0.4

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"

package/templates/etiquette-vanilla-v0/source/control-seat/bin/seat-consume-pass

@@ -0,0 +1,115 @@
+#!/bin/sh
+# seat-consume-pass: redeem a setup-pass against the hosted plane and cache
+# the returned envelope into $STATE_DIR/workspace.json.
+#
+# Per pass.v0 contract.  No credentials are returned; only routing fields
+# (workspace_id, org_id, seat_template, requested_runtime, artifact_type,
+# allowed_repo_binding).
+#
+# Usage:
+#   sh bin/seat-consume-pass --pass-id <pass-id>
+#   sh bin/seat-consume-pass --pass-id <pass-id> --host http://localhost:4000
+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"
+
+host=${ETIQUETTE_HOSTED_HOST:-http://localhost:4000}
+pass_id=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --pass-id) pass_id=$2; shift 2 ;;
+    --host) host=$2; shift 2 ;;
+    -h|--help)
+      cat <<'EOF'
+seat-consume-pass — redeem a setup-pass; cache envelope to workspace.json
+
+  sh bin/seat-consume-pass --pass-id <pass-id> [--host <url>]
+
+Requires seat-init to have run first (needs seat.json for consumer_seat_id).
+Stores envelope at $STATE_DIR/workspace.json on success.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -z "$pass_id" ]; then
+  echo "seat-consume-pass: --pass-id is required" >&2
+  exit 2
+fi
+
+# Pass-id format check: it's a ULID we received from the dashboard; let the
+# server be the authority on validity, but reject obvious junk (whitespace,
+# excessive length).
+case "$pass_id" in
+  *' '*|*"$(printf '\t')"*) echo "seat-consume-pass: pass-id has whitespace" >&2; exit 2 ;;
+esac
+if [ "${#pass_id}" -gt 64 ]; then
+  echo "seat-consume-pass: pass-id length > 64; suspicious" >&2
+  exit 2
+fi
+
+seat_file=$(etq_state_seat_path)
+if [ ! -f "$seat_file" ]; then
+  cat >&2 <<EOF
+seat-consume-pass: seat.json missing — run \`sh bin/seat-init\` first.
+EOF
+  exit 1
+fi
+
+seat_id=$(etq_state_read_key "$seat_file" seat_id) || exit 1
+# Defence: confirm seat_id still sanitiser-clean (in case of manual edits).
+if ! seat_id=$(etq_sanitize_opaque_id "$seat_id"); then
+  echo "seat-consume-pass: seat.json contains invalid seat_id; re-run seat-init --force" >&2
+  exit 1
+fi
+
+# Build request body.
+body=$(printf '{"consumer_seat_id":"%s"}' "$seat_id")
+
+url="$host/passes/$pass_id/consume"
+printf 'seat-consume-pass: POST %s\n' "$url"
+
+response=$(etq_http_post "$url" "$body") || {
+  rc=$?
+  echo "seat-consume-pass: pass redemption failed (http rc=$rc)" >&2
+  exit "$rc"
+}
+
+# Sanity-check the envelope.
+if ! command -v jq >/dev/null 2>&1; then
+  echo "seat-consume-pass: jq required to parse envelope" >&2
+  exit 1
+fi
+
+workspace_id=$(printf '%s' "$response" | jq -r '.workspace_id // empty')
+org_id=$(printf '%s' "$response" | jq -r '.org_id // empty')
+
+if [ -z "$workspace_id" ] || [ -z "$org_id" ]; then
+  echo "seat-consume-pass: envelope missing workspace_id or org_id" >&2
+  printf '%s\n' "$response" >&2
+  exit 1
+fi
+
+now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+# Augment envelope with consumption-side metadata (pass_id + host + ts).
+augmented=$(printf '%s' "$response" | jq \
+  --arg pass_id "$pass_id" \
+  --arg host "$host" \
+  --arg consumed_at "$now" \
+  '. + {pass_id: $pass_id, hosted_host: $host, cached_at: $consumed_at}')
+
+workspace_file=$(etq_state_workspace_path)
+etq_state_write_file "$workspace_file" "$augmented"
+
+printf 'seat-consume-pass: cached envelope to %s\n' "$workspace_file"
+printf 'seat-consume-pass: workspace_id=%s org_id=%s\n' "$workspace_id" "$org_id"
+printf 'seat-consume-pass: next: sh bin/seat-post-readiness\n'

package/templates/etiquette-vanilla-v0/source/control-seat/bin/seat-doctor

@@ -0,0 +1,20 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+test -f "$ROOT/.llm-substrate/HANDOFF.md"
+test -f "$ROOT/docs/work/ledger/LEDGER.md"
+test -f "$ROOT/docs/work/access/workspace-secure-profile.v0.json"
+test -f "$ROOT/docs/work/access/ACCESS-ASSURANCE.md"
+test -f "$ROOT/docs/work/playbacks/PLAYBACK_TEMPLATE.md"
+test -f "$ROOT/docs/work/tasks/CONTROL-001.yaml"
+test -d "$ROOT/docs/work/receipts"
+test -f "$ROOT/bin/access-assurance-check"
+test -f "$ROOT/bin/session-init"
+test -f "$ROOT/bin/local-event"
+test -f "$ROOT/bin/compact-local-events"
+
+sh "$ROOT/bin/access-assurance-check" >/dev/null
+
+echo "control-seat: ok"

package/templates/etiquette-vanilla-v0/source/control-seat/bin/seat-init

@@ -0,0 +1,86 @@
+#!/bin/sh
+# seat-init: mint an opaque seat_id and write $STATE_DIR/seat.json.
+#
+# Opaque seat_id only: no hostnames, paths, IPs, unsafe characters, or
+# values over 64 chars. Idempotent: re-runs preserve existing seat_id
+# unless --force is passed.
+#
+# Usage:
+#   sh bin/seat-init                              # mint if missing
+#   sh bin/seat-init --execution-seat cc-seat     # set seat label
+#   sh bin/seat-init --force                      # re-mint even if seat.json exists
+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"
+
+execution_seat=${ETIQUETTE_EXECUTION_SEAT:-control-seat}
+force=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --execution-seat) execution_seat=$2; shift 2 ;;
+    --force) force=1; shift ;;
+    -h|--help)
+      cat <<'EOF'
+seat-init — mint opaque seat_id; bootstrap $STATE_DIR/seat.json
+
+  sh bin/seat-init [--execution-seat <label>] [--force]
+
+Writes ~/.etiquette/state/seat.json under the seat root with:
+  seat_id        opaque ULID-style id (≤64 chars; no hostnames/paths/IPs)
+  execution_seat  caller-supplied label (default control-seat)
+  created_at     iso8601 timestamp
+
+Idempotent: re-runs preserve seat_id unless --force.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+# Validate execution_seat is sanitiser-clean (it ends up in payloads).
+if ! execution_seat=$(etq_sanitize_opaque_id "$execution_seat"); then
+  exit 1
+fi
+
+etq_state_init_dir
+seat_file=$(etq_state_seat_path)
+
+if [ -f "$seat_file" ] && [ "$force" -eq 0 ]; then
+  existing_id=$(etq_state_read_key "$seat_file" seat_id 2>/dev/null || true)
+  if [ -n "$existing_id" ]; then
+    printf 'seat-init: seat.json already exists (seat_id=%s); use --force to re-mint\n' "$existing_id"
+    exit 0
+  fi
+fi
+
+# Generate an opaque seat_id.  Shape: seat-<unixtime>-<8 hex>
+# This is opaque (no hostname/path/IP), bounded length, sanitiser-clean.
+ts=$(date +%s)
+if command -v openssl >/dev/null 2>&1; then
+  rand=$(openssl rand -hex 4)
+elif [ -r /dev/urandom ]; then
+  rand=$(od -An -N4 -tx1 /dev/urandom | tr -d ' \n')
+else
+  # Last-resort PRNG; not cryptographic, but seat_id is not a secret.
+  rand=$(awk 'BEGIN{srand(); printf "%08x", int(rand()*4294967295)}')
+fi
+seat_id="seat-${ts}-${rand}"
+
+# Verify our own output is sanitiser-clean (defence-in-depth).
+if ! seat_id=$(etq_sanitize_opaque_id "$seat_id"); then
+  echo "seat-init: generated seat_id failed self-sanitiser; aborting" >&2
+  exit 1
+fi
+
+now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+body=$(printf '{"seat_id":"%s","execution_seat":"%s","created_at":"%s"}' \
+  "$seat_id" "$execution_seat" "$now")
+
+etq_state_write_file "$seat_file" "$body"
+printf 'seat-init: minted seat_id=%s execution_seat=%s\n' "$seat_id" "$execution_seat"
+printf 'seat-init: wrote %s\n' "$seat_file"

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

@@ -0,0 +1,171 @@
+#!/bin/sh
+# seat-post-readiness: push capability declaration to the hosted plane.
+#
+# Per hosted-plane-boundary.v0 Sycophant problem fix — capability_source
+# defaults to "seat-doctor" (trusted source).  "agent-self-declared" is
+# allowed but flagged low-trust at the dashboard.  Operator-config is
+# also trusted.
+#
+# Usage:
+#   sh bin/seat-post-readiness --status operational
+#   sh bin/seat-post-readiness --status operational --parallel-support \
+#     --strategies "solo,telescope,local_adversarial_tango" \
+#     --unsupported "avengers"
+#   sh bin/seat-post-readiness --capability-source operator-config --status operational
+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="operational degraded blocked"
+ALLOWED_SOURCES="operator-config seat-doctor agent-self-declared"
+
+status=""
+capability_source="seat-doctor"
+parallel_support="false"
+strategies=""
+unsupported=""
+environment_node_id=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --status) status=$2; shift 2 ;;
+    --capability-source) capability_source=$2; shift 2 ;;
+    --parallel-support) parallel_support="true"; shift ;;
+    --strategies) strategies=$2; shift 2 ;;
+    --unsupported) unsupported=$2; shift 2 ;;
+    --environment-node-id) environment_node_id=$2; shift 2 ;;
+    -h|--help)
+      cat <<EOF
+seat-post-readiness — push capability declaration to the hosted plane
+
+  sh bin/seat-post-readiness --status <status> \\
+    [--capability-source <source>] [--parallel-support] \\
+    [--strategies "a,b,c"] [--unsupported "x,y"] \\
+    [--environment-node-id <opaque>]
+
+Status (3):
+$(printf '  - %s\n' $ALLOWED_STATUSES)
+
+Capability source (3; agent-self-declared flagged low-trust):
+$(printf '  - %s\n' $ALLOWED_SOURCES)
+
+Defaults: capability_source=seat-doctor, parallel_support=false.
+Requires seat-consume-pass to have populated workspace.json.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$status" ] || { echo "seat-post-readiness: --status required" >&2; exit 2; }
+
+# Allowlist checks.
+ok=0
+for s in $ALLOWED_STATUSES; do [ "$s" = "$status" ] && ok=1; done
+if [ "$ok" -ne 1 ]; then
+  printf 'seat-post-readiness: --status "%s" not in allowlist:\n' "$status" >&2
+  printf '  - %s\n' $ALLOWED_STATUSES >&2
+  exit 2
+fi
+ok=0
+for s in $ALLOWED_SOURCES; do [ "$s" = "$capability_source" ] && ok=1; done
+if [ "$ok" -ne 1 ]; then
+  printf 'seat-post-readiness: --capability-source "%s" not in allowlist:\n' "$capability_source" >&2
+  printf '  - %s\n' $ALLOWED_SOURCES >&2
+  exit 2
+fi
+
+# Sanitise environment_node_id if supplied.
+clean_env=""
+if [ -n "$environment_node_id" ]; then
+  if ! clean_env=$(etq_sanitize_opaque_id "$environment_node_id"); then
+    echo "seat-post-readiness: --environment-node-id rejected" >&2
+    exit 2
+  fi
+fi
+
+# Load state.
+seat_file=$(etq_state_seat_path)
+workspace_file=$(etq_state_workspace_path)
+if [ ! -f "$seat_file" ]; then
+  echo "seat-post-readiness: seat.json missing — run \`sh bin/seat-init\` first" >&2
+  exit 1
+fi
+if [ ! -f "$workspace_file" ]; then
+  echo "seat-post-readiness: workspace.json missing — run \`sh bin/seat-consume-pass --pass-id <id>\` first" >&2
+  exit 1
+fi
+
+seat_id=$(etq_state_read_key "$seat_file" seat_id) || exit 1
+execution_seat=$(etq_state_read_key "$seat_file" execution_seat) || exit 1
+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
+
+# Validate seat_id + execution_seat against sanitiser (defence).
+seat_id=$(etq_sanitize_opaque_id "$seat_id") || exit 1
+execution_seat=$(etq_sanitize_opaque_id "$execution_seat") || exit 1
+
+# Convert comma-separated strategy lists to JSON arrays.
+strategies_to_json() {
+  list=$1
+  if [ -z "$list" ]; then
+    printf '[]'
+    return
+  fi
+  # Use jq for safe construction.
+  printf '%s' "$list" | tr ',' '\n' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' | grep -v '^$' \
+    | jq -R . | jq -sc .
+}
+if ! command -v jq >/dev/null 2>&1; then
+  echo "seat-post-readiness: jq required" >&2
+  exit 1
+fi
+strategies_json=$(strategies_to_json "$strategies")
+unsupported_json=$(strategies_to_json "$unsupported")
+
+# Build body.
+body=$(jq -nc \
+  --arg pass_id "$pass_id" \
+  --arg seat_id "$seat_id" \
+  --arg execution_seat "$execution_seat" \
+  --arg status "$status" \
+  --arg capability_source "$capability_source" \
+  --argjson parallel_support "$parallel_support" \
+  --argjson strategies "$strategies_json" \
+  --argjson unsupported "$unsupported_json" \
+  --arg environment_node_id "$clean_env" \
+  '
+    {pass_id: $pass_id, seat_id: $seat_id, execution_seat: $execution_seat,
+     status: $status, capability_source: $capability_source,
+     parallel_support: $parallel_support,
+     supported_strategies: $strategies,
+     unsupported_strategies: $unsupported}
+    + (if $environment_node_id != "" then {environment_node_id: $environment_node_id} else {} end)
+  ')
+
+url="$host/workspaces/$workspace_id/seat-readiness"
+printf 'seat-post-readiness: POST %s status=%s capability_source=%s\n' \
+  "$url" "$status" "$capability_source"
+
+response=$(etq_http_post "$url" "$body") || {
+  rc=$?
+  echo "seat-post-readiness: ingest failed (http rc=$rc)" >&2
+  exit "$rc"
+}
+
+printf 'seat-post-readiness: ingested\n'
+printf '%s\n' "$response" | jq -c . 2>/dev/null || printf '%s\n' "$response"
+
+# Capability-source hint if low-trust.
+if [ "$capability_source" = "agent-self-declared" ]; then
+  printf '\nseat-post-readiness: NOTE — capability_source=agent-self-declared is flagged low-trust\n' >&2
+  printf 'seat-post-readiness:        in the dashboard per capability-trust doctrine.\n' >&2
+fi

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

@@ -0,0 +1,132 @@
+#!/bin/sh
+# session-init: initialize the live local workflow surface for this seat.
+#
+# This is intentionally local-first. It does not register the seat remotely,
+# consume a pass, start a runtime, clone product repos, or call hosted APIs.
+# It verifies the seat identity, prepares ledger/receipt/task directories,
+# writes session.json, appends one compact ledger line, and emits one local
+# event so a running agent session has a durable local trail from turn zero.
+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"
+
+task_id="session-bootstrap"
+operator_principal="local-operator"
+force=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --task-id) task_id=$2; shift 2 ;;
+    --operator) operator_principal=$2; shift 2 ;;
+    --force) force=1; shift ;;
+    -h|--help)
+      cat <<'EOF'
+session-init — prepare local workflow surface for a live seat session
+
+  sh bin/session-init [--task-id <id>] [--operator <id>] [--force]
+
+Requires seat-init first. If seat-consume-pass already ran, the hosted
+workspace_id is copied into session.json. This command is local-only: no
+hosted POST, no product repo clone, no execution, no grant attachment.
+EOF
+      exit 0
+      ;;
+    *) echo "unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+seat_file=$(etq_state_seat_path)
+if [ ! -f "$seat_file" ]; then
+  echo "session-init: seat.json missing — run \`sh bin/seat-init\` first" >&2
+  exit 1
+fi
+
+seat_id=$(etq_state_read_key "$seat_file" seat_id) || exit 1
+execution_seat=$(etq_state_read_key "$seat_file" execution_seat) || exit 1
+seat_id=$(etq_sanitize_opaque_id "$seat_id") || exit 1
+execution_seat=$(etq_sanitize_opaque_id "$execution_seat") || exit 1
+operator_principal=$(etq_sanitize_opaque_id "$operator_principal") || exit 1
+task_id=$(etq_sanitize_opaque_id "$task_id") || exit 1
+
+etq_state_init_dir
+session_file="$(etq_state_dir)/session.json"
+if [ -f "$session_file" ] && [ "$force" -eq 0 ]; then
+  existing=$(etq_state_read_key "$session_file" session_id 2>/dev/null || true)
+  if [ -n "$existing" ]; then
+    printf 'session-init: session already exists (session_id=%s); use --force to re-open\n' "$existing"
+    exit 0
+  fi
+fi
+
+mkdir -p \
+  "$ROOT/.etiquette/events" \
+  "$ROOT/docs/work/ledger" \
+  "$ROOT/docs/work/receipts" \
+  "$ROOT/docs/work/tasks" \
+  "$ROOT/docs/work/outbox" \
+  "$ROOT/docs/work/sessions"
+
+ledger="$ROOT/docs/work/ledger/LEDGER.md"
+if [ ! -f "$ledger" ]; then
+  printf '# Local Ledger\n\n' > "$ledger"
+fi
+
+ts=$(date +%s)
+if command -v openssl >/dev/null 2>&1; then
+  rand=$(openssl rand -hex 4)
+elif [ -r /dev/urandom ]; then
+  rand=$(od -An -N4 -tx1 /dev/urandom | tr -d ' \n')
+else
+  rand=$(awk 'BEGIN{srand(); printf "%08x", int(rand()*4294967295)}')
+fi
+session_id="session-${ts}-${rand}"
+session_id=$(etq_sanitize_opaque_id "$session_id") || exit 1
+now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+workspace_id=""
+hosted_host=""
+workspace_file=$(etq_state_workspace_path)
+if [ -f "$workspace_file" ]; then
+  workspace_id=$(etq_state_read_key "$workspace_file" workspace_id 2>/dev/null || true)
+  hosted_host=$(etq_state_read_key "$workspace_file" hosted_host 2>/dev/null || true)
+fi
+
+body=$(jq -cn \
+  --arg session_id "$session_id" \
+  --arg started_at "$now" \
+  --arg seat_id "$seat_id" \
+  --arg execution_seat "$execution_seat" \
+  --arg operator_principal "$operator_principal" \
+  --arg task_id "$task_id" \
+  --arg remote_registration "$([ -n "$workspace_id" ] && printf present || printf absent)" \
+  --arg workspace_id "$workspace_id" \
+  --arg hosted_host "$hosted_host" \
+  '{
+    session_id: $session_id,
+    started_at: $started_at,
+    seat_id: $seat_id,
+    execution_seat: $execution_seat,
+    operator_principal: $operator_principal,
+    task_id: $task_id,
+    workflow_surface: "local-control-seat",
+    remote_registration: $remote_registration
+  }
+  + (if $workspace_id != "" then {workspace_id: $workspace_id} else {} end)
+  + (if $hosted_host != "" then {hosted_host: $hosted_host} else {} end)')
+
+etq_state_write_file "$session_file" "$body"
+printf -- '- %s session=%s task=%s seat=%s operator=%s action=session_opened scope=local-workflow remote_registration=%s authority=advisory-only\n' \
+  "$now" "$session_id" "$task_id" "$seat_id" "$operator_principal" \
+  "$([ -n "$workspace_id" ] && printf present || printf absent)" >> "$ledger"
+
+sh "$ROOT/bin/local-event" "$task_id" "$seat_id" session_init \
+  "session $session_id opened for $execution_seat; local ledger/receipts/tasks/outbox ready" >/dev/null
+
+printf 'session-init: opened session_id=%s task_id=%s seat_id=%s\n' "$session_id" "$task_id" "$seat_id"
+printf 'session-init: wrote %s\n' "$session_file"
+printf 'session-init: ledger ready at docs/work/ledger/LEDGER.md\n'
+printf 'session-init: receipts/tasks/outbox ready under docs/work/\n'

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/access/ACCESS-ASSURANCE.md

@@ -0,0 +1,39 @@
+# Access Assurance
+
+The vanilla control seat starts in `open` mode. That keeps Etiquette usable as a
+local-first workflow kit without authentication, screening, hosted services, or
+a daemon.
+
+The workspace mode lives in `workspace-secure-profile.v0.json`.
+
+Modes:
+
+- `open`: no access-assurance gate is required.
+- `screening-warn`: restricted-seat policy and claims are checked, but failures
+  warn instead of blocking.
+- `screening-enforced`: restricted seats fail closed when policy or claims are
+  missing, expired, revoked, or not provider-backed.
+- `enterprise-reactor`: `screening-enforced` plus an optional tighten-only
+  daemon for revocation sync, badge refresh, kill-switch writes, and outbox
+  drain.
+
+The reactor may tighten access only. It must not grant access, authorize
+actions, close work, merge, or rewrite the ledger.
+
+Provider-backed secure deployments should keep raw identity material outside the
+repo:
+
+```text
+Persona / Scandit / SSO -> Supabase derived claims -> local access check
+```
+
+Repo-safe fields are provider refs, status, policy eligibility class, evidence
+hash, expiry, and audit timestamps. Passport images, document photos, full
+document numbers, ethnicity, provider secrets, and raw webhook payloads do not
+belong in Git.
+
+Check the mode:
+
+```sh
+sh bin/access-assurance-check
+```