@indigoai-us/hq-cli 5.290.0 → 5.291.0

package/assets/scaffold/core/scripts/hq-session.sh

@@ -27,6 +27,46 @@
 
 set -euo pipefail
 
+# Prefer the CLI-hosted implementation only when it advertises the exact-company
+# directory check. Older CLI bundles may recognize hq-session but still accept
+# case aliases, so they must use this in-tree implementation instead.
+# HQ_HQ_SESSION_NO_CLI=1 forces the in-tree path.
+if [ "${HQ_HQ_SESSION_NO_CLI:-}" != "1" ]; then
+  __hs_hq="$(command -v hq 2>/dev/null || true)"
+  if [ -n "$__hs_hq" ]; then
+    # `hq core --help` costs seconds of node startup, so probe it at most once
+    # per CLI build and cache the answer. Key by resolved path + mtime + size so
+    # a PATH switch or same-second rebuild cannot reuse a stale result; keep the
+    # cache in a private 0700 dir and trust it only when we own it; never persist
+    # a failed probe. HQ_CLI_CAPS_CACHE overrides the path (tests isolate it).
+    __hs_mt="$(stat -c %Y "$__hs_hq" 2>/dev/null || stat -f %m "$__hs_hq" 2>/dev/null || echo 0)"
+    __hs_sz="$(stat -c %s "$__hs_hq" 2>/dev/null || stat -f %z "$__hs_hq" 2>/dev/null || echo 0)"
+    __hs_key="$(printf '%s' "$__hs_hq:$__hs_mt:$__hs_sz" | cksum 2>/dev/null | cut -d' ' -f1)"
+    if [ -n "${HQ_CLI_CAPS_CACHE:-}" ]; then
+      __hs_cache="$HQ_CLI_CAPS_CACHE"
+    else
+      __hs_dir="${XDG_CACHE_HOME:-${HOME:-/tmp}/.cache}/hq-cli"
+      mkdir -p "$__hs_dir" 2>/dev/null && chmod 700 "$__hs_dir" 2>/dev/null || true
+      __hs_cache="$__hs_dir/core-caps.${__hs_key:-0}"
+    fi
+    __hs_caps=""
+    if [ -r "$__hs_cache" ] && [ -O "$__hs_cache" ]; then
+      __hs_caps="$(cat "$__hs_cache" 2>/dev/null || true)"
+    elif __hs_caps="$(hq core --help 2>/dev/null)"; then
+      [ -n "$__hs_caps" ] && (umask 077; printf '%s' "$__hs_caps" >"$__hs_cache" 2>/dev/null) || true
+    else
+      __hs_caps=""
+    fi
+    case "$__hs_caps" in
+      *hq-session*)
+        case "$__hs_caps" in
+          *exact-company-directory-match-v1*) exec hq core hq-session "$@" ;;
+        esac
+        ;;
+    esac
+  fi
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # The DATA tree (sessions, companies, hooks) is the live HQ root. When this
 # script is dispatched as `hq core hq-session` from inside the hq-cli package,
@@ -43,6 +83,44 @@ LIB_DIR="$SCRIPT_DIR/lib"
 # shellcheck source=lib/session-id.sh
 . "$LIB_DIR/session-id.sh"
 
+# These checks stay local so hq-session remains usable by fixtures and bundled
+# copies that include its capability and ID libraries but not auto-bind.
+hq_session_has_exact_company_dir() {
+  local root="${1:-}" slug="${2:-}" company_dir
+  [ -n "$root" ] && [ -n "$slug" ] || return 1
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    [ "${company_dir##*/}" = "$slug" ] && return 0
+  done
+  return 1
+}
+
+hq_session_has_case_alias() {
+  local root="${1:-}" slug="${2:-}" company_dir company_slug slug_fold company_fold
+  [ -n "$root" ] && [ -n "$slug" ] || return 1
+
+  # Exact, real entries are the common case. Check them before starting any
+  # case-fold subprocesses on SessionStart or a normal company bind.
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    company_slug="${company_dir##*/}"
+    [ "$company_slug" = "$slug" ] && return 1
+  done
+
+  slug_fold="$(printf '%s' "$slug" | LC_ALL=C tr '[:upper:]' '[:lower:]')"
+  for company_dir in "$root"/companies/*; do
+    [ -d "$company_dir" ] || continue
+    [ -L "$company_dir" ] && continue
+    company_slug="${company_dir##*/}"
+    [ "$company_slug" = "$slug" ] && continue
+    company_fold="$(printf '%s' "$company_slug" | LC_ALL=C tr '[:upper:]' '[:lower:]')"
+    [ "$company_fold" = "$slug_fold" ] && return 0
+  done
+  return 1
+}
+
 # Set by the --session-id global option; empty means "resolve it".
 SESSION_ID_OVERRIDE=""
 
