@rubytech/create-maxy 1.0.794 → 1.0.796

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.794",
+  "version": "1.0.796",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/neo4j/migrations/003-person-name-eradicate.cypher

@@ -0,0 +1,24 @@
+// ============================================================
+// Migration 003 — Person.name eradication (Task 849)
+//
+// Removes the denormalised `name` property from every Person node.
+// `Person.name` is forbidden by schema-base.md "Forbidden Properties":
+// the canonical fields are `givenName` + `familyName`, composed at
+// read time by display-helpers.ts. Persisted `name` was a divergence
+// trap — LLM extraction emitted `name = givenName` ("Dan") alongside
+// the structured pair, so the canvas rendered "Dan" instead of
+// "Dan Brett".
+//
+// Idempotent: subsequent runs find no Persons with `name` set and
+// return removed=0.
+//
+// Applied at boot by platform/ui/app/lib/neo4j-migrations.ts. Safe to
+// run manually:
+//   cypher-shell -u neo4j -p <password> -a $NEO4J_URI \
+//     -f platform/neo4j/migrations/003-person-name-eradicate.cypher
+// ============================================================
+
+MATCH (p:Person)
+WHERE p.name IS NOT NULL
+REMOVE p.name
+RETURN count(p) AS removed

package/payload/platform/plugins/admin/hooks/__tests__/archive-ingest-gate.test.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# Regression test for archive-ingest-gate.sh (Task 846).
+#
+# Six cases cover the contract:
+#   1. Edit on /platform/plugins/<x>/lib/* is BLOCKED (exit 2).
+#   2. Edit on a benign path is ALLOWED (exit 0).
+#   3. Bash with `npx vitest` is BLOCKED.
+#   4. PostToolUse on whatsapp-export-parse with isError:true sets the flag.
+#   5. Subsequent PreToolUse on ANY tool is BLOCKED (post-parse-error gate).
+#   6. UserPromptSubmit clears the flag, restoring normal allow behavior.
+#
+# Tests use ARCHIVE_INGEST_GATE_STATE_DIR to point at a tmp dir so they run
+# without a real account layout.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/archive-ingest-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+# Per-run isolated state dir
+STATE_DIR=$(mktemp -d)
+export ARCHIVE_INGEST_GATE_STATE_DIR="$STATE_DIR"
+FLAG_FILE="$STATE_DIR/archive-ingest-parse-error.flag"
+
+cleanup() { rm -rf "$STATE_DIR"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Case 1 — Edit on plugin lib path: BLOCKED
+run_case "Edit on platform/plugins/whatsapp-import/lib/src/parse-export.ts → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/whatsapp-import/lib/src/parse-export.ts","old_string":"a","new_string":"b"}}' \
+  2
+
+# Case 2 — Edit on a benign path: ALLOWED
+run_case "Edit on README.md → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/README.md","old_string":"a","new_string":"b"}}' \
+  0
+
+# Case 3 — Bash with `npx vitest`: BLOCKED
+run_case "Bash 'npx vitest run parse-export.test.ts' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run parse-export.test.ts"}}' \
+  2
+
+# Case 3b — Bash with benign command: ALLOWED
+run_case "Bash 'ls -la' → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
+  0
+
+# Case 3c — Bash with `bun test`: BLOCKED
+run_case "Bash 'bun test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bun test"}}' \
+  2
+
+# Case 3d — Bash with `npm test`: BLOCKED
+run_case "Bash 'npm test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' \
+  2
+
+# Make sure flag is absent before parse-error simulation
+rm -f "$FLAG_FILE"
+
+# Case 4 — PostToolUse on whatsapp-export-parse with isError:true sets flag
+run_case "PostToolUse parse-error sets flag (exit 0, flag side-effect)" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":true,"content":[{"type":"text","text":"parse-error file=_chat.txt line=1 reason=not-a-_chat.txt"}]}}' \
+  0
+
+if [[ -f "$FLAG_FILE" ]]; then
+  echo "PASS: parse-error flag created at $FLAG_FILE"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: parse-error flag NOT created at $FLAG_FILE" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Case 5 — Subsequent PreToolUse on ANY tool BLOCKED while flag is fresh
+run_case "PreToolUse Read after parse-error → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  2
+
+run_case "PreToolUse Bash after parse-error → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}' \
+  2
+
+# Case 6 — UserPromptSubmit clears flag
+run_case "UserPromptSubmit clears flag (exit 0)" \
+  '{"hook_event_name":"UserPromptSubmit","prompt":"retry"}' \
+  0
+
+if [[ ! -f "$FLAG_FILE" ]]; then
+  echo "PASS: UserPromptSubmit cleared flag"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: UserPromptSubmit did NOT clear flag" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Case 7 — After clearance, normal allow resumes
+run_case "PreToolUse Read after clearance → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# Case 8 — PostToolUse with isError:false does NOT set flag
+rm -f "$FLAG_FILE"
+run_case "PostToolUse parse-success (isError:false) does NOT set flag" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":false,"content":[{"type":"text","text":"{\"parsedLines\":[]}"}]}}' \
+  0
+
+if [[ ! -f "$FLAG_FILE" ]]; then
+  echo "PASS: parse-success leaves flag absent"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: parse-success incorrectly created flag" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Case 9 — Stale flag (>600s) auto-clears + allows
+PAST=$(( $(date -u +%s) - 700 ))
+echo "$PAST" > "$FLAG_FILE"
+run_case "Stale flag auto-clears, PreToolUse Read → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# Case 10 — No stdin (terminal) fails closed
+echo "Probing fail-closed behaviour (no stdin)..."
+bash "$HOOK" </dev/null >/dev/null 2>/dev/null
+ACTUAL=$?
+# /dev/null IS a stdin — the `[ -t 0 ]` check tests for terminal, not file.
+# A file/pipe stdin reads as empty, which produces empty hook_event_name and
+# falls through to default `exit 0` (allow). The terminal-only fail-closed
+# branch can't be tested non-interactively; verify the script reads `[ -t 0 ]`.
+if grep -q '\[ -t 0 \]' "$HOOK"; then
+  echo "PASS: fail-closed terminal check is present"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: fail-closed terminal check missing" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo
+echo "──────── archive-ingest-gate test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+if [[ "$FAIL" -gt 0 ]]; then
+  exit 1
+fi
+exit 0

