@stravica-ai/digital-operator-pa 0.1.56 → 0.1.57

package/bin/pa-operator-attendance

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/operator-attendance/cli.mjs')
+  .then(async (m) => process.exit(await m.main(process.argv.slice(2))))
+  .catch((err) => {
+    process.stderr.write(`pa-operator-attendance: fatal error loading hook (${err && err.message}); failing open\n`);
+    process.exit(1);
+  });

package/bin/pa-worker-launcher

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/worker-launcher/cli.mjs')
+  .then(async (m) => process.exit(await m.main(process.argv.slice(2))))
+  .catch((err) => {
+    process.stderr.write(`pa-worker-launcher: fatal error (${err && err.message})\n`);
+    process.exit(2);
+  });

package/dist/engineering-pa-cli/bin/pa-operator-attendance

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// pa-operator-attendance - operator-presence hook for Claude Code.
+//
+// Two subcommands wired into the scaffolded .claude/settings.json
+// (session-start, pre-tool-use). See src/operator-attendance/cli.mjs
+// for the behaviour, the exit-code contract (hook contract, not the
+// repo's own 0/1/2/3), and the observe-vs-enforce switch.
+//
+// Fail-closed is handled inside main(); this top-level .catch() exists
+// for the pathological case where even the dynamic import() fails
+// (corrupted install). The hook contract reads an unexpected exit code
+// as non-blocking, so a partial install does not block every tool call
+// estate-wide: exit 1 and log, same as the inner malformed-input case.
+import('../src/operator-attendance/cli.mjs')
+  .then(async (m) => process.exit(await m.main(process.argv.slice(2))))
+  .catch((err) => {
+    process.stderr.write(`pa-operator-attendance: fatal error loading hook (${err && err.message}); failing open\n`);
+    process.exit(1);
+  });

package/dist/engineering-pa-cli/bin/pa-worker-launcher

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// pa-worker-launcher - mint a signed PA_WORKER_GRANT and spawn an
+// unattended `claude -p` child session for a dispatch. See
+// src/worker-launcher/cli.mjs for the full behaviour and exit-code
+// contract (CONTRIBUTING.md: 0 ok / 1 usage / 2 operational / 3 IO).
+//
+// The hook contract covers the SessionStart + PreToolUse legs; this
+// bin is a normal estate CLI and uses the standard exit-code contract.
+import('../src/worker-launcher/cli.mjs')
+  .then(async (m) => process.exit(await m.main(process.argv.slice(2))))
+  .catch((err) => {
+    process.stderr.write(`pa-worker-launcher: fatal error (${err && err.message})\n`);
+    process.exit(2);
+  });

package/dist/engineering-pa-cli/config/coordinator-allowlist.json

