@rubytech/create-realagent 1.0.866 → 1.0.868

package/payload/platform/lib/graph-search/src/index.ts

@@ -92,6 +92,20 @@ export interface ScoredNode {
   properties: Record<string, unknown>;
   vectorScore: number;
   bm25Score: number;
+  /**
+   * Task 967 — true when this node entered the merge map via the BM25 path
+   * with a raw Lucene score > 0 (literal-token match against the universal
+   * fulltext index), or via the keyword-subscriptions property-lookup path.
+   * Set BEFORE bm25 normalisation, so a single-hit set whose normalised
+   * value collapses to 0.0 still carries the flag.
+   *
+   * Read by the vector-threshold filter as the carve-out predicate: rows
+   * with weak cosine survive when `bm25Hit` is true (operator's literal
+   * tokens override the semantic similarity floor). Without this flag the
+   * naive `bm25Score > 0` check would drop every bottom-of-set BM25 row
+   * because min-max normalisation pins the lowest score to 0.
+   */
+  bm25Hit: boolean;
 }
 
 export type SearchMode = "hybrid" | "bm25";
@@ -124,6 +138,23 @@ export interface HybridParams extends Bm25OnlyParams {
    * false so embed failure surfaces loudly.
    */
   degradeOnEmbedFailure?: boolean;
+  /**
+   * Task 967 — minimum raw vector cosine in [0,1] required for a row to
+   * pass the merge step. Rows below the threshold are dropped UNLESS they
+   * also entered via the BM25 path (`bm25Hit === true`) — that carve-out
+   * preserves literal-token matches whose embedding happened to score
+   * mediocre. Counts surface in HybridResponse so callers can render an
+   * "N suppressed — show all" affordance.
+   *
+   * Undefined ⇒ no threshold (legacy behaviour; memory MCP keeps this).
+   * Zero ⇒ explicit "show all" override (admin route's /data and /graph
+   * surfaces use this when the operator clicks "show all").
+   *
+   * Calibration: see `DEFAULT_VECTOR_THRESHOLD` in
+   * `platform/ui/server/routes/admin/graph-search.ts` for the route's
+   * default; the lib itself takes no opinion on the value.
+   */
+  vectorThreshold?: number;
 }
 
 export interface HybridResponse {
@@ -139,6 +170,26 @@ export interface HybridResponse {
    * `expandHops === 0` or no merged results.
    */
   expandMs: number;
+  /**
+   * Task 967 — operator-facing threshold accounting.
+   *
+   * `rawMerged`     count of nodes in the merge map BEFORE the threshold
+   *                 filter ran (vector + BM25 + keyword-subscriptions
+   *                 union, deduped by nodeId).
+   * `suppressed`    count of nodes the threshold filter dropped.
+   *                 Always 0 when `vectorThreshold` is undefined.
+   * `bm25Bypass`    count of nodes that would have been dropped by the
+   *                 vector-cosine floor BUT survived because `bm25Hit`
+   *                 was true. Subset of the rendered set.
+   * `threshold`     the actual threshold applied (echoes the param);
+   *                 null when no filter ran. Drives the "show all"
+   *                 affordance: if null, no banner; if non-null and
+   *                 `suppressed > 0`, banner with count.
+   */
+  rawMerged: number;
+  suppressed: number;
+  bm25Bypass: number;
+  threshold: number | null;
 }
 
 export type EmbedFn = (text: string) => Promise<number[]>;
@@ -332,7 +383,21 @@ export async function hybrid(
       bm25Score: normalised[i] ?? 0,
       related: [],
     }));
-    return { mode: "bm25", results, embedError: msg, expandMs: 0 };
+    // Task 967 — threshold has no meaning in the degraded path: no embed
+    // happened, so there is no vector cosine to compare against. Surface
+    // counts in the response (rawMerged = rendered, suppressed = 0,
+    // bm25Bypass = 0, threshold = null) so the caller's render path is
+    // uniform across hybrid + degraded modes.
+    return {
+      mode: "bm25",
+      results,
+      embedError: msg,
+      expandMs: 0,
+      rawMerged: results.length,
+      suppressed: 0,
+      bm25Bypass: 0,
+      threshold: null,
+    };
   }
 
   const labelToIndex = await discoverIndexes(session);
