devflow-kit 3.1.0 → 3.3.0

package/src/assets/scripts/hooks/ensure-root-gitignore

@@ -58,6 +58,22 @@
 # `!.claudeignore` entry means "the user owns that line" — emit the block without it.
 # All matching is whole-line and whitespace-tolerant; never substring.
 #
+# D-GITIGNORE-LINK-INSIDE: a root .gitignore that is a symbolic link is written only
+# when the file it resolves to lies inside the project root and outside any .git
+# folder in the project, the project's own or a nested repository's: no part of its
+# path below the root may be named .git, in any letter case, as git itself refuses
+# such a path. Then that file is read and written directly, never through the link.
+# Otherwise nothing is read or written anywhere, no marker is stamped, the skip is
+# logged once and the caller goes on. Reason: a repository can commit .gitignore as a
+# link to any file on the machine, and the carve-out would be appended to it; a file
+# in a .git is no file of the repository's either, but git's own hooks and config,
+# and a line appended to a hook runs as a command the next time git runs it. The case
+# matters because a case-insensitive file system (macOS) opens .git for .GIT. The TS
+# twin, ensureDevflowGitignore in src/targets/claude-code/post-install.ts, applies the
+# same rule the same way: the link is followed one hop at a time, at most 40 hops, and
+# only its last folder is resolved physically, so a missing file inside the project
+# is created there as before.
+#
 # Usage: source ensure-root-gitignore "$PROJECT_ROOT"
 # Sourced helper: uses `return` (never exit), _ERG_-prefixed locals (never clobbers
 # caller vars).
@@ -68,6 +84,76 @@ _ERG_DEVFLOW_DIR="$1/.devflow"
 _ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v6"
 _ERG_GITIGNORE="$1/.gitignore"
 
+# _erg_resolve_inside <root> <link> — follow the symbolic link <link> one hop at a
+# time, at most 40, and set _ERG_RESOLVED to the file it leads to, its folder
+# resolved physically. Returns 0 when that file lies inside <root> and no part of its
+# path below <root> is named .git in any letter case (D-GITIGNORE-LINK-INSIDE);
+# returns 1, with _ERG_RESOLVED empty, when it does not and when the link cannot be
+# followed: a read that fails, an empty or folder-like target, a chain longer than
+# 40, a folder that does not resolve. A predicate: call it in an `if`, never as a
+# plain statement under `set -e`. Relative targets are joined to the folder the link
+# sits in as spelled, never normalised, so `..` is resolved by the file system as the
+# write itself would resolve it. Each hop forks one readlink; `cd -P` and $PWD are
+# builtins, and the caller's folder is restored before returning.
+_erg_resolve_inside() {
+  local _root="$1" _cur="$2" _target="" _dir="" _base="" _root_real="" _hops=0 _back="$PWD"
+  _ERG_RESOLVED=''
+  # Absolute from the start, so no path is read as an option, searched for along
+  # CDPATH, or taken relative to a folder this function moved into.
+  case "$_root" in /*) ;; *) _root="$_back/$_root" ;; esac
+  case "$_cur" in /*) ;; *) _cur="$_back/$_cur" ;; esac
+  while [ -L "$_cur" ]; do
+    [ "$_hops" -lt 40 ] || return 1
+    # The `x` keeps a target's own trailing newlines from command substitution; the
+    # one newline readlink adds is then removed.
+    _target="$(readlink "$_cur" 2>/dev/null && printf x)"
+    case "$_target" in *x) _target="${_target%x}" ;; *) return 1 ;; esac
+    _target="${_target%$'\n'}"
+    case "$_target" in
+      '') return 1 ;;
+      /*) _cur="$_target" ;;
+      *) _cur="${_cur%/*}/$_target" ;;
+    esac
+    _hops=$((_hops + 1))
+  done
+  _base="${_cur##*/}"
+  _dir="${_cur%/*}"
+  case "$_base" in ''|.|..) return 1 ;; esac
+  [ -n "$_dir" ] || _dir=/
+  if cd -P "$_root" 2>/dev/null; then
+    _root_real="${PWD%/}"
+    if cd -P "$_dir" 2>/dev/null; then _ERG_RESOLVED="${PWD%/}/$_base"; fi
+  fi
+  cd "$_back" 2>/dev/null || true
+  case "$_ERG_RESOLVED" in
+    '') ;;
+    "$_root_real"/?*)
+      # Each part below the root is tested whole, in any letter case: `cd -P` keeps
+      # the spelling the link gave, and a case-insensitive file system opens `.git`
+      # for `.GIT`.
+      case "/${_ERG_RESOLVED#"$_root_real"/}/" in
+        */.[Gg][Ii][Tt]/*) ;;
+        *) return 0 ;;
+      esac
+      ;;
+  esac
+  _ERG_RESOLVED=''
+  return 1
+}
+
+# D-GITIGNORE-LINK-INSIDE (above): checked before the fast path, so a link that leads
+# elsewhere is neither read nor written. A regular .gitignore costs one builtin test.
+if [ -L "$_ERG_GITIGNORE" ]; then
+  if _erg_resolve_inside "$1" "$_ERG_GITIGNORE"; then
+    _ERG_GITIGNORE="$_ERG_RESOLVED"
+  else
+    if declare -F log >/dev/null 2>&1; then
+      log "Skipped: $_ERG_GITIGNORE is a symbolic link that leads outside the project, into a .git, or nowhere; nothing was written through it"
+    fi
+    return 0
+  fi
+fi
+
 # Whole-line, whitespace-tolerant matchers. `*` and `.` are escaped so the ERE
 # matches the literal gitignore patterns.
 _ERG_RE_OPTOUT='^[[:space:]]*/\.devflow/[[:space:]]*$'
