@indigoai-us/hq-cli 5.322.0 → 5.324.0

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 
 ## [Unreleased]
 
+## [5.324.0] — 2026-10-02
+- Keep the bundled shell runner out of native fast-route startup and defer timeout-guard flag snapshot imports until a timeout would block.
+- Reuse the parsed fast-route entry when dispatching the selected command.
+- Add native `hq core derive-trigger-facts` on the fast route behind the default-off `core-native-hook-helpers` flag.
+- Feedback reports can include the current cached hq-cli release when the default-off `feedback.latest-version` flag is enabled.
+- Added flag-gated global Anywhere installation, company linking, and hqd daemon commands.
+- Added flag-gated Anywhere daemon operations, doctor checks, and update convergence.
+- `hq-auth-refresh` accepts `--min-validity-seconds` or `HQ_AUTH_MIN_VALIDITY_SECONDS`; values above 1800 seconds use the resolver's 1800-second cache margin.
+- `hq db provision` now says remote databases are not available yet, instead of printing the server adapter error.
+
 ## [5.322.0] — 2026-10-02
+- Add an opt-in, default-off CLI prompt for solo companies to invite a teammate after a work-bearing sync.
 
 - Retried idempotent vault API GETs once when API Gateway returned its generic Lambda-invoke 504 response without a function request ID.
 

package/assets/scaffold/core/scripts/derive-trigger-facts.sh