@@ -78,7 +156,19 @@ cmd_get() {
   [ -n "$key" ] || { echo "usage: hq-session.sh get <key>" >&2; exit 1; }
   local meta
   meta="$(current_meta)"
+  # Missing meta.yaml: no keys to read. Print nothing, exit 0.
+  # Unreadable meta.yaml: awk fails and this function exits non-zero under
+  # set -e. Those two are not the same case — do not default either.
   [ -n "$meta" ] && [ -f "$meta" ] || return 0
+  # Absent key: print nothing. For `senior`, a record written before that
+  # field existed has no line; that is a successful read of a file that does
+  # not contain the key, not a failed read. §3.1 defaults `senior` to `user`
+  # at write time (the seed in cmd_set / master-hook.sh). This getter does
+  # not invent that default, so "never written" stays distinguishable from
+  # an explicit `senior: user`. Authority walkers apply the §3.1 default at
+  # the walk site. Substituting `user` here would collapse absence into the
+  # permissive value that hq-never-swallow-errors and
+  # monitor-unknown-paths-must-not-resolve-to-healthy forbid.
   awk -v k="$key" '
     $1 == k":" {
       sub(/^[^:]+:[[:space:]]*/, "")
@@ -93,10 +183,9 @@ cmd_set() {
   local key="${1:-}" value="${2:-}"
   [ -n "$key" ] && [ $# -ge 2 ] || { echo "usage: hq-session.sh set <key> <value>" >&2; exit 1; }
 
-  # Reject an invalid company_slug BEFORE writing anything. Otherwise a bad value
-  # lands in meta.yaml and only fails later at session_scope_mint, leaving
-  # corrupt state that the scope gate would read as a (bogus) binding. Mirrors
-  # session_scope_mint's own character-set rule; `personal` is a valid slug.
+  # Reject invalid company_slug values before writing anything. A case alias
+  # could otherwise bind the session and surface policies from a differently
+  # named company directory on a case-insensitive filesystem.
   if [ "$key" = "company_slug" ] && [ -n "$value" ]; then
     case "$value" in
       *[!a-zA-Z0-9_-]*)
@@ -104,6 +193,45 @@ cmd_set() {
         exit 1
         ;;
     esac
+    if [ "$value" != "personal" ] && {
+      [ -L "$REPO_ROOT/companies/$value" ] \
+        || hq_session_has_case_alias "$REPO_ROOT" "$value"
+    }; then
+      echo "hq-session: company_slug must use the exact real directory name: '$value'" >&2
+      exit 1
+    fi
+  fi
+
+  # Reject an invalid senior BEFORE writing anything. Otherwise a bad value
+  # lands in meta.yaml and only fails later when the authority walk reads it,
+  # leaving corrupt state that hop 2 would treat as a real parent. Same shape
+  # as the company_slug guard above.
+  #
+  # Accepted forms: user | session:<id> | lane:<id>.
+  # <id> charset is A-Za-z0-9._- — company_slug's a-z0-9_- plus `.` (hostnames
+  # contain dots) plus A-Z because lane ids on this box are ULID_hostname
+  # (e.g. 01M30KHSEX50K0G203QNV2590N_ip-172-31-47-133-ec2-internal; ULIDs are
+  # Crockford base32, typically uppercase) and session ids are UUID hex
+  # (e.g. 0026e2dd-7fff-4733-8d61-9a6fe7004908). `.` and `..` are rejected as
+  # ids: they are path segments under workspace/sessions/.
+  if [ "$key" = "senior" ]; then
+    local senior_ok=0 senior_id
+    case "$value" in
+      user)
+        senior_ok=1
+        ;;
+      session:*|lane:*)
+        senior_id="${value#*:}"
+        case "$senior_id" in
+          ""|.|..|*[!A-Za-z0-9._-]*) ;;
+          *) senior_ok=1 ;;
+        esac
+        ;;
+    esac
+    if [ "$senior_ok" != 1 ]; then
+      echo "hq-session: invalid senior: '$value' (accepted forms: user, session:<id>, lane:<id>)" >&2
+      exit 1
+    fi
   fi
 
   local id meta