package/payload/platform/plugins/admin/hooks/archive-ingest-gate.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Archive-ingest gate (Task 846).
+#
+# Three enforcements, one script — phase decided by `hook_event_name` on stdin:
+#
+# 1. PreToolUse Edit/Write/NotebookEdit: deny writes under
+#    `*platform/plugins/*/lib/*` (parser/CSV-shape source for any *-import or
+#    *-export plugin). The database-operator subagent has Read+Bash but not
+#    Edit/Write per its `tools:` frontmatter — yet it can still mutate files
+#    via Bash heredoc. The path block applies to every tool that takes a
+#    `file_path` and has been observed as the improvisation surface.
+#
+# 2. PreToolUse Bash: deny commands invoking JavaScript test runners
+#    (vitest|bun test|npm test|npx jest|node .*vitest). The reproducer
+#    incident (conv 47c6a590) saw the operator run all four variants in
+#    sequence after parse-export returned isError.
+#
+# 3. Parse-error gate: PostToolUse on any `mcp__*__*-export-parse` /
+#    `mcp__*__*-import-parse` tool whose `tool_response.isError == true`
+#    writes a flag file. Subsequent PreToolUse on ANY tool blocks until
+#    UserPromptSubmit clears the flag (semantics: "subagent's next action
+#    must be a user-facing message; further tool calls blocked"). A 600s
+#    TTL is the cross-session safety net.
+#
+# Exit codes follow Claude Code hook protocol: 0 = allow, 2 = block (stderr
+# message shown to the agent). Fail-closed on stdin read failure to match
+# pre-tool-use.sh.
+
+set -uo pipefail
+
+# Read stdin — fail closed if unavailable
+if [ -t 0 ]; then
+  echo "Blocked: archive-ingest-gate received no stdin (cannot inspect tool call). Failing closed." >&2
+  exit 2
+fi
+INPUT=$(cat)
+
+# ----- Resolve account dir for state file ----------------------------------
+# Mirrors pre-tool-use.sh lines 100-107: walk from this hook's location to
+# platform/, then `../data/accounts/<single-account>/`. Phase 0 has exactly
+# one account directory.
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+PLATFORM_ROOT_RESOLVED="${HOOK_DIR}/../../.."
+ACCOUNTS_DIR="${PLATFORM_ROOT_RESOLVED}/../data/accounts"
+ACCOUNT_DIR=""
+if [ -d "$ACCOUNTS_DIR" ]; then
+  ACCOUNT_DIR=$(find "$ACCOUNTS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | head -1)
+fi
+# Test harness override — tests pass `ARCHIVE_INGEST_GATE_STATE_DIR` to point
+# at a tmp dir without needing a real account layout.
+STATE_DIR="${ARCHIVE_INGEST_GATE_STATE_DIR:-${ACCOUNT_DIR}/state}"
+FLAG_FILE="${STATE_DIR}/archive-ingest-parse-error.flag"
+TTL_SECONDS=600
+
+# ----- Parse fields from stdin ---------------------------------------------
+# Hook protocol: every event includes `hook_event_name`. PreToolUse +
+# PostToolUse include `tool_name`. PostToolUse adds `tool_response`.
+# UserPromptSubmit has neither. Use grep/sed against the JSON envelope —
+# no jq dependency to match the rest of the hook fleet.
+HOOK_EVENT=$(printf '%s' "$INPUT" | grep -o '"hook_event_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+TOOL_NAME=$(printf '%s' "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+
+# ============================================================================
+# UserPromptSubmit — clear the parse-error flag.
+# ============================================================================
+if [ "$HOOK_EVENT" = "UserPromptSubmit" ]; then
+  if [ -f "$FLAG_FILE" ]; then
+    rm -f "$FLAG_FILE" 2>/dev/null
+    echo "[archive-ingest-gate] cleared reason=user-prompt-submit" >&2
+  fi
+  exit 0
+fi
+
+# ============================================================================
+# PostToolUse — record parse-error from any *-export-parse / *-import-parse.
+# ============================================================================
+if [ "$HOOK_EVENT" = "PostToolUse" ]; then
+  case "$TOOL_NAME" in
+    mcp__*__*-export-parse|mcp__*__*-import-parse)
+      # Inspect tool_response for isError true. Body is a JSON object; match
+      # `"isError":true` with optional whitespace.
+      if printf '%s' "$INPUT" | grep -Eq '"isError"[[:space:]]*:[[:space:]]*true'; then
+        mkdir -p "$STATE_DIR" 2>/dev/null
+        date -u +%s > "$FLAG_FILE" 2>/dev/null
+        echo "[archive-ingest-gate] surfaced reason=parse-error tool=${TOOL_NAME}" >&2
+      fi
+      ;;
+  esac
+  # PostToolUse must always allow the tool result through.
+  exit 0
+fi
+
+# ============================================================================
+# PreToolUse — three independent blocks.
+# ============================================================================
+if [ "$HOOK_EVENT" != "PreToolUse" ]; then
+  # Unknown event, or hook fired in a context without an event name. Allow.
+  exit 0
+fi
+
+# --- Block 1: post-parse-error gate (applies to ALL tools) -----------------
+if [ -f "$FLAG_FILE" ]; then
+  FLAG_TS=$(cat "$FLAG_FILE" 2>/dev/null | head -1)
+  NOW=$(date -u +%s)
+  if [ -n "$FLAG_TS" ] && [ "$FLAG_TS" -gt 0 ] 2>/dev/null; then
+    AGE=$(( NOW - FLAG_TS ))
+    if [ "$AGE" -lt "$TTL_SECONDS" ]; then
+      echo "[archive-ingest-gate] block tool=${TOOL_NAME} reason=post-parse-error age_s=${AGE}" >&2
+      echo "Blocked: an archive-parser MCP tool returned isError=true earlier in this turn. The subagent's next action must be a user-facing message naming the parse-error and yielding back to the operator. Further tool calls are blocked until the operator submits a new prompt." >&2
+      exit 2
+    fi
+    # Stale flag — clean up so we don't keep blocking on a corpse.
+    rm -f "$FLAG_FILE" 2>/dev/null
+  else
+    # Unparseable flag — remove rather than block on garbage.
+    rm -f "$FLAG_FILE" 2>/dev/null
+  fi
+fi
+
+# --- Block 2: plugin-source path block (Edit/Write/NotebookEdit) -----------
+case "$TOOL_NAME" in
+  Edit|Write|NotebookEdit)
+    FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+    case "$FILE_PATH" in
+      */platform/plugins/*/lib/*|platform/plugins/*/lib/*)
+        echo "[archive-ingest-gate] block tool=${TOOL_NAME} reason=plugin-source-edit path=${FILE_PATH}" >&2
+        echo "Blocked: ${TOOL_NAME} on ${FILE_PATH} is a platform plugin lib/ path. The database-operator subagent does not own plugin source; if a parser is broken, surface the parse-error to the operator and let them dispatch a code-edit task instead." >&2
+        exit 2
+        ;;
+    esac
+    ;;
+esac
+
+# --- Block 3: shell test-runner block (Bash) -------------------------------
+if [ "$TOOL_NAME" = "Bash" ]; then
+  COMMAND=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+  # Match any of: `vitest`, `bun test`, `npm test`, `npx jest`, `node ... vitest`.
+  # Word-boundary checks via grep -E with explicit token boundaries — POSIX
+  # `[[:space:]]` covers leading-token edge cases, end-of-string covers tail.
+  if printf '%s' "$COMMAND" | grep -Eq '(^|[[:space:]/])vitest($|[[:space:]])|(^|[[:space:]])bun[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npm[[:space:]]+test($|[[:space:]])|(^|[[:space:]])npx[[:space:]]+jest($|[[:space:]])|node[[:space:]].*vitest'; then
+    echo "[archive-ingest-gate] block tool=Bash reason=test-runner command=${COMMAND}" >&2
+    echo "Blocked: Bash command invokes a JavaScript test runner (vitest/bun test/npm test/npx jest). The database-operator subagent does not run plugin tests; surface the parse-error to the operator." >&2
+    exit 2
+  fi
+fi
+
+exit 0

package/payload/platform/plugins/docs/references/internals.md

@@ -317,6 +317,10 @@ This tool is read-only and available to both public and admin agents.
 
 Each row in the Conversations modal exposes a `View logs` row-action that opens a popover with three links — **Stream**, **Errors**, **SSE** — each of which targets `/api/admin/logs?type={stream|error|sse}&conversationId={full-id}` in a new tab. The row's 8-char id chip is click-to-copy; hover reveals the full `conversationId` as a tooltip. See `.docs/web-chat.md` "In-chat retrieval" for the route contract and `console.debug` observability (Task 686).
 
+### Cross-tab session rotation (Task 848)
+
+When you click "New conversation" in the chat tab, {{productName}} mints a fresh admin session key on the server and clears the old one. Sibling admin tabs (`/graph`, `/data`) opened in the same browser keep working without re-login: the chat tab broadcasts the new key on a same-origin channel so each sibling tab updates its captured key instantly, and any in-flight admin request that 401s with the rotation-orphan code retries once after re-reading the latest key from per-tab storage. If neither path recovers (browser locked down, second 401 after retry, session expired), the tab shows a single banner — "Your admin session was renewed in another tab. Click to reload." — and one click sends you back through login. No silent 401s; no re-clicking through the same trash icon hoping it sticks. See `.docs/web-chat.md` "Cross-tab rotation contract (Task 848)" for the wire-level `code` taxonomy and observability surfaces.
+
 ---
 
 ## Context Assembly — How Retrieved Knowledge Reaches the Agent

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/SKILL.md

@@ -68,6 +68,8 @@ When the owner is an external Person (non-operator archive), the anchor is the c
 
 **Doctrine:** raw Cypher and `cypher-shell` invocations are forbidden in this skill and its references. Writes route through `mcp__memory__memory-archive-write` (bulk archives) or `mcp__memory__memory-write` / `mcp__memory__memory-update` (single-node enrichments like `profile.md`). If a CSV needs a write shape no current MCP tool supports, file a task to extend `memory-archive-write` with a new `archiveType` handler — never improvise via Bash. See [database-operator's LOUD-FAIL prerogative](../../../../templates/specialists/agents/database-operator.md#prerogatives).
 
+**LOUD-FAIL on parse errors (structurally enforced, Task 846).** When LinkedIn parser tools land that follow the `mcp__*__*-import-parse` naming convention, the harness-level `platform/plugins/admin/hooks/archive-ingest-gate.sh` will record an `isError: true` response and block every subsequent tool call this turn until the operator submits the next prompt. The hook also denies edits to `platform/plugins/*/lib/*` and JavaScript test runners (`vitest`, `bun test`, `npm test`, `npx jest`) unconditionally. The skill's "no Bash improvisation" doctrine above is the contract; the hook is the enforcement. See [.docs/hooks.md](../../../../../.docs/hooks.md) for the full gate surface.
+
 ## Selective-ingest threshold (bulk archives)
 
 A LinkedIn export typically contains 3,000–10,000 connections. Writing all of them in one shot defeats compression-on-write — most rows will never be queried, and the noise compounds with every subsequent ingest. The skill compresses by interrogating the operator before bulk writes.

package/payload/platform/plugins/memory/PLUGIN.md

@@ -94,9 +94,11 @@ Restricted fields (`accountId`, `embedding`, `profileVersion`) cannot be set via
 
 ## Schema References
 
-Before any structured write, load `references/schema-base.md` via `plugin-read`. This defines property naming rules, required-property groups for documented types, and relationship patterns. If the `LocalBusiness` node has a `businessType` property, also load the matching vertical schema (`references/schema-{businessType}.md`) — it extends the base with vertical-specific types. Confirm which schemas were consulted before writing.
+Before any structured write, load `references/schema-base.md` via `plugin-read`. This defines property naming rules, required-property groups for documented types, forbidden-property rules, and relationship patterns. If the `LocalBusiness` node has a `businessType` property, also load the matching vertical schema (`references/schema-{businessType}.md`) — it extends the base with vertical-specific types. Confirm which schemas were consulted before writing.
 
-**Validation surface (Task 736).** `memory-write` validates labels against `db.labels()` ∪ `schema.cypher` declarations — not against this markdown. A label is recognised if it appears in either set. The markdown defines property *shape* (required-property groups, naming rules) for documented labels only; recognised-but-undocumented labels (e.g. `LocalBusiness`, `AdminUser`, `KnowledgeDocument`) accept any property shape and emit `[schema-validator] markdown-undocumented label=<X>` so the doc gap is visible to operators. If `memory-write` rejects a label as unknown, the rejection lists both source sets — the agent can call `maxy-graph-get_neo4j_schema` to refresh its view.
+**Validation surface (Task 736).** `memory-write` validates labels against `db.labels()` ∪ `schema.cypher` declarations — not against this markdown. A label is recognised if it appears in either set. The markdown defines property *shape* (required-property groups, naming rules, forbidden-property rules) for documented labels only; recognised-but-undocumented labels (e.g. `LocalBusiness`, `AdminUser`, `KnowledgeDocument`) accept any property shape and emit `[schema-validator] markdown-undocumented label=<X>` so the doc gap is visible to operators. If `memory-write` rejects a label as unknown, the rejection lists both source sets — the agent can call `maxy-graph-get_neo4j_schema` to refresh its view.
+
+**Forbidden properties (Task 849).** A "Forbidden Properties" table in any schema markdown file declares per-label deny-listed property keys. The validator rejects writes that include a forbidden key for the matching primary label and emits `[schema-validator] outcome=rejected label=<X> property=<Y> reason=forbidden writer=<agentName>`. The first row is `Person | name` — use `givenName` + `familyName` (rendered display name composed at read time). The check fires after the synonym pass, so `firstName → givenName` rewrites still happen first.
 
 ## Document Ingestion
 

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -860,9 +860,9 @@ if (!readOnly) {
             .min(1)
             .describe("IANA timezone the operator confirmed (e.g. 'Europe/London', 'America/New_York', 'UTC'). Each parsed timestamp is emitted as ISO 8601 with the offset that this zone holds for the wall-clock instant — DST is handled correctly."),
         dateFormat: z
-            .enum(["DD/MM/YY", "MM/DD/YY"])
+            .enum(["DD/MM/YY", "MM/DD/YY", "DD/MM/YYYY", "MM/DD/YYYY"])
             .optional()
-            .describe("Date ordering the export uses. Defaults to DD/MM/YY (WhatsApp's default in most locales). Pass MM/DD/YY for US-locale exports — confirm with the operator before passing this."),
+            .describe("Date ordering and year shape. Omit for auto-detect (Task 845): the parser probes the first matched line as DD/MM and locks that ordering if range-valid; otherwise locks MM/DD. Year shape is independent — both 2-digit (legacy) and 4-digit (modern) years are accepted within the same file. Pass an explicit value only when the operator confirms a US-locale export or when auto-detect would mis-lock on a manually concatenated multi-locale archive."),
     }, async ({ filePath, timezone, dateFormat }) => {
         try {
             const result = await whatsappExportParse({