@@ -350,7 +415,15 @@ export async function hybrid(
       .map((l) => labelToIndex.get(l))
       .filter((idx): idx is string => idx !== undefined);
     if (indexesToQuery.length === 0) {
-      return { mode: "hybrid", results: [], expandMs: 0 };
+      return {
+        mode: "hybrid",
+        results: [],
+        expandMs: 0,
+        rawMerged: 0,
+        suppressed: 0,
+        bm25Bypass: 0,
+        threshold: params.vectorThreshold ?? null,
+      };
     }
   } else {
     indexesToQuery = [...new Set(labelToIndex.values())];
@@ -402,6 +475,7 @@ export async function hybrid(
           properties: plainProperties(node.properties),
           vectorScore: score,
           bm25Score: 0,
+          bm25Hit: false,
         });
       }
     }
@@ -458,6 +532,7 @@ export async function hybrid(
       const existing = scoreMap.get(nodeId);
       if (existing) {
         existing.bm25Score = Math.max(existing.bm25Score, 1.0);
+        existing.bm25Hit = true;
       } else {
         const node = record.get("node") as { properties: Record<string, unknown> };
         scoreMap.set(nodeId, {
@@ -466,17 +541,48 @@ export async function hybrid(
           properties: plainProperties(node.properties),
           vectorScore: 0,
           bm25Score: 1.0,
+          bm25Hit: true,
         });
       }
     }
   }
 
-  // --- Merge & rank ---
-  const merged = [...scoreMap.values()]
-    .map((node) => ({
-      ...node,
-      combinedScore: VECTOR_WEIGHT * node.vectorScore + BM25_WEIGHT * node.bm25Score,
-    }))
+  // --- Merge, threshold, rank ---
+  //
+  // Task 967 — vectorThreshold filters BEFORE sort+slice. Order matters:
+  // slicing first would consume the slot budget with rows the threshold
+  // would have suppressed, under-filling the rendered set. Sorting before
+  // filtering would waste cycles ordering rows we are about to drop. So:
+  // filter -> sort -> slice. Counts (rawMerged / suppressed / bm25Bypass)
+  // are computed against the pre-filter and post-filter populations so the
+  // route can render "N suppressed — show all" without a second query.
+  //
+  // Carve-out: a row with vector cosine below the threshold survives iff
+  // bm25Hit is true. The flag (not bm25Score) is the gate — min-max
+  // normalisation pins the lowest BM25 row's score to 0.0, so checking
+  // bm25Score > 0 would silently drop a literal-token match that just
+  // happens to be the worst-scored BM25 hit in the set.
+  const allMerged = [...scoreMap.values()].map((node) => ({
+    ...node,
+    combinedScore: VECTOR_WEIGHT * node.vectorScore + BM25_WEIGHT * node.bm25Score,
+  }));
+  const rawMerged = allMerged.length;
+  const threshold = params.vectorThreshold;
+  let kept = allMerged;
+  let bm25Bypass = 0;
+  if (threshold !== undefined) {
+    kept = [];
+    for (const node of allMerged) {
+      if (node.vectorScore >= threshold) {
+        kept.push(node);
+      } else if (node.bm25Hit) {
+        kept.push(node);
+        bm25Bypass++;
+      }
+    }
+  }
+  const suppressed = rawMerged - kept.length;
+  const merged = kept
     .sort((a, b) => b.combinedScore - a.combinedScore)
     .slice(0, limit);
 
@@ -561,7 +667,15 @@ export async function hybrid(
     }
   }
 