@@ -208,18 +294,30 @@ else
     # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
     # comment first, then fall through to the shared append below. Portable (grep
     # filter + mv; no sed -i, which differs on BSD/GNU).
-    # The pipeline's own status is deliberately ignored: grep -v exits 1 when it
+    # The filter's own status is deliberately ignored: grep -v exits 1 when it
     # emits no lines, which is the correct outcome for a .gitignore whose only
-    # content was the legacy entry. The redirect creates _ERG_TMP either way.
+    # content was the legacy entry, so `true` ends the group and the subshell fails
+    # only when the copy cannot be created. The copy is created only where nothing
+    # stands at its name: builtin tests come first, so an entry already there, a
+    # link to a FIFO or a device included, is never opened (noclobber alone would
+    # open one, as no regular file stands there), and noclobber then makes the
+    # create itself exclusive (D-HOOKS-NO-SYMLINK, git-marker). Such an entry is
+    # removed instead; the upgrade then waits for a later run, and the skip is
+    # logged once.
     _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
-    grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null \
-      | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
-      > "$_ERG_TMP" 2>/dev/null
-    if [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
+    if [ ! -e "$_ERG_TMP" ] && [ ! -L "$_ERG_TMP" ] && (set -o noclobber; {
+          grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" \
+            | grep -vF '# Devflow runtime data (local by default; remove to share via git)'
+          true
+        } > "$_ERG_TMP") 2>/dev/null \
+      && [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
       :
     else
-      rm -f "$_ERG_TMP" 2>/dev/null
+      rm -f "$_ERG_TMP" 2>/dev/null || true
       _ERG_MODE=fail
+      if declare -F log >/dev/null 2>&1; then
+        log "Legacy .devflow/ entry not upgraded: its copy could not be written ($_ERG_TMP); a later run retries"
+      fi
     fi
   fi
 fi
@@ -231,7 +329,8 @@ fi
 # unchanged, and when the run ends on a last line with no newline, one is added
 # before <text>. Each read ends in a trailing `x`, so command substitution cannot
 # strip the file's own trailing newlines. The file is rewritten in place with one
-# `>`, as the TS twin's writeFile does, so a symlinked .gitignore keeps its link.
+# `>`, as the TS twin's writeFile does; a .gitignore linked to a file inside the
+# project is rewritten at that file, so the link stays (D-GITIGNORE-LINK-INSIDE).
 # Returns non-zero, having written nothing, when the anchor line cannot be found.
 _erg_insert_in_block() {
   local _anchor="$1" _run="$2" _text="$3" _hit="" _n="" _next="" _line="" _i=0 _head="" _tail=""
@@ -284,9 +383,22 @@ case "$_ERG_MODE" in
     ;;
 esac
 
-# On success, stamp the current-format v6 marker and drop legacy markers.
+# On success, stamp the current-format v6 marker and drop legacy markers. The marker
+# is created only where nothing stands, never `touch`ed: `touch` follows a symbolic
+# link committed at its path (D-HOOKS-NO-SYMLINK, git-marker), and so does
+# noclobber's create when the link leads to a FIFO, where it would wait at every
+# session start and prompt, or to a device. So builtin tests come first: a link
+# there is left as it was and the skip logged once, a marker already there is all
+# the fast path needs, and noclobber makes the create itself exclusive. A `.devflow`
+# that is itself a link is refused by both callers before they reach this file.
 [ "$_ERG_OK" = 1 ] && {
-  touch "$_ERG_MARKER"
+  if [ -L "$_ERG_MARKER" ]; then
+    if declare -F log >/dev/null 2>&1; then
+      log "Marker not stamped: $_ERG_MARKER is a symbolic link"
+    fi
+  elif [ ! -e "$_ERG_MARKER" ]; then
+    (set -o noclobber; : > "$_ERG_MARKER") 2>/dev/null || true
+  fi
   _erg_drop_legacy_markers
 }
 return 0

package/src/assets/scripts/hooks/git-marker

@@ -62,3 +62,74 @@ df_is_project_root() {
   [ -n "$_root_real" ] || return 1
   [ "$_root_real" != "$_home_real" ]
 }
+
+# df_no_symlink_below <root> <path>... — returns 0 when no <path>, and no folder
+# between <root> and it, is a symbolic link. Returns 1 when one is, and for any
+# call it cannot vouch for: no <path>, an empty <root>, a <path> not below <root>,
+# or a <path> with an empty, `.` or `..` part or more than 64 parts below <root>.
+# A predicate: call it in an `if` or an `||` list, never as a plain statement
+# under `set -e`.
+#
+# D-HOOKS-NO-SYMLINK: a hook writes under a project's `.devflow/`, and reads a file
+# there into the session context, a backup, a prompt or an agent directive, only
+# where nothing on the way down from the root is a symbolic link. A repository can
+# commit a link anywhere in its own `.devflow/`, and the hooks' shell commands follow
+# one. `>>` and `touch` write through a linked file and `mkdir -p` creates folders
+# inside a linked folder, so a linked queue or folder would put captured
+# conversation text into whatever file the link names. `head`, `sed`, `read` and
+# `jq` read through one, so a linked working memory, backup or decisions file would
+# put whatever file the link names into the session, the memory refresh's prompt or
+# the backup the next session restores, with no one choosing to read it. Each hook
+# checks every path this rule covers: a refused write is skipped and a refused
+# read is treated as an absent file (df_file_below below), each logged once. A
+# rename's target is one of those paths: `mv` moves a file into the folder a link
+# at its target names, so a link there, to anything, refuses the rename.
+#
+# Only the part of each path below <root> is checked, never the root or a folder
+# above it: the root is where the session runs or where git keeps the ledger,
+# chosen by the user and not by what the repository holds, and a folder above it
+# may legitimately be a link (on macOS /tmp and /var lead into /private). The check
+# runs just before the write or the read, so a process that swaps a link in between
+# is not stopped; such a process already runs as the user.
+#
+# Zero forks: builtin `[ -L ]` tests and parameter expansion only.
+df_no_symlink_below() {
+  local _root="$1" _path="" _rest="" _seg="" _at="" _n=0
+  [ -n "$_root" ] || return 1
+  shift
+  [ "$#" -gt 0 ] || return 1
+  for _path in "$@"; do
+    case "$_path" in
+      "$_root"/?*) _rest="${_path#"$_root"/}" ;;
+      *) return 1 ;;
+    esac
+    _at="$_root"
+    _n=0
+    while [ -n "$_rest" ]; do
+      [ "$_n" -lt 64 ] || return 1
+      _seg="${_rest%%/*}"
+      if [ "$_seg" = "$_rest" ]; then _rest=""; else _rest="${_rest#*/}"; fi
+      case "$_seg" in ''|.|..) return 1 ;; esac
+      _at="$_at/$_seg"
+      if [ -L "$_at" ]; then return 1; fi
+      _n=$((_n + 1))
+    done
+  done
+  return 0
+}
+
+# df_file_below <root> <path> — returns 0 when <path> is a regular file that
+# df_no_symlink_below admits, so a hook may read it. Returns 1 when no regular file
+# stands there, and when a symbolic link sits on its path: the file is then treated
+# as absent (D-HOOKS-NO-SYMLINK, above), and that refusal is logged once through the
+# caller's log(), where it defines one. `[ -f ]` follows a link, so a dangling link
+# or a link to a folder reads as absent with nothing logged: nothing would be read
+# through it. A predicate, like df_no_symlink_below; it forks nothing unless it logs.
+df_file_below() {
+  [ -f "$2" ] || return 1
+  if df_no_symlink_below "$1" "$2"; then return 0; fi
+  if declare -F log >/dev/null 2>&1; then
+    log "Skipped: a symbolic link sits on the path to $2; treated as absent"
+  fi
+  return 1
+}