@@ -0,0 +1,263 @@
+#!/bin/bash
+# derive-trigger-facts.sh — build the fact set a policy `when:` expression is
+# evaluated against, for a given hook event.
+#
+# Usage:
+#   <hook-json on stdin> | derive-trigger-facts.sh <EVENT> [--with-assistant-intent]
+#     EVENT in {PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent}
+#   -> prints a space-separated, de-duplicated fact set to stdout.
+#   With --with-assistant-intent (PreToolUse and UserPromptSubmit only), prints
+#   the primary and AssistantIntent fact sets as two newline-delimited records.
+#
+# Facts = event tokens + best-effort static facts (company / repo / shared_branch),
+# EXCEPT AssistantIntent, which is AI-message tokens only (no static facts).
+#
+# Tokens are OPEN — there is NO curated vocabulary. The fact set for a text
+# event is EVERY word token in that text (lowercased, letter-led, length >= 2),
+# so a policy `when:` can key on any word that naturally appears when it is
+# relevant (`refactor`, `monitor`, `docker`, `linear`, ...) without the engine
+# having to know it in advance. On top of the literal words, a few NON-LITERAL
+# / structured facts are derived (a word that is not itself present in the text):
+#   secret + apikey <- credential locations and key-shaped strings
+#   completed      <- clear completion messages in tool output or assistant text
+#   shared_branch  <- a shared branch name (main/master/staging/production/release/)
+#   <basename>+.ext <- a file reference (see Filename tokens below)
+#   /command       <- a slash-command mention (see Slash-command tokens below)
+#   run_in_background <- PreToolUse Bash with tool_input.run_in_background: true
+# Per-event source text:
+#   PreToolUse  Bash  -> the command. (`gh pr create` -> the word `pr`, etc.)
+#   PreToolUse  other -> lowercased tool name (Glob->glob, Grep->grep, ...).
+#   UserPromptSubmit  -> the prompt text.
+#   PostToolUse       -> the tool OUTPUT (tool_response) text.
+#   AssistantIntent   -> assistant message text emitted since the last user turn
+#                        in transcript_path, AND NOTHING ELSE (no command/prompt
+#                        tokens, no static facts). The dedicated AI-message
+#                        channel; raw PreToolUse / UserPromptSubmit fact sets do
+#                        NOT include look-back.
+#
+# Filename tokens: any file reference in the text emits a literal basename token
+# and a `.ext` token (the eval-trigger grammar allows dots and slashes). So a
+# policy keys on the file directly. `.claude/settings.json` -> `settings.json` +
+# `.json`; `.mcp.json` -> `.mcp.json` + `.json`; `shot.png` -> `shot.png` + `.png`.
+# This is what lets file-scoped policies fire from AssistantIntent (the AI naming
+# the file it is about to edit/read) without the hook seeing the non-Bash
+# Edit/Read tool call itself.
+#
+# Slash-command tokens: a `/command` mentioned in the text emits a `/command`
+# token (`/brainstorm`, `/deep-plan`), so a slash-command-scoped policy fires
+# when the command is invoked or referenced in a prompt.
+#
+# Pure read-only. Requires jq for JSON parsing (falls back to best-effort sed).
+
+set -euo pipefail
+
+EVENT="${1:-}"
+WITH_ASSISTANT_INTENT=0
+[ "${2:-}" = "--with-assistant-intent" ] && WITH_ASSISTANT_INTENT=1
+
+# Bash can read the hook pipe directly without the separate `cat` process. An
+# empty pipe retains the old best-effort empty-object behavior.
+STDIN_JSON="$(</dev/stdin)" || STDIN_JSON='{}'
+[ -n "$STDIN_JSON" ] || STDIN_JSON='{}'
+JQ="$(command -v jq || true)"
+
+# HQ root — used only to resolve the session's meta.yaml for the company fact
+# (US-004). Prefer an explicit HQ_ROOT / CLAUDE_PROJECT_DIR; otherwise walk up
+# from this script (core/scripts/derive-trigger-facts.sh -> ../.. == HQ root).
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+case "$SCRIPT_PATH" in
+  */*) SCRIPT_DIR="${SCRIPT_PATH%/*}" ;;
+  *) SCRIPT_DIR="." ;;
+esac
+SCRIPT_DIR="$(cd "$SCRIPT_DIR" && pwd)"
+HQ_ROOT="${HQ_ROOT:-${CLAUDE_PROJECT_DIR:-$(cd "$SCRIPT_DIR/../.." && pwd)}}"
+TRIGGER_FACT_TEXT_AWK="$SCRIPT_DIR/lib/trigger-fact-text.awk"
+if [ ! -r "$TRIGGER_FACT_TEXT_AWK" ]; then
+  printf '%s\n' 'ERROR: derive-trigger-facts: missing core/scripts/lib/trigger-fact-text.awk' >&2
+  exit 1
+fi
+TRANSCRIPT_TAIL_LIB="$SCRIPT_DIR/lib/transcript-tail.sh"
+if [ ! -r "$TRANSCRIPT_TAIL_LIB" ]; then
+  printf '%s\n' 'ERROR: derive-trigger-facts: missing core/scripts/lib/transcript-tail.sh' >&2
+  exit 1
+fi
+. "$TRANSCRIPT_TAIL_LIB"
+
+# Parse the hook payload once. The old per-field jget() helper launched jq for
+# every scalar, then the policy hook launched this script twice for a single
+# PreToolUse/UserPromptSubmit fire. NUL-delimited records preserve embedded
+# newlines in commands and prompts; JSON strings containing NUL were already
+# unsupported by bash command substitution on the old path.
+JSON_FIELDS=()
+if [ -n "$JQ" ]; then
+  while IFS= read -r -d '' json_field; do
+    JSON_FIELDS+=("$json_field")
+  done < <(
+    printf '%s' "$STDIN_JSON" | "$JQ" -rj '
+      def text:
+        if . == null then ""
+        elif type == "string" then .
+        else tostring
+        end;
+      [
+        (.tool_name // ""),
+        (.tool_input.command // ""),
+        (.tool_input.run_in_background // ""),
+        (if .tool_response == null then ""
+         elif (.tool_response | type) == "string" then .tool_response
+         else (.tool_response | tostring)
+         end),
+        (.prompt // ""),
+        (.cwd // ""),
+        (.session_id // ""),
+        (.transcript_path // "")
+      ] | .[] | text + "\u0000"
+    ' 2>/dev/null
+  )
+fi
+
+TOOL="${JSON_FIELDS[0]:-}"
+COMMAND="${JSON_FIELDS[1]:-}"
+RUN_IN_BACKGROUND="${JSON_FIELDS[2]:-}"
+TOOL_RESPONSE="${JSON_FIELDS[3]:-}"
+PROMPT="${JSON_FIELDS[4]:-}"
+PAYLOAD_CWD="${JSON_FIELDS[5]:-}"
+PAYLOAD_SESSION_ID="${JSON_FIELDS[6]:-}"
+TRANSCRIPT_PATH="${JSON_FIELDS[7]:-}"
+
+# match_keywords <text> — emit (newline-separated) the OPEN fact set for <text>:
+# every word token present (case-insensitive), plus the non-literal derived
+# tokens (secret / shared_branch) and structured filename / slash-command tokens.
+match_keywords() {
+  printf '%s\n' "$1" | awk -v mode=all -f "$TRIGGER_FACT_TEXT_AWK"
+}
+
+# --- company: a SESSION-IDENTITY fact, resolved once per payload (US-004) ---
+# Company is not look-back content; it identifies the active tenant. It is
+# derived with the SAME precedence as inject-policy-on-trigger.sh DIRS —
+#   HQ_POLICY_COMPANY env override > cwd companies/<slug> > session-meta
+#   company_slug (workspace/sessions/$session_id/meta.yaml).
+# A paired primary/AssistantIntent derivation shares this resolution, but each
+# resulting fact set still receives the same `company` token it would alone.
+CWD="$PAYLOAD_CWD"; [ -z "$CWD" ] && CWD="${CLAUDE_PROJECT_DIR:-$PWD}"
+SESSION_ID="$PAYLOAD_SESSION_ID"
+co_scope=""
+if [ -n "${HQ_POLICY_COMPANY:-}" ]; then
+  co_scope="$HQ_POLICY_COMPANY"
+else
+  case "$CWD" in
+    *companies/*)
+      co_path="${CWD##*companies/}"
+      co_scope="${co_path%%/*}"
+      ;;
+  esac
+  if [ -z "$co_scope" ] && [ -n "$SESSION_ID" ]; then
+    # Read the session's own meta.yaml directly (awk idiom from
+    # master-hook.sh:119); READ ONLY, never via hq-session.sh get.
+    META="$HQ_ROOT/workspace/sessions/$SESSION_ID/meta.yaml"
+    [ -f "$META" ] && co_scope="$(awk '$1 == "company_slug:" { sub(/^[^:]+:[[:space:]]*/, ""); gsub(/^"|"$/, ""); print; exit }' "$META")"
+  fi
+fi
+COMPANY_FACT=""
+[ -n "$co_scope" ] && COMPANY_FACT="company"
+
+FACTS=""
+FACTS_OUTPUT=""
+add() { FACTS="$FACTS $*"; }
+
+# Preserve the existing splitting and first-seen ordering but do it in one awk
+# process instead of awk | tr | sed. `FACTS` only contains space/newline token
+# boundaries from the existing match_keywords contract.
+normalize_facts() {
+  FACTS_OUTPUT="$(printf '%s\n' $FACTS | awk -v mode=normalize -v branch="$branch" -f "$TRIGGER_FACT_TEXT_AWK")"
+}
+
+# derive_event <event> sets FACTS_OUTPUT. It does not write stdout so paired
+# mode can run both channels in this one process without a second hook launch.
+derive_event() {
+  local event="$1" lookback_text branch=""
+  FACTS=""
+
+  # `always` is present in every fact set so `when: always` is the canonical
+  # "no condition" expression (used by SessionStart-introduced advisory policies).
+  add always
+
+  case "$event" in
+    PreToolUse|PostToolUse)
+      case "$TOOL" in
+        Bash)
+          if [ "$event" = "PreToolUse" ]; then
+            add "$(match_keywords "$COMMAND")"
+            # structured: a harness-tracked background task (`run_in_background:
+            # true`) -> `run_in_background`, so a policy can tell a backgrounded
+            # poll loop from the same command run in the foreground.
+            [ "$RUN_IN_BACKGROUND" = "true" ] && add run_in_background
+          else
+            # PostToolUse: derive from the tool OUTPUT, not the input command.
+            add "$(match_keywords "$TOOL_RESPONSE")"
+          fi
+          ;;
+        "" ) : ;;
+        * )
+          # non-Bash tool -> lowercased tool name token (PreToolUse mainly)
+          if [ "$event" = "PreToolUse" ]; then
+            add "$(printf '%s' "$TOOL" | tr '[:upper:]' '[:lower:]')"
+          else
+            add "$(match_keywords "$TOOL_RESPONSE")"
+          fi
+          ;;
+      esac
+      ;;
+    UserPromptSubmit)
+      add "$(match_keywords "$PROMPT")"
+      ;;
+  esac
+
+  [ -n "$COMPANY_FACT" ] && add "$COMPANY_FACT"
+
+  # The dedicated channel for "what the assistant said it would do" — assistant
+  # text emitted since the last user turn in transcript_path. No command/prompt
+  # tokens are mixed in; the raw PreToolUse/UserPromptSubmit fact sets deliberately
+  # exclude this look-back so the two channels stay crisp. (Company, above, is the
+  # one session-identity fact shared across channels.)
+  if [ "$event" = "AssistantIntent" ]; then
+    if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ] && [ -n "$JQ" ]; then
+      lookback_text="$("$JQ" -nr '
+        # Real Claude Code transcript: each line is {type, message:{role,content}}
+        # where assistant text lives at .message.content[] | select(.type=="text")
+        # | .text. Fall back to a flat top-level .content (string) for simple
+        # fixtures. (Mirrors enforce-capability-link-render.sh / capture-estimates.sh.)
+        reduce inputs as $e ("";
+          ($e.type // "") as $ty
+          | (($e.message.content // $e.content) as $c
+             | if   ($c|type)=="array"  then ([$c[]? | select(.type=="text") | .text] | join(" "))
+               elif ($c|type)=="string" then $c
+               else "" end) as $txt
+          | if $ty == "user" then ""
+            elif $ty == "assistant" then . + (if length > 0 then " " else "" end) + $txt
+            else . end
+        )
+      ' < <(hq_transcript_tail "$TRANSCRIPT_PATH") 2>/dev/null)"
+      [ -n "$lookback_text" ] && add "$(match_keywords "$lookback_text")"
+    fi
+  else
+    # Best-effort static session facts (repo / shared_branch), primary events
+    # only. AssistantIntent is facts-from-AI-only except for `company` above.
+    case "$CWD" in
+      *repos/public/*|*repos/private/*) add repo ;;
+    esac
+    branch="$(git -C "$CWD" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+  fi
+
+  normalize_facts
+}
+
+derive_event "$EVENT"
+PRIMARY_FACTS="$FACTS_OUTPUT"
+if [ "$WITH_ASSISTANT_INTENT" = "1" ] \
+  && { [ "$EVENT" = "PreToolUse" ] || [ "$EVENT" = "UserPromptSubmit" ]; }; then
+  derive_event AssistantIntent
+  printf '%s\n%s\n' "$PRIMARY_FACTS" "$FACTS_OUTPUT"
+else
+  printf '%s\n' "$PRIMARY_FACTS"
+fi

package/assets/scaffold/core/scripts/lib/transcript-tail.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Shared bounded reads for JSONL transcripts on hot hook paths.
+
+HQ_TRANSCRIPT_TAIL_MAX_BYTES=1048576
+
+# hq_transcript_size <path>
+# Report the file's exact byte size from filesystem metadata without reading
+# its contents.
+hq_transcript_size() {
+  [ "$#" -eq 1 ] || return 2
+  local path="$1" size=""
+  size="$(stat -L -c %s "$path" 2>/dev/null || true)"
+  case "$size" in
+    ''|*[!0-9]*)
+      size="$(stat -L -f %z "$path" 2>/dev/null || true)"
+      ;;
+  esac
+  case "$size" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  printf '%s\n' "$size"
+}
+
+# hq_transcript_tail <path> [max_bytes]
+# Keep a complete-line suffix of a JSONL transcript. The extra byte is a
+# boundary sentinel: when the tail starts mid-record, sed drops that partial
+# first line. If the byte window contains no complete line because the newest
+# record is oversized, return only that final record.
+hq_transcript_tail() {
+  [ "$#" -ge 1 ] && [ "$#" -le 2 ] || return 2
+  local path="$1" max_bytes="${2:-$HQ_TRANSCRIPT_TAIL_MAX_BYTES}" size
+  case "$max_bytes" in
+    ''|*[!0-9]*) return 2 ;;
+  esac
+  [ "$max_bytes" -gt 0 ] || return 2
+  size="$(hq_transcript_size "$path")" || {
+    printf '%s\n' "hq_transcript_tail: cannot read transcript size: $path" >&2
+    return 1
+  }
+  if [ "$size" -le "$((max_bytes + 1))" ]; then
+    cat "$path"
+    return $?
+  fi
+  local bounded_tail
+  bounded_tail="$(tail -c "$((max_bytes + 1))" "$path" | sed '1d'; printf '.')"
+  bounded_tail="${bounded_tail%.}"
+  if [ -n "$bounded_tail" ]; then
+    printf '%s' "$bounded_tail"
+  else
+    # The newest record itself may be larger than the byte window. Keep that
+    # complete record so safety and capture hooks can still inspect it.
+    tail -n 1 "$path"
+  fi
+}
+
+# hq_transcript_tail_with_latest_assistant <path> [max_bytes] [scan_cap_bytes]
+# Return the normal bounded suffix plus the latest complete assistant record
+# when later metadata records have pushed it outside that suffix. The fallback
+# scan is bounded; status 3 means the latest assistant could not be verified
+# within the cap and security-sensitive callers must fail closed.
+hq_transcript_tail_with_latest_assistant() {
+  [ "$#" -ge 1 ] && [ "$#" -le 3 ] || return 2
+  local path="$1" max_bytes="${2:-$HQ_TRANSCRIPT_TAIL_MAX_BYTES}"
+  local scan_cap="${3:-16777216}" size normal_tail assistant_record scan_tail
+  case "$scan_cap" in ''|*[!0-9]*) return 2 ;; esac
+  [ "$scan_cap" -gt 0 ] || return 2
+
+  normal_tail="$(hq_transcript_tail "$path" "$max_bytes")" || return $?
+  assistant_record="$(printf '%s\n' "$normal_tail" | jq -Rrc 'fromjson? | select(.type == "assistant")' | tail -n 1)"
+  if [ -n "$assistant_record" ]; then
+    [ -z "$normal_tail" ] || printf '%s\n' "$normal_tail"
+    return 0
+  fi
+
+  size="$(hq_transcript_size "$path")" || {
+    printf '%s\n' "hq_transcript_tail_with_latest_assistant: cannot read transcript size: $path" >&2
+    return 1
+  }
+  if [ "$size" -le "$scan_cap" ]; then
+    scan_tail="$(cat "$path"; printf '.')"
+  else
+    scan_tail="$(tail -c "$((scan_cap + 1))" "$path" | sed '1d'; printf '.')"
+  fi
+  scan_tail="${scan_tail%.}"
+  assistant_record="$(printf '%s\n' "$scan_tail" | jq -Rrc 'fromjson? | select(.type == "assistant")' | tail -n 1)"
+  if [ -n "$assistant_record" ]; then
+    printf '%s\n' "$assistant_record"
+    [ -z "$normal_tail" ] || printf '%s\n' "$normal_tail"
+    return 0
+  fi
+
+  if [ "$size" -gt "$scan_cap" ]; then
+    printf '%s\n' "hq_transcript_tail_with_latest_assistant: latest assistant record exceeds the ${scan_cap}-byte verification window" >&2
+    return 3
+  fi
+
+  [ -z "$normal_tail" ] || printf '%s\n' "$normal_tail"
+}

package/assets/scaffold/core/scripts/lib/trigger-fact-text.awk

@@ -0,0 +1,86 @@
+# Shared source for non-literal text facts derived by derive-trigger-facts.sh
+# and the adapter policy-vocabulary prefilter. Keep every text-derived fact
+# here so the prefilter cannot drift from the real policy trigger path.
+function hq_is_shared_branch(t) {
+  return t ~ /(^|[^a-z0-9_])(main|master|staging|production)([^a-z0-9_]|$)/ || t ~ /release\//
+}
+
+function hq_emit_derived_text_facts(t) {
+  if (t ~ /(^|[^a-z0-9_])aws_profile/ || t ~ /op:\/\/|\.env([^a-z0-9]|$)/) print "secret"
+  if (hq_is_shared_branch(t)) print "shared_branch"
+  if (t ~ /(^|[^a-z0-9])sk-[a-z0-9]/ \
+     || t ~ /(^|[^a-z0-9])(gh[opsur]_|github_pat_)[a-z0-9_]/ \
+     || t ~ /(^|[^a-z0-9])akia[a-z0-9][a-z0-9]/ \
+     || t ~ /(^|[^a-z0-9])xox[bpsa]-[a-z0-9]/ \
+     || t ~ /(^|[^a-z0-9])glpat-[a-z0-9]/ \
+     || t ~ /-----begin[a-z -]*private key/ \
+     || t ~ /(^|[^a-z0-9])bearer[ ][a-z0-9._-][a-z0-9._-][a-z0-9._-]/) {
+    print "apikey"
+    print "secret"
+  }
+  if (t ~ /successfully (merged|deployed|pushed|published|created)/ \
+     || t ~ /(deployment|deploy|build|release) (complete|completed|succeeded|ready)/ \
+     || t ~ /merged pull request/ \
+     || t ~ /pull request #?[0-9]+ .* merged/) print "completed"
+}
+
+{
+  if (NR > 1) text = text "\n"
+  text = text $0
+}
+
+END {
+  t = tolower(text)
+  if (mode == "derived") {
+    hq_emit_derived_text_facts(t)
+    if (hq_is_shared_branch(tolower(branch))) print "shared_branch"
+    exit
+  }
+  if (mode == "normalize") {
+    rest = t
+    while (match(rest, /[^[:space:]]+/)) {
+      fact = substr(rest, RSTART, RLENGTH)
+      rest = substr(rest, RSTART + RLENGTH)
+      if (!seen[fact]++) {
+        if (out != "") out = out " "
+        out = out fact
+      }
+    }
+    if (hq_is_shared_branch(tolower(branch)) && !seen["shared_branch"]++) {
+      if (out != "") out = out " "
+      out = out "shared_branch"
+    }
+    printf "%s", out
+    exit
+  }
+
+  # Open tokenization: every word token in the text becomes a fact. Tokens are
+  # letter-led and length >= 2; underscores and internal hyphens are retained.
+  tw = t
+  while (match(tw, /[a-z][a-z0-9_-]+/)) {
+    print substr(tw, RSTART, RLENGTH)
+    tw = substr(tw, RSTART + RLENGTH)
+  }
+  hq_emit_derived_text_facts(t)
+
+  # File references emit their basename and extension as facts.
+  tmp = t
+  while (match(tmp, "\\.?[a-z0-9_][a-z0-9_./-]*\\.[a-z][a-z0-9]+")) {
+    fn = substr(tmp, RSTART, RLENGTH)
+    tmp = substr(tmp, RSTART + RLENGTH)
+    bn = fn
+    sub(/.*\//, "", bn)
+    ext = bn
+    sub(/.*\./, "", ext)
+    print "." ext
+    print bn
+  }
+
+  # Slash-command mentions emit /command facts; paths such as repos/public do not.
+  tmp2 = " " t
+  while (match(tmp2, " /[a-z][a-z0-9-]*")) {
+    sc = substr(tmp2, RSTART + 1, RLENGTH - 1)
+    tmp2 = substr(tmp2, RSTART + RLENGTH)
+    print sc
+  }
+}

package/dist/bin/hq-auth-refresh.d.ts

@@ -14,6 +14,10 @@ import "../node-preflight.js";
 import { acquireCurrentPackageUseLease } from "../utils/package-use-lease.js";
 import "../node-network-compat.js";
 import type { refreshCachedSession } from "../utils/cognito-session.js";
-export declare function runAuthRefresh(refreshSession?: typeof refreshCachedSession): Promise<number>;
+type RefreshSession = (options?: {
+    minValiditySeconds?: number;
+}) => ReturnType<typeof refreshCachedSession>;
+export declare function runAuthRefresh(refreshSession?: RefreshSession): Promise<number>;
 export declare function startAuthRefresh(acquireLease?: typeof acquireCurrentPackageUseLease): Promise<number>;
+export {};
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -17,12 +17,44 @@ import { acquireCurrentPackageUseLease } from "../utils/package-use-lease.js";
 import "../node-network-compat.js";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+const MIN_VALIDITY_FLAG = "--min-validity-seconds";
+function parseMinimumValiditySeconds(argv, env) {
+    let raw;
+    let fromFlag = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === MIN_VALIDITY_FLAG) {
+            raw = argv[index + 1];
+            fromFlag = true;
+            if (!raw || raw.startsWith("--")) {
+                throw new Error(`${MIN_VALIDITY_FLAG} requires a non-negative integer`);
+            }
+            break;
+        }
+        if (arg.startsWith(`${MIN_VALIDITY_FLAG}=`)) {
+            raw = arg.slice(MIN_VALIDITY_FLAG.length + 1);
+            fromFlag = true;
+            break;
+        }
+    }
+    if (!fromFlag)
+        raw = env.HQ_AUTH_MIN_VALIDITY_SECONDS || undefined;
+    if (raw === undefined)
+        return undefined;
+    const value = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(value)) {
+        throw new Error("minimum token validity must be a non-negative integer");
+    }
+    // Values above the provider's cache margin are clamped by cognito-session.
+    return value;
+}
 export async function runAuthRefresh(refreshSession) {
     const { finishSentrySession, Sentry } = await import("../sentry.js");
     const { refreshCachedSession: refresh } = await import("../utils/cognito-session.js");
     let exitCode = 1;
     try {
-        const result = await (refreshSession ?? refresh)();
+        const minValiditySeconds = parseMinimumValiditySeconds(process.argv.slice(2), process.env);
+        const result = await (refreshSession ?? refresh)(minValiditySeconds === undefined ? {} : { minValiditySeconds });
         if (result.refreshed) {
             exitCode = 0;
         }