-  return { mode: "hybrid", results, expandMs };
+  return {
+    mode: "hybrid",
+    results,
+    expandMs,
+    rawMerged,
+    suppressed,
+    bm25Bypass,
+    threshold: threshold ?? null,
+  };
 }
 
 function mergeBm25Hit(
@@ -572,6 +686,11 @@ function mergeBm25Hit(
   const existing = map.get(hit.nodeId);
   if (existing) {
     existing.bm25Score = Math.max(existing.bm25Score, normalisedScore);
+    // Task 967 — set bm25Hit irrespective of normalised value. The hit
+    // came from db.index.fulltext.queryNodes (raw Lucene score > 0 by
+    // construction); min-max normalisation pinning the lowest row to
+    // 0.0 is a presentation artefact, not a "no match" signal.
+    existing.bm25Hit = true;
   } else {
     map.set(hit.nodeId, {
       nodeId: hit.nodeId,
@@ -579,6 +698,7 @@ function mergeBm25Hit(
       properties: hit.properties,
       vectorScore: 0,
       bm25Score: normalisedScore,
+      bm25Hit: true,
     });
   }
 }

package/payload/platform/plugins/admin/skills/unzip-attachment/SKILL.md

@@ -17,18 +17,31 @@ The `[ATTACHMENTS:]` block is contractually present on every turn that originall
 These are not guidelines. Every one of them is mechanically enforced by the shell primitives below; if any check fails, abort the flow, emit the named log line, and tell the operator verbatim what tripped it.
 
 - **No byte of the archive may land outside `{accountDir}/extracted/{attachmentId}/`.** The destination is fresh per upload. Extraction uses `unzip -oq` into that directory and only that directory.
-- **Sum of declared uncompressed sizes must be ≤ `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in [platform/ui/app/lib/attachments.ts](../../../../ui/app/lib/attachments.ts)).** Checked via `unzip -Zt` *before* any write.
-- **No entry may be a symlink.** Checked via `unzip -Z1v` output parsing before extraction; the post-extraction loop also runs `find <dest> -type l` as a ground-truth backstop.
-- **Every extracted file's `realpath --relative-to <dest>` must not start with `../`.** This is the canonical zip-slip guard — it catches malicious entry names like `../../etc/passwd` that some older `unzip` builds silently accept.
-- **Password-protected archives are refused with a fixed message.** Never prompt for a key.
+- **Sum of declared uncompressed sizes must be ≤ `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in [platform/ui/app/lib/attachments.ts](../../../../ui/app/lib/attachments.ts)).** Checked by summing column 4 of `unzip -Z` output *before* any write.
+- **No entry may be a symlink.** Checked by parsing column 1 of `unzip -Z` output (permission column; leading `l` = symlink) before extraction; the post-extraction loop also runs `find <dest> -type l` as a ground-truth backstop.
+- **No entry name may start with `../`.** Checked by parsing the name column of `unzip -Z` output before extraction; the post-extraction `realpath --relative-to <dest>` loop is a defense-in-depth backstop for `unzip` versions that silently sanitise `../` during extraction.
+- **Password-protected archives are refused with a fixed message.** Detected by column 5 of `unzip -Z` output: a leading uppercase `T` or `B` (text/binary, encrypted) marks an encrypted entry. Never prompt for a key.
 
 See [references/safety.md](references/safety.md) for the precise shell commands, attack examples, and refusal templates.
 
 ## Flow
 
 1. **Resolve paths.** From the `[ATTACHMENTS:]` line read `attachmentId` and `storagePath`. Set `dest="${ACCOUNT_DIR}/extracted/${attachmentId}"`. Create it with `mkdir -p "$dest"`.
-2. **Pre-scan for password + symlink + byte total.** Run `unzip -Z -1 "$storagePath"` for the entry list; if it exits non-zero, the archive is corrupt or password-protected — refuse. Run `unzip -Z -v "$storagePath"` and scan the permission column for a leading `l` (symlink) — refuse on match. Run `unzip -Zt "$storagePath"` to obtain the summary line and parse the total uncompressed bytes; if > `100 * 1024 * 1024`, refuse.
-3. **Emit the start log line** — `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n>` — exactly once, before the extraction command.
+2. **Single-pass pre-flight.** One `unzip -Z "$storagePath"` invocation produces the zipinfo column listing; pipe through an awk parser that checks all four invariants in one read of the output. Non-zero exit from `unzip -Z` → corrupt archive, refuse with `unreadable reason=corrupt`. Otherwise the awk gates (in order: encrypted, symlink, zip-slip, oversize) fire the matching refusal log line and exit before extraction. Inline this single bash block — do **not** split into two or more `unzip` calls:
+   ```sh
+   ZINFO=$(unzip -Z "$storagePath" 2>&1) || { echo "[skill:unzip] unreadable attachmentId=$attachmentId reason=corrupt"; exit 1; }
+   echo "$ZINFO" | awk -v aid="$attachmentId" -v lim=$((100*1024*1024)) '
+     NR>2 && $1 ~ /^[-lrwxd?]/ {
+       if ($5 ~ /^[TB]/)           { print "[skill:unzip] unreadable attachmentId=" aid " reason=password"; bad=1; exit }
+       if ($1 ~ /^l/)              { print "[skill:unzip] symlink-blocked attachmentId=" aid " entry=" $9; bad=1; exit }
+       for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { print "[skill:unzip] zip-slip-blocked attachmentId=" aid " entry=" $i; bad=1; exit }
+       sum += $4
+     }
+     END { if (!bad && sum > lim) { print "[skill:unzip] oversize attachmentId=" aid " uncompressed=" sum " limit=" lim; bad=1 }; exit bad }
+   ' || exit 1
+   DECLARED_BYTES=$(echo "$ZINFO" | awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { print s+0 }')
+   ```
+3. **Emit the start log line** — `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n> preflightPasses=1` — exactly once, before the extraction command. The `preflightPasses=1` field is mandatory and always `1`; its absence in `server.log` after a clean upload means the skill was not invoked or step 2 was split into multiple passes (a regression).
 4. **Extract.** `unzip -oq "$storagePath" -d "$dest"`. Non-zero exit → refuse with the underlying `unzip` stderr quoted.
 5. **Post-extraction realpath check.** For every path emitted by `find "$dest" -mindepth 1 \( -type f -o -type l \)`:
    - If `-type l`, refuse with `symlink-blocked` (ground-truth guard — pre-scan caught most, this catches the rest).
@@ -45,7 +58,7 @@ On any refusal step the operator gets the refusal message verbatim, no re-try, n
 
 | When | Line |
 |------|------|
-| Before extraction | `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n>` |
+| Before extraction | `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n> preflightPasses=1` |
 | On success | `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>` |
 | Oversize refusal | `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600` |
 | Zip-slip refusal | `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>` |

package/payload/platform/plugins/admin/skills/unzip-attachment/__tests__/preflight.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Regression suite for the single-pass pre-flight prescribed by SKILL.md step 2.
+# Each test builds a fixture zip, runs the exact awk one-liners from SKILL.md
+# against `unzip -Z` output, and asserts the expected gate fires.
+#
+# Run from anywhere: `bash platform/plugins/admin/skills/unzip-attachment/__tests__/preflight.sh`
+# Exits 0 if all assertions pass, non-zero on the first failure.
+
+set -uo pipefail
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+PASS=0
+FAIL=0
+fail() { echo "FAIL: $1"; FAIL=$((FAIL+1)); }
+pass() { echo "PASS: $1"; PASS=$((PASS+1)); }
+
+# --- The four awk gates from SKILL.md step 2 -----------------------------------
+# Each takes `unzip -Z $zip` on stdin and exits 0 if the gate FIRES (attack
+# detected), non-zero if the zip is clean for that gate.
+
+detect_symlink()   { awk 'NR>2 && $1 ~ /^l/ { found=1; print $0 } END { exit !found }'; }
+detect_encrypted() { awk 'NR>2 && $5 ~ /^[TB]/ { found=1; print $0 } END { exit !found }'; }
+detect_slip()      { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { found=1; print $i } } END { exit !found }'; }
+sum_uncompressed() { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { print s+0 }'; }
+extract_names()    { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) printf "%s%s", $i, (i<NF?" ":"\n") }'; }
+
+LIMIT=$((100 * 1024 * 1024))
+
+# --- (a) Password-protected archive refused ----------------------------------
+cd "$WORK"
+echo "secret" > a-secret.txt
+zip -e -P testpass a-pw.zip a-secret.txt >/dev/null 2>&1
+if unzip -Z a-pw.zip 2>/dev/null | detect_encrypted >/dev/null; then
+  pass "(a) password — col-5 uppercase first letter detected"
+else
+  fail "(a) password — col-5 uppercase first letter NOT detected"
+fi
+
+# --- (b) Symlink entry refused -----------------------------------------------
+cd "$WORK"
+ln -s /etc/passwd b-link
+echo "ok" > b-ok.txt
+zip -y b-sym.zip b-link b-ok.txt >/dev/null 2>&1
+if unzip -Z b-sym.zip 2>/dev/null | detect_symlink >/dev/null; then
+  pass "(b) symlink — col-1 leading 'l' detected"
+else
+  fail "(b) symlink — col-1 leading 'l' NOT detected"
+fi
+
+# --- (c) Zip-slip entry refused by pre-scan ---------------------------------
+# The PRE-scan must detect `../`-prefixed entry names in `unzip -Z` column 9+
+# BEFORE extraction runs. macOS unzip silently sanitises these paths during
+# extraction (the file lands inside dest with `../` stripped), so the
+# post-extraction realpath check is a defense-in-depth backstop for unzip
+# versions that don't sanitise — not the primary gate.
+# zip(1) refuses `..` paths, so python forges the central-directory entry.
+cd "$WORK"
+python3 - <<'PY' >/dev/null 2>&1
+import zipfile
+with zipfile.ZipFile("c-slip.zip", "w") as z:
+    z.writestr("../../escapee.txt", "evil payload")
+    z.writestr("good.txt", "ok")
+PY
+if unzip -Z c-slip.zip 2>/dev/null | detect_slip >/dev/null; then
+  pass "(c) zip-slip — pre-scan caught '../' in entry name"
+else
+  fail "(c) zip-slip — pre-scan missed '../' in entry name"
+fi
+
+# --- (d) Oversize archive refused (declared > 100 MiB) -----------------------
+# Building a 100 MiB+ fixture is expensive on disk and CI. Instead, simulate
+# the awk gate against a synthetic `unzip -Z`-shaped fixture whose column-4
+# sum exceeds the limit. This tests the *gate logic*, not unzip itself.
+cd "$WORK"
+cat > d-zfake.txt <<'FAKE'
+Archive:  d-big.zip
+Zip file size: 999 bytes, number of entries: 2
+-rw-r--r--  3.0 unx 60000000 tx stor 26-May-10 21:08 big1.bin
+-rw-r--r--  3.0 unx 60000000 tx stor 26-May-10 21:08 big2.bin
+2 files, 120000000 bytes uncompressed, 999 bytes compressed:  0.0%
+FAKE
+SUM=$(sum_uncompressed < d-zfake.txt)
+if [ "$SUM" -gt "$LIMIT" ]; then
+  pass "(d) oversize — sum=$SUM > limit=$LIMIT detected"
+else
+  fail "(d) oversize — sum=$SUM did not exceed limit=$LIMIT (gate broken)"
+fi
+
+# --- (e) Clean zip = exactly 1 pre-flight + 1 extraction ---------------------
+cd "$WORK"
+mkdir e-stage && cd e-stage
+echo "alpha" > a.txt
+mkdir sub && echo "beta" > sub/b.txt
+zip -r ../e-clean.zip a.txt sub >/dev/null 2>&1
+cd "$WORK"
+
+# Wrap unzip in a tracer that increments a counter file per invocation, scoped
+# by the flag combination so we can count pre-flight vs extraction calls.
+TRACE_DIR=$(mktemp -d)
+mkdir -p "$TRACE_DIR/bin"
+cat > "$TRACE_DIR/bin/unzip" <<TRACE
+#!/usr/bin/env bash
+# Classify the call: -Z* = pre-flight (zipinfo mode), -o* = extraction.
+case "\$1" in
+  -Z*) echo "Z" >> "$TRACE_DIR/calls" ;;
+  -o*) echo "O" >> "$TRACE_DIR/calls" ;;
+  -t*) echo "T" >> "$TRACE_DIR/calls" ;;
+  *)   echo "?" >> "$TRACE_DIR/calls" ;;
+esac
+exec /usr/bin/unzip "\$@"
+TRACE
+chmod +x "$TRACE_DIR/bin/unzip"
+: > "$TRACE_DIR/calls"
+
+# Run the prescribed clean-path: 1 `unzip -Z` + 1 `unzip -oq`.
+mkdir e-dest
+PATH="$TRACE_DIR/bin:/usr/bin:/bin" unzip -Z e-clean.zip >/dev/null 2>&1
+PATH="$TRACE_DIR/bin:/usr/bin:/bin" unzip -oq e-clean.zip -d e-dest >/dev/null 2>&1
+
+Z_COUNT=$(grep -c '^Z$' "$TRACE_DIR/calls" || true)
+O_COUNT=$(grep -c '^O$' "$TRACE_DIR/calls" || true)
+T_COUNT=$(grep -c '^T$' "$TRACE_DIR/calls" || true)
+
+if [ "$Z_COUNT" = "1" ] && [ "$O_COUNT" = "1" ] && [ "$T_COUNT" = "0" ]; then
+  pass "(e) clean — exactly 1 pre-flight + 1 extraction (Z=$Z_COUNT O=$O_COUNT T=$T_COUNT)"
+else
+  fail "(e) clean — wrong invocation count Z=$Z_COUNT O=$O_COUNT T=$T_COUNT"
+fi
+
+# --- (f) Filenames with spaces survive name extraction -----------------------
+cd "$WORK"
+mkdir f-stage && cd f-stage
+echo "hello" > "hello world.txt"
+zip ../f-space.zip "hello world.txt" >/dev/null 2>&1
+cd "$WORK"
+NAMES=$(unzip -Z f-space.zip 2>/dev/null | extract_names)
+if [ "$NAMES" = "hello world.txt" ]; then
+  pass "(f) whitespace name — extracted intact: '$NAMES'"
+else
+  fail "(f) whitespace name — corrupted: got '$NAMES' want 'hello world.txt'"
+fi
+
+# --- Summary -----------------------------------------------------------------
+echo
+echo "RESULT: $PASS passed, $FAIL failed"
+exit "$FAIL"