package/src/assets/scripts/hooks/json-helper.cjs

@@ -11,18 +11,8 @@
 //
 // Operations:
 //   get-field <field> [default]           Read field from stdin JSON
-//   validate                              Exit 0 if stdin is valid JSON, 1 otherwise
-//   compact                               Compact stdin JSON to single line
-//   construct <json-template> [--arg k v] Build JSON object with args
-//   update-field <field> <value> [--json] Set field on stdin JSON (--json parses value)
-//   update-fields <json-patches>          Apply multiple field updates from stdin JSON
+//   get-string-field <field>              Read field from stdin JSON only when it is a string
 //   extract-cwd-field <field>             Extract cwd + arbitrary field, SOH-byte delimited
-//   extract-text-messages                 Extract text content from Claude message format
-//   merge-evidence                        Flatten, dedupe, limit to 10 from stdin JSON
-//   slurp-sort <field> [limit]            Read stdin JSONL, sort by field desc, limit results
-//   slurp-cap <field> [limit]             Read stdin JSONL, sort by field desc, output limit lines
-//   array-length <path>                   Get length of array at dotted path in stdin JSON
-//   array-item <path> <index>             Get item at index from array at path in stdin JSON
 //   session-output <context>              Build SessionStart output envelope
 //   prompt-output <context>               Build UserPromptSubmit output envelope
 //   backup-construct                      Build pre-compact backup JSON from --arg pairs