@@ -75,6 +75,7 @@
   "hardDeny": {
     "_comment": "Checked before any allow pattern (core or overlay), for both Bash commands and Read/Write paths. Overlays cannot add, remove, or shadow entries here — see policy.mjs. Not a security sandbox (a determined caller can still smuggle a second command past a naive prefix regex — see bashChainGuard below for the mitigation), just a mechanical backstop against the most obviously destructive one-liners, the specific 'obviously-destructive gh verbs' the spec calls out, and reads/writes of credential material even if some overlay pattern would otherwise match it.",
     "bashPatterns": [
+      "^\\s*claude(\\s+[^-\\s]|\\s*$)",
       "rm\\s+-rf\\b",
       "curl[^\\n]*\\|\\s*(sh|bash|zsh)\\b",
       "wget[^\\n]*\\|\\s*(sh|bash|zsh)\\b",
@@ -93,6 +94,7 @@
     ],
     "bashChainGuardPattern": "[;&|`<>\\n]|\\$\\(",
     "bashChainGuardNote": "Tier2 Bash commands containing a shell-chaining metacharacter (;, &&, ||, |, backtick, $(...), <, >) or an embedded newline are blocked outright even if the leading command (or leading line) matches an allow pattern — a prefix match on 'pa knowledge search foo && rm -rf ~' must not slip through, nor must 'pa knowledge search foo\\nsudo apt-get purge -y openssh-server' or a redirect like 'echo foo > ~/.ssh/authorized_keys'. False positives (e.g. a quoted '&&' inside a search string) are an accepted cost; the hook always suggests a dispatch alternative.",
+    "claudeLaunchNote": "The leading `^\\s*claude(\\s+[^-\\s]|\\s*$)` entry denies raw agent-CLI launches from Bash: bare `claude`, `claude help foo`, `claude -p <...>`, `claude mcp list`, any `claude <word>` form that would start a full session that boots the project PA. Flag-only inspection forms (`claude --help`, `claude --version`, `claude --mcp-list`, `claude -v`, `claude -h`) pass through because the character after the space is `-`. A dispatch that genuinely needs its own child session goes through pa-worker-launcher, which carries a signed PA_WORKER_GRANT; the pa-operator-attendance PreToolUse hook enforces the same deny with the launcher-grant exemption.",
     "pathPatterns": [
       "\\.vault/",
       "secrets\\.enc\\.json$",

package/dist/engineering-pa-cli/package.json

@@ -17,7 +17,9 @@
     "smoke": "bin/smoke",
     "launch": "bin/launch",
     "research": "bin/research",
-    "pa-coordinator-hook": "bin/pa-coordinator-hook"
+    "pa-coordinator-hook": "bin/pa-coordinator-hook",
+    "pa-operator-attendance": "bin/pa-operator-attendance",
+    "pa-worker-launcher": "bin/pa-worker-launcher"
   },
   "dependencies": {
     "@stravica-ai/engineering-pa-core": "workspace:*",

package/dist/engineering-pa-cli/src/operator-attendance/cli.mjs

@@ -0,0 +1,420 @@
+// cli.mjs - pa-operator-attendance entry point.
+//
+// Two subcommands run from one program:
+//
+//   `pa-operator-attendance session-start`
+//     Wired into Claude Code's SessionStart hook. Computes the attendance
+//     stamp (TTY + env + no grant), persists it to a per-session cache,
+//     and emits a one-line `additionalContext` block carrying
+//     `operator-present: true|false[...]` for the loaded agent to read as
+//     the first line of its workState context.
+//
+//   `pa-operator-attendance pre-tool-use`
+//     Wired into Claude Code's PreToolUse hook, matcher Bash + Edit +
+//     Write + NotebookEdit. Reads the attendance stamp (recomputing if
+//     the cache is missing), denies raw `claude <word>` launches
+//     regardless of attendance, denies estate-mutating tool calls on an
+//     unattended session with no grant, and otherwise falls through.
+//
+// Observe-vs-enforce switch: `PA_OPERATOR_ATTENDANCE_MODE` env var.
+//   observe (default): every would-deny is appended as one JSONL line
+//     to the decision log; the hook exits 0 and the call proceeds. Used
+//     for one point release before the default flips to enforce so both
+//     estates get a week of real-traffic decisions before the gate goes
+//     live.
+//   enforce: would-denies become real exit-2 denies with stderr
+//     messages the model sees.
+//
+// Exit codes follow Claude Code's hook contract, not the repo's own
+// 0/1/2/3 CLI convention: 0 = allow / stamp emitted, 2 = block (enforce),
+// 1 = non-blocking error (malformed input, unexpected failure).
+//
+// Zero dependencies beyond node stdlib and the shared grant module in
+// `@stravica-ai/engineering-pa-core/src/attendance/grant.mjs`.
+
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  loadOrMintHostKey,
+  verifyGrant,
+  resolveKeyPath,
+} from '../../../engineering-pa-core/src/attendance/grant.mjs';
+import { resolveHome } from '../../../engineering-pa-core/src/home/resolve.mjs';
+
+const USAGE = `pa-operator-attendance: operator-presence gate for Claude Code hooks.
+
+Two subcommands wired into the scaffolded .claude/settings.json:
+
+  session-start   SessionStart hook: stamp attendance, emit the
+                  operator-present line, cache the stamp for the
+                  PreToolUse leg.
+  pre-tool-use    PreToolUse hook (Bash + Edit + Write + NotebookEdit):
+                  deny raw agent-CLI launches, deny estate-mutating
+                  calls on an unattended session without a grant.
+
+Environment:
+  PA_OPERATOR_ATTENDANCE_MODE=observe|enforce   default: observe
+  PA_WORKER_GRANT=<dispatchId>.<unixTs>.<hmac>  minted by pa-worker-launcher
+  PA_ATTENDANCE_KEY_PATH=/path/to/key           override host-key location
+  PA_ATTENDANCE_LOG_DIR=/path/to/log/dir        override decision-log dir
+
+Decision log (observe mode): one JSONL line per would-deny at
+<logDir>/attendance-decisions.jsonl. Rejection log: a hostile grant lands
+at <logDir>/attendance-rejects.log.
+
+Usage:
+  pa-operator-attendance session-start
+  pa-operator-attendance pre-tool-use
+  pa-operator-attendance --help
+`;
+
+const RAW_CLAUDE_PATTERN = /^\s*claude(\s+[^-\s]|\s*$)/;
+
+// Bash commands denied for an unattended + no-grant session. Any line
+// matching one of these is a durable estate side effect: a commit, a
+// push, a write through the pa-family CLI, a redirect, a tee, an rm.
+// Read-only verbs (git status, git log, ls, cat, grep, etc.) are not
+// listed and pass through.
+const UNATTENDED_MUTATE_PATTERNS = [
+  /^\s*git\s+(commit|push|merge|rebase|cherry-pick|reset|checkout|branch|tag|stash|am|revert|pull)\b/,
+  /^\s*gh\s+(pr\s+(create|edit|merge|close|comment|review)|repo\s+(create|edit|delete|archive)|issue\s+(create|edit|close|comment)|release\s+(create|edit|delete)|workflow\s+(enable|disable|run)|secret\s+(set|remove))\b/,
+  /^\s*(pnpm\s+exec\s+)?pa\s+(work|project|library|relay|autonomy|content-pub|secrets|scheduler)\s+(?!(?:help|list|ls|get|show|view|status|tail|find|search|export|path|inspect|whoami|context|overview|today|related|domain|orphans|read|print))/,
+  /^\s*(pnpm\s+exec\s+)?library\s+(put|flush|refresh-clones|up-merge)\b/,
+  /^\s*(pnpm\s+exec\s+)?claude-relay\s+(send|publish|post)\b/,
+  /^\s*rm\b/,
+  /^\s*mv\b/,
+  /^\s*cp\b/,
+  /^\s*mkdir\b/,
+  /^\s*touch\b/,
+  /^\s*(ln|chmod|chown)\b/,
+  /^\s*(tee|dd)\b/,
+  /^\s*(apt|apt-get|brew|npm|pnpm|yarn)\s+(install|add|remove|uninstall|upgrade|update|publish)\b/,
+  /[^<>]>\s*\S/,  // `foo > bar`, `foo 2> bar`: any single-redirect write
+  />>\s*\S/,       // append redirect
+];
+
+export async function main(argv = [], {
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  env = process.env,
+  now = () => new Date(),
+} = {}) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    stderr.write(USAGE);
+    return 0;
+  }
+  const sub = argv[0];
+  if (!sub) {
+    stderr.write('pa-operator-attendance: missing subcommand (session-start | pre-tool-use)\n');
+    return 1;
+  }
+  try {
+    if (sub === 'session-start') {
+      return await runSessionStart({ stdin, stdout, stderr, env, now });
+    }
+    if (sub === 'pre-tool-use') {
+      return await runPreToolUse({ stdin, stdout, stderr, env, now });
+    }
+    stderr.write(`pa-operator-attendance: unknown subcommand "${sub}"\n`);
+    return 1;
+  } catch (err) {
+    // A hook that throws unhandled is worse than a degraded one: a
+    // SessionStart failure blocks the boot, a PreToolUse failure blocks
+    // every tool call. Exit 1 (non-blocking per the hooks contract) and
+    // leave a stderr note the transcript will pick up.
+    stderr.write(`pa-operator-attendance: ${sub || 'unknown'}: unexpected error (${err && err.message}); failing open\n`);
+    return 1;
+  }
+}
+
+// --- session-start ---------------------------------------------------------
+
+async function runSessionStart({ stdin, stdout, stderr, env, now }) {
+  const payload = await readPayload(stdin);
+  // SessionStart has no required fields we gate on; we still parse it so
+  // a payload with `session_id` can key the cache properly.
+  const sessionId = (payload && payload.session_id) || env.CLAUDE_CODE_SESSION_ID || 'unknown';
+
+  // Attendance detection. The empirical probe for w-2026-10-02-dave-018
+  // (session-start leg) proved against client 2.1.287 that:
+  //   - a `claude -p` child always sees CLAUDE_CODE_SESSION_ATTENDED=0
+  //     (not unset; the client zeroes it explicitly)
+  //   - a SessionStart hook fired by a `claude -p` child sees both
+  //     stdin and stdout as non-TTY
+  // So the positive-proof gate is: stdout.isTTY AND env === '1' AND no
+  // grant. Any other combination is unattended, which is the fail-safe
+  // direction (a client bump that strips the var defaults to absent).
+  const grantPresent = typeof env.PA_WORKER_GRANT === 'string' && env.PA_WORKER_GRANT.length > 0;
+  const envAttended = env.CLAUDE_CODE_SESSION_ATTENDED === '1';
+  const stdoutIsTty = Boolean(stdout.isTTY);
+  const attended = stdoutIsTty && envAttended && !grantPresent;
+
+  let stamp;
+  if (attended) {
+    stamp = { operatorPresent: true, grant: 'none', scope: 'attended' };
+  } else if (grantPresent) {
+    const key = await loadOrMintHostKeySafe(env);
+    const verdict = key
+      ? verifyGrant({ grant: env.PA_WORKER_GRANT, hostKey: key, now: now() })
+      : { ok: false, reason: 'host-key-unavailable' };
+    if (verdict.ok) {
+      stamp = {
+        operatorPresent: false,
+        grant: verdict.dispatchId,
+        scope: 'dispatch-only',
+        grantUnixTs: verdict.unixTs,
+      };
+    } else {
+      stamp = {
+        operatorPresent: false,
+        grant: 'rejected',
+        scope: 'refusal',
+        refusal: `grant ${verdict.reason}`,
+      };
+      await appendRejectLog({ env, sessionId, reason: verdict.reason, now: now() });
+    }
+  } else {
+    stamp = {
+      operatorPresent: false,
+      grant: 'none',
+      scope: 'refusal',
+      refusal: 'boot-routine denied, no PA_WORKER_GRANT',
+    };
+  }
+
+  await persistStamp({ env, sessionId, stamp, now: now() });
+
+  // Emit the Claude Code hook JSON envelope. The additionalContext text
+  // becomes the first line of the session's workState context, carrying
+  // the stamp to any downstream hook (boot-context, relay list) and to
+  // the loaded agent per the canon clause.
+  const contextLine = formatStampLine(stamp);
+  const envelope = {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: contextLine + '\n',
+    },
+  };
+  stdout.write(JSON.stringify(envelope) + '\n');
+
+  // Observe-mode trace: every session-start decision lands as one JSONL
+  // line so operators can see how the gate would have behaved on the
+  // first point release before the default flips to enforce.
+  await appendDecisionLog({
+    env,
+    now: now(),
+    leg: 'session-start',
+    decision: 'stamp',
+    stamp,
+    sessionId,
+    attendedSignals: { stdoutIsTty, envAttended, grantPresent },
+  });
+  return 0;
+}
+
+function formatStampLine(stamp) {
+  const parts = [`operator-present: ${stamp.operatorPresent ? 'true' : 'false'}`];
+  if (stamp.grant) parts.push(`grant: ${stamp.grant}`);
+  if (stamp.scope) parts.push(`scope: ${stamp.scope}`);
+  if (stamp.refusal) parts.push(`refusal: ${stamp.refusal}`);
+  return parts.join(', ');
+}
+
+// --- pre-tool-use ----------------------------------------------------------
+
+async function runPreToolUse({ stdin, stdout, stderr, env, now }) {
+  const mode = env.PA_OPERATOR_ATTENDANCE_MODE === 'enforce' ? 'enforce' : 'observe';
+  let payload;
+  try {
+    payload = await readPayload(stdin);
+  } catch (err) {
+    stderr.write(`pa-operator-attendance: pre-tool-use: malformed stdin (${err.message}); failing open\n`);
+    return 1;
+  }
+  const toolName = payload && typeof payload.tool_name === 'string' ? payload.tool_name : '';
+  const toolInput = (payload && payload.tool_input) || {};
+  if (!toolName) {
+    stderr.write('pa-operator-attendance: pre-tool-use: payload missing tool_name; failing open\n');
+    return 1;
+  }
+  const sessionId = (payload && payload.session_id) || env.CLAUDE_CODE_SESSION_ID || 'unknown';
+  const stamp = await readStamp({ env, sessionId }) || recomputeStamp(env);
+
+  const bashCommand = toolName === 'Bash' && typeof toolInput.command === 'string'
+    ? toolInput.command
+    : null;
+
+  // Rule 1: raw agent-CLI launch is denied regardless of attendance.
+  // The flag-only forms (`claude --help`, `claude --version`, `claude -v`,
+  // `claude -h`) pass; everything else (`claude help foo`, `claude -p`,
+  // `claude mcp list`, bare `claude`) is a session launch and must go
+  // through the launcher.
+  if (bashCommand) {
+    for (const line of bashCommand.split('\n')) {
+      if (RAW_CLAUDE_PATTERN.test(line)) {
+        return await denyOrObserve({
+          env, now, mode, stdout, stderr, sessionId, toolName, bashCommand,
+          stamp, rule: 'raw-claude-launch', matched: line.trim(),
+          message: 'pa-operator-attendance: raw agent-CLI launch denied. A `claude <word>` from a tool call starts a full session that boots the project PA. Use pa-worker-launcher to spawn a child session with a dispatch grant, or an inspection flag form (`claude --help`, `claude --version`).',
+        });
+      }
+    }
+  }
+
+  // Rule 2: unattended + no grant denies every estate-mutating call.
+  if (!stamp.operatorPresent && stamp.grant === 'none') {
+    if (toolName === 'Edit' || toolName === 'Write' || toolName === 'NotebookEdit') {
+      return await denyOrObserve({
+        env, now, mode, stdout, stderr, sessionId, toolName, bashCommand: null,
+        stamp, rule: 'unattended-write', matched: toolName,
+        message: `pa-operator-attendance: ${toolName} denied; session is unattended with no PA_WORKER_GRANT; estate side effects are blocked. Allowed: Read, Grep, Glob, and flag-only CLI inspection.`,
+      });
+    }
+    if (bashCommand) {
+      for (const line of bashCommand.split('\n')) {
+        for (const pattern of UNATTENDED_MUTATE_PATTERNS) {
+          if (pattern.test(line)) {
+            return await denyOrObserve({
+              env, now, mode, stdout, stderr, sessionId, toolName, bashCommand,
+              stamp, rule: 'unattended-mutate', matched: line.trim(),
+              message: `pa-operator-attendance: Bash command denied; session is unattended with no PA_WORKER_GRANT; estate side effects are blocked (matched "${pattern.source}"). Allowed: read-only inspection.`,
+            });
+          }
+        }
+      }
+    }
+  }
+  // Rule 2a: a rejected grant is hostile, not merely absent. Any tool
+  // call on a session with grant: rejected is denied outright until the
+  // operator attends or re-mints the grant.
+  if (!stamp.operatorPresent && stamp.grant === 'rejected') {
+    return await denyOrObserve({
+      env, now, mode, stdout, stderr, sessionId, toolName, bashCommand,
+      stamp, rule: 'rejected-grant', matched: toolName,
+      message: `pa-operator-attendance: ${toolName} denied; session carried a PA_WORKER_GRANT that failed verification; every tool call is blocked until the session attends or re-mints a valid grant.`,
+    });
+  }
+  return 0;
+}
+
+function recomputeStamp(env) {
+  // Fallback when the session-start cache is missing (hook ordering, cold
+  // start). Mirror the session-start detection without the key material,
+  // which means a grant that LOOKS valid shape-wise is treated as
+  // dispatch-only without HMAC verification. Intentional: the hook stays
+  // closed if session-start's richer stamp was lost, but it does not
+  // fabricate a verdict it does not have evidence for.
+  const grantPresent = typeof env.PA_WORKER_GRANT === 'string' && env.PA_WORKER_GRANT.length > 0;
+  const envAttended = env.CLAUDE_CODE_SESSION_ATTENDED === '1';
+  // In the pre-tool-use leg, stdout is always the hook pipe, so TTY check
+  // alone is unreliable. Trust the env signal only when there is no grant.
+  if (grantPresent) return { operatorPresent: false, grant: 'present', scope: 'dispatch-only' };
+  if (envAttended) return { operatorPresent: true, grant: 'none', scope: 'attended' };
+  return { operatorPresent: false, grant: 'none', scope: 'refusal', refusal: 'no stamp cache, env signals absent' };
+}
+
+async function denyOrObserve({ env, now, mode, stdout, stderr, sessionId, toolName, bashCommand, stamp, rule, matched, message }) {
+  await appendDecisionLog({
+    env,
+    now: now(),
+    leg: 'pre-tool-use',
+    decision: mode === 'enforce' ? 'deny' : 'observe',
+    rule,
+    matched,
+    toolName,
+    bashCommand,
+    stamp,
+    sessionId,
+    mode,
+  });
+  if (mode === 'enforce') {
+    stderr.write(message + '\n');
+    return 2;
+  }
+  // Observe mode: write a one-line stderr note so the operator can see
+  // what would have been denied without the tool call being blocked.
+  stderr.write(`pa-operator-attendance: OBSERVE would deny (${rule}: ${matched})\n`);
+  return 0;
+}
+
+// --- helpers ---------------------------------------------------------------
+
+async function readPayload(stdin) {
+  if (stdin.isTTY) return {};
+  const chunks = [];
+  for await (const chunk of stdin) chunks.push(chunk);
+  if (chunks.length === 0) return {};
+  const raw = Buffer.concat(chunks.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(c)))).toString('utf8');
+  if (raw.trim() === '') return {};
+  return JSON.parse(raw);
+}
+
+async function loadOrMintHostKeySafe(env) {
+  try {
+    return await loadOrMintHostKey({ keyPath: resolveKeyPath({ env }) });
+  } catch {
+    return null;
+  }
+}
+
+function resolveLogDir(env) {
+  if (env.PA_ATTENDANCE_LOG_DIR && env.PA_ATTENDANCE_LOG_DIR.length > 0) {
+    return env.PA_ATTENDANCE_LOG_DIR;
+  }
+  return join(resolveHome({ env }), '.local', 'share', 'pa');
+}
+
+function resolveStampPath(env, sessionId) {
+  const base = env.TMPDIR || tmpdir();
+  const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 128);
+  return join(base, `pa-attendance-${safe}.json`);
+}
+
+async function persistStamp({ env, sessionId, stamp, now }) {
+  const path = resolveStampPath(env, sessionId);
+  const record = { ...stamp, writtenAt: now.toISOString(), sessionId };
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(record), { mode: 0o600 });
+  } catch {
+    // The cache is a convenience for the pre-tool-use leg; losing it
+    // means the leg falls back to env recomputation (fail-safe).
+  }
+}
+
+async function readStamp({ env, sessionId }) {
+  const path = resolveStampPath(env, sessionId);
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function appendDecisionLog({ env, now, ...fields }) {
+  const dir = resolveLogDir(env);
+  const path = join(dir, 'attendance-decisions.jsonl');
+  const line = JSON.stringify({ ts: now.toISOString(), ...fields }) + '\n';
+  try {
+    await mkdir(dir, { recursive: true });
+    await appendFile(path, line);
+  } catch {
+    // Decision log is best effort; a hook never fails on logging.
+  }
+}
+
+async function appendRejectLog({ env, sessionId, reason, now }) {
+  const dir = resolveLogDir(env);
+  const path = join(dir, 'attendance-rejects.log');
+  const line = `${now.toISOString()} session=${sessionId} reason=${reason}\n`;
+  try {
+    await mkdir(dir, { recursive: true });
+    await appendFile(path, line);
+  } catch {
+    // Reject log is best effort too; the stamp is already emitting a
+    // refusal downstream.
+  }
+}