package/payload/platform/plugins/admin/skills/unzip-attachment/references/safety.md

@@ -1,6 +1,20 @@
 # Zip extraction safety reference
 
-This file is the authoritative source for the exact shell commands, attack examples, and refusal messages referenced by [SKILL.md](../SKILL.md). Changes here propagate to every extraction — the skill file inlines none of this so the reference is the single point of truth.
+This file is the authoritative source for the exact shell commands, attack examples, and refusal messages referenced by [SKILL.md](../SKILL.md). Changes here propagate to every extraction — the skill file inlines the pre-flight bash block; this reference explains *why* each gate is shaped the way it is.
+
+## The single-pass pre-flight
+
+One `unzip -Z "$zip"` call produces the zipinfo column listing. Every attack-class gate reads the same output:
+
+```
+Archive:  example.zip
+Zip file size: 317 bytes, number of entries: 2
+-rw-r--r--  3.0 unx        6 tx stor 26-May-10 21:08 foo.txt
+lrwxr-xr-x  3.0 unx       11 bx stor 26-May-10 21:08 link
+2 files, 17 bytes uncompressed, 17 bytes compressed:  0.0%
+```
+
+Columns: `$1=permissions $2=zip-version $3=os $4=size-bytes $5=text/binary+crypto-flag $6=method $7=date $8=time $9+=name`. Each gate keys off one column; no second `unzip` invocation is needed.
 
 ## Attack classes
 