@@ -165,31 +155,15 @@ function getNestedField(obj, field) {
   return current;
 }
 
-/** The JSON values of a JSONL text's lines; a line that does not parse is skipped. */
-function parseJsonlText(text) {
-  const lines = text.split('\n').filter(Boolean);
-  return lines.map(l => {
-    try { return JSON.parse(l); } catch { return null; }
-  }).filter(Boolean);
-}
-
 function parseArgs(argList) {
   const result = {};
-  const jsonArgs = {};
   for (let i = 0; i < argList.length; i++) {
     if (argList[i] === '--arg' && i + 2 < argList.length) {
       result[argList[i + 1]] = argList[i + 2];
       i += 2;
-    } else if (argList[i] === '--argjson' && i + 2 < argList.length) {
-      try {
-        jsonArgs[argList[i + 1]] = JSON.parse(argList[i + 2]);
-      } catch {
-        jsonArgs[argList[i + 1]] = argList[i + 2];
-      }
-      i += 2;
     }
   }
-  return { ...result, ...jsonArgs };
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,7 +252,8 @@ function heartbeat(root) {
 // The learning ops run from the project root and take no path to a learning file:
 // each builds its paths from the current directory. Every op that writes takes the
 // store's one learning lock through withDecisionsLock (D-ONE-LEARNING-LOCK) and
-// refuses, creating nothing, when .devflow/learning/ is absent (D-NO-STRAY-TREE).
+// refuses, creating nothing, when .devflow/learning/ is absent (D-NO-STRAY-TREE)
+// or when it, or .devflow, is a symbolic link (D-NO-LINKED-TREE).
 // A locked body returns its Result; emit prints it once the lock is released.
 if (require.main === module) {
 try {
@@ -293,54 +268,15 @@ try {
       break;
     }
 
-    case 'validate': {
-      try {
-        const text = readStdin();
-        if (!text) process.exit(1);
-        JSON.parse(text);
-        process.exit(0);
-      } catch {
-        process.exit(1);
-      }
-      break;
-    }
-
-    case 'compact': {
+    case 'get-string-field': {
+      // The typed read: get-field stringifies, so the number 42 and the string
+      // "42" are the same to it. Here a JSON string prints byte-exact (no
+      // trailing newline added, so the caller sees the value's own) and every
+      // other type, an absent field, or a string holding a NUL (no shell
+      // variable can carry one) prints nothing.
       const input = JSON.parse(readStdin());
-      console.log(JSON.stringify(input));
-      break;
-    }
-
-    case 'construct': {
-      // Build JSON from --arg/--argjson pairs
-      const template = parseArgs(args);
-      console.log(JSON.stringify(template));
-      break;
-    }
-
-    case 'update-field': {
-      const input = JSON.parse(readStdin());
-      const field = args[0];
-      const value = args[1];
-      const isJson = args[2] === '--json';
-      input[field] = isJson ? JSON.parse(value) : value;
-      console.log(JSON.stringify(input));
-      break;
-    }
-
-    case 'update-fields': {
-      // Read stdin JSON, apply field updates from args: field1=val1 field2=val2
-      const input = JSON.parse(readStdin());
-      for (const arg of args) {
-        const eqIdx = arg.indexOf('=');
-        if (eqIdx > 0) {
-          const key = arg.slice(0, eqIdx);
-          const val = arg.slice(eqIdx + 1);
-          // Try to parse as JSON, fall back to string
-          try { input[key] = JSON.parse(val); } catch { input[key] = val; }
-        }
-      }
-      console.log(JSON.stringify(input));
+      const val = getNestedField(input, args[0]);
+      if (typeof val === 'string' && !val.includes('\0')) process.stdout.write(val);
       break;
     }
 
@@ -356,75 +292,6 @@ try {
       break;
     }
 
-    case 'extract-text-messages': {
-      const input = JSON.parse(readStdin());
-      const content = input?.message?.content;
-      if (typeof content === 'string') {
-        console.log(content);
-        break;
-      }
-      if (!Array.isArray(content)) {
-        console.log('');
-        break;
-      }
-      const texts = content
-        .filter(c => c.type === 'text')
-        .map(c => c.text);
-      console.log(texts.join('\n'));
-      break;
-    }
-
-    case 'merge-evidence': {
-      const input = JSON.parse(readStdin());
-      // input is [[old_evidence], [new_evidence]] — flatten, dedupe, limit
-      const flat = input.flat();
-      const unique = [...new Set(flat)];
-      console.log(JSON.stringify(unique.slice(0, 10)));
-      break;
-    }
-
-    case 'slurp-sort': {
-      const field = args[0];
-      const limit = parseInt(args[1]) || 30;
-      const parsed = parseJsonlText(readStdin());
-      parsed.sort((a, b) => (b[field] || 0) - (a[field] || 0));
-      console.log(JSON.stringify(parsed.slice(0, limit)));
-      break;
-    }
-
-    case 'slurp-cap': {
-      // Read JSONL, sort by field desc, output top N as JSONL (one per line)
-      const field = args[0];
-      const limit = parseInt(args[1]) || 100;
-      const parsed = parseJsonlText(readStdin());
-      parsed.sort((a, b) => (b[field] || 0) - (a[field] || 0));
-      for (const item of parsed.slice(0, limit)) {
-        console.log(JSON.stringify(item));
-      }
-      break;
-    }
-
-    case 'array-length': {
-      const input = JSON.parse(readStdin());
-      const dotPath = args[0];
-      const arr = getNestedField(input, dotPath);
-      console.log(Array.isArray(arr) ? arr.length : 0);
-      break;
-    }
-
-    case 'array-item': {
-      const input = JSON.parse(readStdin());
-      const dotPath = args[0];
-      const index = parseInt(args[1]);
-      const arr = getNestedField(input, dotPath);
-      if (Array.isArray(arr) && index >= 0 && index < arr.length) {
-        console.log(JSON.stringify(arr[index]));
-      } else {
-        console.log('null');
-      }
-      break;
-    }
-
     case 'session-output': {
       const ctx = args[0];
       console.log(JSON.stringify({

package/src/assets/scripts/hooks/json-parse

@@ -1,10 +1,12 @@
 #!/bin/bash
 
-# JSON parsing helper — tries jq, falls back to node json-helper.js
+# JSON parsing helper — tries jq, falls back to node json-helper.cjs
 # Usage: source "$SCRIPT_DIR/json-parse"
 #
 # After sourcing, check $_JSON_AVAILABLE before using json_* functions.
 # All functions read from stdin unless noted otherwise.
+# Where a jq path discards stderr, its node fallback does too, so input that
+# cannot be parsed fails silently on either backend.
 
 _SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 _JSON_HELPER="$_SCRIPT_DIR/json-helper.cjs"
@@ -28,134 +30,42 @@ json_field() {
   if [ "$_HAS_JQ" = "true" ]; then
     jq -r ".$field // \"$default\"" 2>/dev/null
   else
-    node "$_JSON_HELPER" get-field "$field" "$default"
+    node "$_JSON_HELPER" get-field "$field" "$default" 2>/dev/null
   fi
 }
 
 # Extract a field from a JSON file. Usage: json_field_file "/path/to/file.json" "field" "default"
 # Note: uses if/then/else to preserve boolean false (jq // operator would replace false with default)
 # The node fallback reads the file on stdin: json-helper takes no file path.
+# Both paths are silent on stderr: an unparseable or missing file yields empty
+# output and a failing status, as jq does with its errors discarded. The node
+# path redirects stderr BEFORE stdin, so the shell's own error for a `< "$file"`
+# that cannot open is discarded too.
 json_field_file() {
   local file="$1" field="$2" default="${3:-}"
   if [ "$_HAS_JQ" = "true" ]; then
     jq -r "if (.$field | type) == \"null\" then \"$default\" else (.$field | tostring) end" "$file" 2>/dev/null
   else
-    node "$_JSON_HELPER" get-field "$field" "$default" < "$file"
+    node "$_JSON_HELPER" get-field "$field" "$default" 2>/dev/null < "$file"
   fi
 }
 
-# --- Validation ---
-
-# Validate stdin as JSON (exit code 0/1). Usage: echo '{}' | json_valid
-json_valid() {
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -e . >/dev/null 2>&1
-  else
-    node "$_JSON_HELPER" validate
-  fi
-}
-
-# --- Compact ---
-
-# Compact stdin JSON to single line. Usage: echo '{ "k": "v" }' | json_compact
-json_compact() {
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -c '.' 2>/dev/null
-  else
-    node "$_JSON_HELPER" compact
-  fi
-}
-
-# --- Construction ---
-
-# Build a JSON object from --arg/--argjson pairs.
-# Usage: json_construct --arg key1 val1 --arg key2 val2
-json_construct() {
-  if [ "$_HAS_JQ" = "true" ]; then
-    # Build jq expression from args
-    local jq_args=()
-    local fields=""
-    local i=0
-    while [ $i -lt $# ]; do
-      local flag="${!((i+1))}"
-      if [ "$flag" = "--arg" ]; then
-        local name="${!((i+2))}"
-        local val="${!((i+3))}"
-        jq_args+=(--arg "$name" "$val")
-        if [ -n "$fields" ]; then fields="$fields, "; fi
-        fields="${fields}${name}: \$${name}"
-        i=$((i + 3))
-      elif [ "$flag" = "--argjson" ]; then
-        local name="${!((i+2))}"
-        local val="${!((i+3))}"
-        jq_args+=(--argjson "$name" "$val")
-        if [ -n "$fields" ]; then fields="$fields, "; fi
-        fields="${fields}${name}: \$${name}"
-        i=$((i + 3))
-      else
-        i=$((i + 1))
-      fi
-    done
-    jq -n -c "${jq_args[@]}" "{$fields}" 2>/dev/null
-  else
-    node "$_JSON_HELPER" construct "$@"
-  fi
-}
-
-# --- Field updates ---
-
-# Update a field on stdin JSON. Usage: echo '{"k":"v"}' | json_update_field "k" "new_v"
-json_update_field() {
-  local field="$1" value="$2"
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -c --arg v "$value" ".$field = \$v" 2>/dev/null
-  else
-    node "$_JSON_HELPER" update-field "$field" "$value"
-  fi
-}
-
-# Update a field with a JSON value. Usage: echo '{}' | json_update_field_json "k" '42'
-json_update_field_json() {
-  local field="$1" value="$2"
+# The typed read of a field from a JSON file. Usage: json_string_field_file "/path/to/file.json" "field"
+# json_field_file stringifies, so the number 42 and the string "42" read the same;
+# this prints the field only when it is a JSON string, and nothing for any other
+# type (a number, boolean, object, array or null), an absent field, or a string
+# holding a NUL, which no shell variable can carry. The string is printed
+# byte-exact with no newline added, so a caller that must see the value's own
+# trailing newline appends a sentinel before the command substitution strips it:
+#   v=$(json_string_field_file "$file" "k"; printf x); v=${v%x}
+# Silent on stderr and failing on an unparseable or missing file, as json_field_file
+# is, and read the same way on both backends (the node path reads the file on stdin).
+json_string_field_file() {
+  local file="$1" field="$2"
   if [ "$_HAS_JQ" = "true" ]; then
-    jq -c --argjson v "$value" ".$field = \$v" 2>/dev/null
+    jq -j ".$field | select(type == \"string\" and all(explode[]; . != 0))" "$file" 2>/dev/null
   else
-    node "$_JSON_HELPER" update-field "$field" "$value" --json
-  fi
-}
-
-# --- Slurp operations ---
-
-# Slurp JSONL file, sort by field desc, output as JSONL (one line per entry).
-# Usage: json_slurp_cap "file.jsonl" "confidence" 100
-json_slurp_cap() {
-  local file="$1" field="$2" limit="${3:-100}"
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -c '.' "$file" | jq -s "sort_by(.$field) | reverse | .[0:$limit][]" 2>/dev/null
-  else
-    node "$_JSON_HELPER" slurp-cap "$field" "$limit" < "$file"
-  fi
-}
-
-# --- Array operations ---
-
-# Get length of array at path. Usage: echo '{"obs":[1,2]}' | json_array_length "observations"
-json_array_length() {
-  local path="$1"
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq ".$path | length" 2>/dev/null
-  else
-    node "$_JSON_HELPER" array-length "$path"
-  fi
-}
-
-# Get item at index from array. Usage: echo '{"obs":[{},{}]}' | json_array_item "observations" 0
-json_array_item() {
-  local path="$1" index="$2"
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -c ".${path}[$index]" 2>/dev/null
-  else
-    node "$_JSON_HELPER" array-item "$path" "$index"
+    node "$_JSON_HELPER" get-string-field "$field" 2>/dev/null < "$file"
   fi
 }
 
@@ -176,7 +86,7 @@ json_extract_cwd_field() {
   if [ "$_HAS_JQ" = "true" ]; then
     jq -r --arg f "$field" '(.cwd // "") + "\u0001" + (.[$f] // "")' 2>/dev/null
   else
-    node "$_JSON_HELPER" extract-cwd-field "$field"
+    node "$_JSON_HELPER" extract-cwd-field "$field" 2>/dev/null
   fi
 }
 
@@ -186,21 +96,6 @@ json_extract_cwd_prompt() {
   json_extract_cwd_field "prompt"
 }
 
-# --- Transcript extraction ---
-
-# Extract text messages from Claude message JSON. Usage: printf '%s\n' '{"message":...}' | json_extract_messages
-json_extract_messages() {
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -r 'if .message.content then
-      if (.message.content | type) == "string" then .message.content
-      else [.message.content[] | select(.type == "text") | .text] | join("\n")
-      end
-    else "" end' 2>/dev/null
-  else
-    node "$_JSON_HELPER" extract-text-messages
-  fi
-}
-
 # --- Hook output envelopes ---
 
 # Build SessionStart output. Usage: json_session_output "$CONTEXT"