@@ -115,9 +243,10 @@ cmd_set() {
   meta="$SESSIONS_DIR/$id/meta.yaml"
   mkdir -p "$(dirname "$meta")"
   # Seed the same header master-hook.sh writes, so binding a session the hook
-  # has not bootstrapped yet still produces a well-formed record.
+  # has not bootstrapped yet still produces a well-formed record. `senior: user`
+  # is the §3.1 default so hop 2 of the authority walk has a field to read.
   if [ ! -f "$meta" ]; then
-    printf 'session_id: %s\nstarted_at: "%s"\n' \
+    printf 'session_id: %s\nstarted_at: "%s"\nsenior: user\n' \
       "$id" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$meta"
   fi
 
@@ -159,6 +288,29 @@ cmd_set() {
       spawn_work_mesh_register "$id" || true
     fi
   fi
+
+  # US-011: mid-session project change closes the old card and opens a new one.
+  # First bind (empty prev) only updates the live-binding marker — SessionStart
+  # already emitted session_start (or reconcile will bind without a card flip).
+  if [ "$key" = "project" ] && [ -n "$value" ] && [ "$value" != "$prev" ]; then
+    local co tk
+    co="$(cmd_get company_slug 2>/dev/null || true)"
+    tk="$(cmd_get task 2>/dev/null || true)"
+    if [ -f "$REPO_ROOT/core/scripts/lib/work-mesh-enqueue.sh" ] && \
+       [ -f "$REPO_ROOT/core/scripts/lib/work-mesh-live-rebind.sh" ]; then
+      # shellcheck source=lib/work-mesh-enqueue.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-enqueue.sh" 2>/dev/null || true
+      # shellcheck source=lib/work-mesh-live-hook.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-live-hook.sh" 2>/dev/null || true
+      # shellcheck source=lib/work-mesh-live-rebind.sh
+      . "$REPO_ROOT/core/scripts/lib/work-mesh-live-rebind.sh" 2>/dev/null || true
+      if [ -n "$prev" ] && command -v work_mesh_live_rebind >/dev/null 2>&1; then
+        work_mesh_live_rebind "$id" "$co" "$prev" "$tk" "$co" "$value" "$tk" || true
+      elif command -v work_mesh_live_write_binding_marker >/dev/null 2>&1; then
+        work_mesh_live_write_binding_marker "$id" "$co" "$value" "$tk" || true
+      fi
+    fi
+  fi
 }
 
 # Spawn the client-side Work Mesh registration hook, detached, for a mid-session
@@ -167,15 +319,16 @@ cmd_set() {
 # and this backgrounds even its fast foreground path off cmd_set's return path.
 spawn_work_mesh_register() {
   local sid="$1"
-  local hook="$REPO_ROOT/core/hooks/work-mesh-register.sh"
+  local hook="$REPO_ROOT/core/hooks/SessionStart/35-work-mesh-session-start.sh"
   local logf="$REPO_ROOT/workspace/logs/work-mesh-hook.log"
-  [ -x "$hook" ] || return 0
+  [ -f "$hook" ] || return 0
   command -v jq >/dev/null 2>&1 || return 0
   local ev
   ev="$(jq -nc --arg sid "$sid" --arg cwd "${PWD:-}" '{session_id:$sid,cwd:$cwd}' 2>/dev/null)" || return 0
   [ -n "$ev" ] || return 0
   mkdir -p "$(dirname "$logf")" 2>/dev/null || true
-  HQ_ROOT="$REPO_ROOT" nohup bash -c 'printf "%s" "$1" | "$2" company_slug' _ "$ev" "$hook" \
+  HQ_ROOT="$REPO_ROOT" CLAUDE_CODE_SESSION_ID="$sid" \
+    nohup bash -c 'printf "%s" "$1" | bash "$2" SessionStart' _ "$ev" "$hook" \
     >>"$logf" 2>&1 </dev/null &
   disown 2>/dev/null || true
   return 0
@@ -183,15 +336,18 @@ spawn_work_mesh_register() {
 
 # Print a company's hard-enforcement policies, read directly from the policy
 # files (the pre-built digest was retired — the when/on trigger hook is now the
-# sole policy-surfacing path). Emits one `- [hard] **slug**: rule` line each,
-# deduped (digest/README/example/sync-conflict copies are skipped) and budgeted
-# (HQ_COMPANY_BIND_POLICY_CAP lines / HQ_COMPANY_BIND_POLICY_BYTES bytes, with a
-# non-silent pointer for the overflow). An unbounded dump — observed at ~298
-# lines for a large tenant — buries the rules it exists to surface; the
-# reactive trigger hook re-injects any withheld policy when its trigger fires.
+# sole policy-surfacing path). Emits one `- [hard] **id**: rule` line per policy,
+# including its exact source path so IDs do not have to match filenames. Lines
+# are deduped (digest/README/example/sync-conflict copies are skipped) and
+# budgeted (HQ_COMPANY_BIND_POLICY_CAP lines / HQ_COMPANY_BIND_POLICY_BYTES
+# bytes, with a non-silent pointer for the overflow). An unbounded dump —
+# observed at ~298 lines for a large tenant — buries the rules it exists to
+# surface; the reactive trigger hook re-injects any withheld policy when its
+# trigger fires.
 emit_company_hard_policies() {
   local co="$1"
   local dir="$REPO_ROOT/companies/$co/policies"
+  hq_session_has_exact_company_dir "$REPO_ROOT" "$co" || return 0
   [ -d "$dir" ] || return 0
   # Collect real policy files only. Skip the generated digest, docs, examples,
   # and sync-conflict duplicates: policy slugs never contain spaces, so a space
@@ -209,13 +365,15 @@ emit_company_hard_policies() {
   done
   [ "${#files[@]}" -gt 0 ] || return 0
   local lines
-  lines="$(awk '
+  lines="$(awk -v co="$co" '
     function bn(p,  n,a,b){ n=split(p,a,"/"); b=a[n]; sub(/\.md$/,"",b); return b }
-    function flush(){ if(enf=="hard" && rule!=""){ if(id=="")id=bn(fn); printf "- [hard] **%s**: %s\n", id, rule } }
+    function policy_file(p,  n,a){ n=split(p,a,"/"); return a[n] }
+    function flush(){ if(enf=="hard" && rule!=""){ if(id=="")id=bn(fn); printf "- [hard] **%s**: %s Full text: `companies/%s/policies/%s`.\n", id, rule, co, policy_file(fn) } }
     FNR==1 { if(seen) flush(); d=0;id="";enf="";rule="";rsec=0;rcap=0;fn=FILENAME;seen=1 }
     /^---[ \t]*$/ { d++; next }
     d==1 && /^id:/          { s=$0; sub(/^id:[ \t]*/,"",s); gsub(/^["'"'"']|["'"'"']$/,"",s); id=s; next }
     d==1 && /^enforcement:/ { s=$0; sub(/^enforcement:[ \t]*/,"",s); gsub(/[ \t]/,"",s); enf=s; next }
+    d==1 && /^status:[ \t]*retired/ { enf="" ; next }
     d>=2 && /^## Rule[ \t]*$/ { rsec=1; next }
     d>=2 && rsec && /^## / { rsec=0 }
     d>=2 && rsec && !rcap && NF { line=$0; gsub(/\*\*/,"",line); if(length(line)>160)line=substr(line,1,157)"..."; rule=line; rcap=1 }
@@ -226,11 +384,14 @@ emit_company_hard_policies() {
   # (glob order), never silent — overflow is summarized with a pointer so the
   # withheld policies stay one command away.
   local cap="${HQ_COMPANY_BIND_POLICY_CAP:-32}"
-  local max_bytes="${HQ_COMPANY_BIND_POLICY_BYTES:-40960}"
+  # 2026-09-07: was 40960. Claude Code persists hook output above ~10,000
+  # bytes and shows the model a 2 KB preview, so a 40 KB digest was never
+  # read. Keep the whole digest under the host ceiling with margin.
+  local max_bytes="${HQ_COMPANY_BIND_POLICY_BYTES:-7168}"
   printf '\n<company-policy-digest co="%s">\n' "$co"
   printf '# %s hard-enforcement policies (auto-surfaced on company bind)\n' "$co"
   printf '> Company context just bound mid-session. These HARD rules now apply.\n'
-  printf '> Full text: `companies/%s/policies/{slug}.md` (or `qmd get -c %s {slug}`).\n\n' "$co" "$co"
+  printf '> Full text: open the file path shown on each policy line. Browse `companies/%s/policies/` for the full set.\n\n' "$co"
   printf '%s\n' "$lines" | awk -v cap="$cap" -v maxb="$max_bytes" -v co="$co" '
     NF {
       n++
@@ -242,8 +403,8 @@ emit_company_hard_policies() {
     END {
       dropped = n - kept
       if (dropped > 0)
-        printf "\n> %d more hard %s not shown (bind budget: %d policies / %d bytes). Full set: `companies/%s/policies/` or `qmd get -c %s {slug}`; matching rules re-surface via the policy trigger hook when they apply.\n", \
-          dropped, (dropped == 1 ? "policy" : "policies"), cap, maxb, co, co
+        printf "\n> %d more hard %s not shown (bind budget: %d policies / %d bytes). Browse `companies/%s/policies/` for the full set; matching rules re-surface via the policy trigger hook when they apply.\n", \
+          dropped, (dropped == 1 ? "policy" : "policies"), cap, maxb, co
     }'
   printf '</company-policy-digest>\n'
 }

package/assets/scaffold/core/scripts/jobs-schedule-parse.sh

@@ -0,0 +1,310 @@
+#!/usr/bin/env bash
+# hq-core: public
+# jobs-schedule-parse.sh — resolve natural-language (or raw cron) schedules for /schedule.
+#
+# Usage:
+#   core/scripts/jobs-schedule-parse.sh [--tz IANA] [--json] "<schedule text>"
+#
+# Prints one JSON object on stdout:
+#   {"ok":true,"cron":"0 9 * * 1-5","timezone":"America/Los_Angeles",
+#    "human":"Every weekday at 9:00 AM (America/Los_Angeles)","source":"nl"|"cron"}
+#   {"ok":false,"error":"..."}
+#
+# Cron is always the canonical 5-field form. NL is never echoed back as storage.
+# Timezone defaults to the host IANA zone (macOS /etc/localtime, $TZ, or UTC).
+#
+# Requires: node. Optional: jq (not required for parse).
+
+set -euo pipefail
+
+TZ_OVERRIDE=""
+
+usage() {
+  echo "usage: jobs-schedule-parse.sh [--tz IANA] \"<nl or cron schedule>\"" >&2
+  exit 2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --tz)
+      [ "$#" -ge 2 ] || usage
+      TZ_OVERRIDE="$2"
+      shift 2
+      ;;
+    --json)
+      # JSON is the only output mode; flag kept for callers/docs symmetry
+      shift
+      ;;
+    -h|--help)
+      usage
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "jobs-schedule-parse: unknown flag: $1" >&2
+      usage
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+[ "$#" -ge 1 ] || usage
+SCHEDULE="$*"
+SCHEDULE="$(printf '%s' "$SCHEDULE" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+[ -n "$SCHEDULE" ] || {
+  printf '%s\n' '{"ok":false,"error":"empty schedule"}'
+  exit 1
+}
+
+export JOBS_SCHEDULE_PARSE_INPUT="$SCHEDULE"
+export JOBS_SCHEDULE_PARSE_TZ="${TZ_OVERRIDE}"
+
+node <<'JS'
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const inp = (process.env.JOBS_SCHEDULE_PARSE_INPUT || "").trim();
+const tzOverride = (process.env.JOBS_SCHEDULE_PARSE_TZ || "").trim();
+
+function fail(msg, code = 1) {
+  process.stdout.write(JSON.stringify({ ok: false, error: msg }));
+  process.stdout.write("\n");
+  process.exit(code);
+}
+
+function detectTz() {
+  if (tzOverride) return tzOverride;
+  const envTz = (process.env.TZ || "").trim();
+  if (envTz && envTz.includes("/")) return envTz;
+  try {
+    const link = fs.realpathSync("/etc/localtime");
+    const parts = link.split(path.sep).filter(Boolean);
+    const i = parts.indexOf("zoneinfo");
+    if (i >= 0) {
+      const cand = parts.slice(i + 1).join("/");
+      if (cand) return cand;
+    }
+  } catch (_) {
+    /* ignore */
+  }
+  try {
+    const out = execFileSync(
+      "timedatectl",
+      ["show", "-p", "Timezone", "--value"],
+      { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }
+    ).trim();
+    if (out && out.includes("/")) return out;
+  } catch (_) {
+    /* ignore */
+  }
+  return "UTC";
+}
+
+function validateIana(tz) {
+  const wellFormed = /^(UTC|[A-Za-z0-9_+\-]+(\/[A-Za-z0-9_+\-]+)+)$/;
+  if (!wellFormed.test(tz)) return false;
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return true;
+  } catch (_) {
+    // Intl may lack tzdata on some hosts — accept well-formed names
+    return wellFormed.test(tz);
+  }
+}
+
+const CRON_RE = /^(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)$/;
+
+const DOW_NAMES = {
+  sun: 0,
+  sunday: 0,
+  mon: 1,
+  monday: 1,
+  tue: 2,
+  tues: 2,
+  tuesday: 2,
+  wed: 3,
+  wednesday: 3,
+  thu: 4,
+  thur: 4,
+  thurs: 4,
+  thursday: 4,
+  fri: 5,
+  friday: 5,
+  sat: 6,
+  saturday: 6,
+};
+
+const DOW_LABEL = {
+  "0": "Sunday",
+  "1": "Monday",
+  "2": "Tuesday",
+  "3": "Wednesday",
+  "4": "Thursday",
+  "5": "Friday",
+  "6": "Saturday",
+  "1-5": "weekday",
+  "*": "day",
+};
+
+function parseClock(fragment) {
+  const s = fragment.trim().toLowerCase().replace(/ /g, "");
+  const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/.exec(s);
+  if (!m) return null;
+  let hour = parseInt(m[1], 10);
+  const minute = parseInt(m[2] || "0", 10);
+  const ampm = m[3];
+  if (minute > 59) return null;
+  if (ampm) {
+    if (hour < 1 || hour > 12) return null;
+    if (ampm === "am") hour = hour === 12 ? 0 : hour;
+    else hour = hour === 12 ? 12 : hour + 12;
+  } else if (hour > 23) {
+    return null;
+  }
+  return [hour, minute];
+}
+
+function fmtClock(hour, minute) {
+  const suffix = hour < 12 ? "AM" : "PM";
+  let h12 = hour % 12;
+  if (h12 === 0) h12 = 12;
+  return `${h12}:${String(minute).padStart(2, "0")} ${suffix}`;
+}
+
+function humanizeCron(cron, tz) {
+  const parts = cron.split(/\s+/);
+  if (parts.length !== 5) return `Cron \`${cron}\` (${tz})`;
+  const [minute, hour, dom, month, dow] = parts;
+  if (
+    /^\d+$/.test(minute) &&
+    /^\d+$/.test(hour) &&
+    dom === "*" &&
+    month === "*" &&
+    (dow === "*" || dow === "1-5")
+  ) {
+    const clock = fmtClock(parseInt(hour, 10), parseInt(minute, 10));
+    if (dow === "1-5") return `Every weekday at ${clock} (${tz})`;
+    return `Every day at ${clock} (${tz})`;
+  }
+  if (
+    /^\d+$/.test(minute) &&
+    /^\d+$/.test(hour) &&
+    dom === "*" &&
+    month === "*" &&
+    /^\d+$/.test(dow)
+  ) {
+    const day = DOW_LABEL[dow] || `day ${dow}`;
+    return `Every ${day} at ${fmtClock(parseInt(hour, 10), parseInt(minute, 10))} (${tz})`;
+  }
+  if (minute.startsWith("*/") && hour === "*" && dom === "*" && month === "*" && dow === "*") {
+    return `Every ${minute.slice(2)} minutes (${tz})`;
+  }
+  if (minute === "0" && hour.startsWith("*/") && dom === "*" && month === "*" && dow === "*") {
+    return `Every ${hour.slice(2)} hours (${tz})`;
+  }
+  if (minute === "0" && hour === "*" && dom === "*" && month === "*" && dow === "*") {
+    return `Every hour on the hour (${tz})`;
+  }
+  return `Cron \`${cron}\` (${tz})`;
+}
+
+function parseNl(text) {
+  const s = text.trim();
+  const low = s.toLowerCase();
+  let m = /^every\s+(\d+)\s+minutes?$/.exec(low);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (n < 1 || n > 59) return [null, "minute interval must be 1..59"];
+    return [`*/${n} * * * *`, `Every ${n} minutes`];
+  }
+  if (low === "every hour" || low === "hourly") {
+    return ["0 * * * *", "Every hour on the hour"];
+  }
+  m = /^every\s+(\d+)\s+hours?$/.exec(low);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (n < 1 || n > 23) return [null, "hour interval must be 1..23"];
+    return [`0 */${n} * * *`, `Every ${n} hours`];
+  }
+  m = /^(?:every\s+)?(weekday|weekdays|day|daily)\s+(?:at\s+)?(.+)$/.exec(low);
+  if (m) {
+    const kind = m[1];
+    const clock = parseClock(m[2]);
+    if (!clock) return [null, `could not parse time: ${m[2]}`];
+    const [hour, minute] = clock;
+    if (kind === "weekday" || kind === "weekdays") {
+      return [`${minute} ${hour} * * 1-5`, `Every weekday at ${fmtClock(hour, minute)}`];
+    }
+    return [`${minute} ${hour} * * *`, `Every day at ${fmtClock(hour, minute)}`];
+  }
+  m =
+    /^(?:every\s+)?(sun(?:day)?|mon(?:day)?|tue(?:s|sday)?|wed(?:nesday)?|thu(?:r|rs|rsday)?|fri(?:day)?|sat(?:urday)?)s?\s+(?:at\s+)?(.+)$/.exec(
+      low
+    );
+  if (m) {
+    const dow = DOW_NAMES[m[1]];
+    const clock = parseClock(m[2]);
+    if (!clock) return [null, `could not parse time: ${m[2]}`];
+    const [hour, minute] = clock;
+    return [
+      `${minute} ${hour} * * ${dow}`,
+      `Every ${DOW_LABEL[String(dow)]} at ${fmtClock(hour, minute)}`,
+    ];
+  }
+  m = /^at\s+(.+?)\s+every\s+(weekday|weekdays|day|daily)$/.exec(low);
+  if (m) {
+    const clock = parseClock(m[1]);
+    if (!clock) return [null, `could not parse time: ${m[1]}`];
+    const [hour, minute] = clock;
+    const kind = m[2];
+    if (kind === "weekday" || kind === "weekdays") {
+      return [`${minute} ${hour} * * 1-5`, `Every weekday at ${fmtClock(hour, minute)}`];
+    }
+    return [`${minute} ${hour} * * *`, `Every day at ${fmtClock(hour, minute)}`];
+  }
+  return [
+    null,
+    "unrecognized schedule — try 'every weekday at 9am', " +
+      "'every day at 14:30', 'every monday at 9am', a 5-field cron, " +
+      "or 'every 15 minutes'",
+  ];
+}
+
+const tz = detectTz();
+if (!validateIana(tz)) fail(`invalid IANA timezone: ${tz}`);
+
+if (CRON_RE.test(inp) && !/[A-Za-z]/.test(inp)) {
+  const cron = inp;
+  const human = humanizeCron(cron, tz);
+  process.stdout.write(
+    JSON.stringify({ ok: true, cron, timezone: tz, human, source: "cron" })
+  );
+  process.stdout.write("\n");
+  process.exit(0);
+}
+
+const named = /^(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(mon-fri|monday-friday)$/i.exec(inp);
+if (named) {
+  const cron = `${named[1]} ${named[2]} ${named[3]} ${named[4]} 1-5`;
+  const human = humanizeCron(cron, tz);
+  process.stdout.write(
+    JSON.stringify({ ok: true, cron, timezone: tz, human, source: "cron" })
+  );
+  process.stdout.write("\n");
+  process.exit(0);
+}
+
+const [cron, humanOrErr] = parseNl(inp);
+if (cron == null) fail(humanOrErr);
+
+const human = `${humanOrErr} (${tz})`;
+process.stdout.write(
+  JSON.stringify({ ok: true, cron, timezone: tz, human, source: "nl" })
+);
+process.stdout.write("\n");
+JS