@@ -8,13 +22,20 @@ This file is the authoritative source for the exact shell commands, attack examp
 
 A malicious archive contains an entry whose name starts with `../` (or uses Windows `..\` on some unzip builds). A naive extractor writing relative paths without validation lands the file *outside* the intended destination.
 
-Example listing (`unzip -Z1`):
+Example listing (`unzip -Z`):
 ```
-good/readme.md
-../../etc/cron.d/malicious
+?rw-------  2.0 unx        4 b- stor 26-May-11 06:31 ../../escapee.txt
+?rw-------  2.0 unx        2 b- stor 26-May-11 06:31 good.txt
 ```
 
-Ground-truth guard: after extraction, for every path under `$dest`, compute `realpath --relative-to "$dest" "<entry>"`. If the relative path begins with `../`, the entry escaped. Refusal line: `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>`.
+Pre-scan detection (one awk pass over column 9+):
+```awk
+NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { print "blocked: " $i; exit } }
+```
+
+Ground-truth backstop: after extraction, for every path under `$dest`, compute `realpath --relative-to "$dest" "<entry>"`. If the relative path begins with `../`, the entry escaped. On macOS InfoZIP 6.00 the extractor silently sanitises `../` prefixes (the file lands inside `$dest` with the prefix stripped), so the realpath check is a no-op in that case — but it still catches the attack on `unzip` builds that don't sanitise. Defense in depth: pre-scan refuses the obvious case, realpath catches the version-specific escape.
+
+Refusal line: `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>`.
 
 Refusal message to the operator:
 
@@ -24,9 +45,9 @@ Refusal message to the operator:
 
 A malicious archive contains a symlink entry — for example, a zero-byte file with permission `lrwxrwxrwx` pointing at `/etc/passwd`. If the extractor materialises it, subsequent operations that follow the symlink read or overwrite the target.
 
-Pre-scan detection:
-```sh
-unzip -Z -v "$zip" | awk 'NR>3 && $1 ~ /^l/ { print $NF; found=1 } END { exit !found }'
+Pre-scan detection (same `unzip -Z` output, column 1):
+```awk
+NR>2 && $1 ~ /^l/ { print "blocked: " $9; exit }
 ```
 First field beginning with `l` is the POSIX symlink flag in the permission column.
 
@@ -42,12 +63,11 @@ Refusal line: `[skill:unzip] symlink-blocked attachmentId=<uuid> entry=<path>`.
 
 A 42 KB archive expands to 4.5 GB — the classic `42.zip`. Not filesystem-escape but resource exhaustion: fills the account disk, causes OOM on downstream processing.
 
-Pre-scan gate:
-```sh
-unzip -Zt "$zip"
-# → "N files, X bytes uncompressed, Y bytes compressed: Z%"
+Pre-scan gate (sum column 4 over the same `unzip -Z` output):
+```awk
+NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { if (s > 100*1024*1024) print "oversize: " s }
 ```
-Parse the `X bytes uncompressed` field. If `X > 100 * 1024 * 1024` (the `MAX_ZIP_UNCOMPRESSED_BYTES` export from `attachments.ts`), refuse *before* calling `unzip -oq`.
+Column 4 is the uncompressed size in bytes per entry. If the running sum exceeds `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in `attachments.ts`), refuse *before* calling `unzip -oq`.
 
 Refusal line: `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600`.
 
@@ -55,7 +75,12 @@ Note: a hostile archive can lie in its declared sizes. The post-extraction realp
 
 ### 4. Password-protected archive
 
-Refused without prompting. `unzip -Z -1` exits non-zero for encrypted entries (or the `-v` listing shows `E` in the attribute column).
+Refused without prompting. The signal is **not** the exit code — `unzip -Z` exits 0 on password-protected archives because the central directory itself is unencrypted; only entry payloads are. The signal is column 5: a leading uppercase `T` (encrypted text) or `B` (encrypted binary). Lowercase `t`/`b` = unencrypted.
+
+Pre-scan detection:
+```awk
+NR>2 && $5 ~ /^[TB]/ { print "password"; exit }
+```
 
 Refusal line: `[skill:unzip] unreadable attachmentId=<uuid> reason=password`.
 
@@ -63,19 +88,29 @@ Refusal message:
 
 > This archive is password-protected. Please extract it locally and upload the individual files you want me to look at.
 
+A genuinely corrupt zip (no central directory) makes `unzip -Z` exit non-zero (typically 9). That is the only exit-code-driven branch: non-zero → `[skill:unzip] unreadable attachmentId=<uuid> reason=corrupt`.
+
 ## Canonical commands
 
 | Purpose | Command |
 |---------|---------|
-| Entry list (names only, exits non-zero on password/corrupt) | `unzip -Z -1 "$zip"` |
-| Verbose listing with permission + size columns | `unzip -Z -v "$zip"` |
-| Summary totals parsed for byte-sum gate | `unzip -Zt "$zip"` |
+| Single-pass pre-flight (listing + permissions + sizes + crypto flag) | `unzip -Z "$zip"` |
 | Extract | `unzip -oq "$zip" -d "$dest"` |
 | Post-extraction symlink backstop | `find "$dest" -mindepth 1 -type l` |
-| Per-entry zip-slip check | `realpath --relative-to "$dest" "<entry>"` → must not start with `../` |
+| Per-entry zip-slip backstop | `realpath --relative-to "$dest" "<entry>"` → must not start with `../` |
 
 All of these are from `unzip` (InfoZIP) + `coreutils` — installed on every Pi image by the installer. No additional dependency.
 
+## Why one pass
+
+Each `Bash` tool_use is one agent turn. `effortToMaxTurns("low") = 5` ([platform/ui/app/lib/claude-agent/budget.ts:175](../../../../ui/app/lib/claude-agent/budget.ts#L175)). The previous flow used three separate `unzip -Z` invocations (entry list, verbose-for-symlink, totals) plus the extraction — four bash calls inside the skill alone, before counting the surrounding specialist dispatch and `plugin-read` calls. At `effort=low` the floor was six turns; one upload exhausted the budget and tripped `error_max_turns`. The fix is structural: every signal the four gates need is already in `unzip -Z`'s column output, so the three pre-flight calls collapse to one.
+
+The observability anchor is `preflightPasses=1` on the `[skill:unzip] start` log line. Absence after a clean upload means either the skill did not activate or the flow regressed back to multiple passes — both regressions are caught by `grep '[skill:unzip] start' server.log | grep -v preflightPasses=1`.
+
 ## Why this is a skill, not a tool
 
 Doctrine: the admin agent has `Bash`; the security-critical code path is a sequence of shell commands whose determinism is enforced by the shell primitives themselves, not by LLM reasoning. Wrapping this in an MCP tool would add a translation layer without adding enforcement — a tool wrapper is still LLM-mediated at the decision boundary. The shell script is the deterministic primitive; the skill tells the agent which primitive to invoke, in which order, against which argument.
+
+## Regression suite
+
+[`__tests__/preflight.sh`](../__tests__/preflight.sh) is the executable specification of the four pre-flight gates. Run it after any change to this file or `SKILL.md`. It builds fixtures for each attack class, pipes `unzip -Z` output through the same awk gates inlined in `SKILL.md` step 2, and asserts each gate fires (or stays silent) on the right input. The clean-zip case also traces `unzip` invocations to assert exactly 1 pre-flight + 1 extraction — the structural invariant `preflightPasses=1` is built on.

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -166,7 +166,7 @@ When the user asks what you can do, answer from the specialist domains, admin-ow
 - Never state a future commitment ("I'll flag", "I'll check", "I'll remind") without immediately creating the mechanism to fulfil it — a scheduled event, a task, or a workflow trigger. A commitment without a backing mechanism is a broken promise.
 - Store everything you learn about the business in the graph — not in files.
 - For document ingestion of any kind — PDFs, text, transcripts, web pages, audio, video, single files, archives — delegate to the `specialists:database-operator` specialist. Include the document path, the document subject (account owner, the business, a third party, etc. — ask if not obvious from context), and the scope (admin/shared/public — ask if not obvious). **Not** `specialists:content-producer`. content-producer produces documents from the populated graph; it does not ingest. The two are opposite movements through the graph and must never be conflated.
-- For ad-hoc graph operations — pruning orphan nodes, deduplicating entities, adding edges, normalising labels, tidying schema drift — delegate to the `specialists:database-operator` specialist. Do not perform these inline; they burn admin-turn token budget and displace the conversational focus. **Not** `specialists:personal-assistant` — PA has no graph-write surface; misdelegation fails at the tool-gate after wasting a turn.
+- For any raw cypher against the memory graph — read or write — delegate to the `specialists:database-operator` specialist. Your read surface is the wrapped tools (`memory-search`, `memory-rank`, `conversation-search`, `profile-read`); your write surface is the schema-aware wrappers (`memory-write`, `memory-update`, `memory-find-candidates`, `memory-delete`). Anything that needs a `MATCH ... RETURN`, a property the wrappers do not expose, or a multi-statement transaction is the operator's surface (e.g. property-name reads against `:CloudflareHostname` / `:Task` / `:Person`, edge-shape audits, dedupe merges, label normalisation, prune passes). Do not perform these inline; admin's `# SCHEMA` block lists labels and edges only — it does not carry the property dictionary, so inline cypher routinely targets non-existent properties and the resulting `01N52` warning is not surfaced. **Not** `specialists:personal-assistant` — PA has no graph surface; misdelegation fails at the tool-gate after wasting a turn.
 - For host-website / publish-site / put-online intents — typically a `.zip` attachment with HTML + assets and a request like "host this website" or "put this online" — delegate immediately to the `specialists:content-producer` specialist on turn 1. Do not `ToolSearch` publish-site, do not `plugin-read` the skill inline, do not pre-scan the zip. The specialist owns the `unzip-attachment` → `publish-site` chain and runs the deterministic Bash flow on its own 10-turn budget; running it inline here exhausts the main-runner budget on per-turn discovery (Task 966 evidence: a 2026-05-10 brochure session hit `error_max_turns total_tool_calls=24` before publish-site executed). **Not** `specialists:database-operator` — static-site zips are extracted to disk for publication, never written to the graph.
 
 ## Proactive Commitment Detection

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -1,6 +1,6 @@
 ---
 name: database-operator
-description: "Document and archive ingestion and ad-hoc graph operations — running the universal `document-ingest` skill for any unstructured document (PDF, text, transcript, web page, audio, video) and per-source archive-import skills (LinkedIn Basic Data Export today; CRM-type seed archives as each plugin ships), plus operator-driven graph hygiene (prune orphans, deduplicate entities, add edges, normalise labels). Delegate when the operator uploads any document, drops an archive directory into chat, or asks for any graph operation that is not a routine per-turn write."
+description: "Owner of the memory graph — any raw cypher (read or write) against Neo4j routes here, plus all document and archive ingestion (running the universal `document-ingest` skill for unstructured documents — PDF, text, transcript, web page, audio, video — and per-source archive-import skills — LinkedIn Basic Data Export today; CRM-type seed archives as each plugin ships), plus operator-driven graph hygiene (prune orphans, deduplicate entities, add edges, normalise labels), plus one-off raw reads (property-name lookups, edge-shape audits, multi-statement queries) when admin's wrapped read tools — `memory-search`, `memory-rank`, `conversation-search`, `profile-read` — do not expose the property or relationship being asked about. Delegate when the operator uploads any document, drops an archive directory into chat, asks for any graph operation that is not a routine per-turn wrapped write, or asks a factual question whose answer requires a property or relationship admin's wrapped read tools cannot reach."
 summary: "Ingests every unstructured document and external archive into your graph (LinkedIn today; other CRM sources in future) and handles ad-hoc graph tidy-ups on request. For example, when you upload a CV, a pricing guide, or a contract; when you drop a LinkedIn export folder into chat; or when you ask to prune orphan nodes, merge duplicate people, or add edges between entities."
 model: claude-sonnet-4-6
 tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-write_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__memory-archive-write, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__tasks__task-create, mcp__admin__file-attach, mcp__admin__plugin-read