devflow-kit 3.6.0 → 3.7.0

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

@@ -12,6 +12,7 @@
 // Operations:
 //   get-field <field> [default]           Read field from stdin JSON
 //   get-string-field <field>              Read field from stdin JSON only when it is a string
+//   array-length <field>                  Count of an array field in stdin JSON; `unknown` for any other type
 //   extract-cwd-field <field>             Extract cwd + arbitrary field, SOH-byte delimited
 //   session-output <context> [message]    Build SessionStart output envelope (+ systemMessage)
 //   prompt-output <context>               Build UserPromptSubmit output envelope
@@ -280,6 +281,16 @@ try {
       break;
     }
 
+    case 'array-length': {
+      // The count of an array field: digits for an array, the word `unknown` for an
+      // absent field or any other type, so a caller can tell none from not reported.
+      // jq's `length` on an array agrees (json-parse json_array_length_file).
+      const input = JSON.parse(readStdin());
+      const val = getNestedField(input, args[0]);
+      console.log(Array.isArray(val) ? String(val.length) : 'unknown');
+      break;
+    }
+
     case 'extract-cwd-field': {
       // Extract cwd and an arbitrary top-level field from hook JSON in one pass.
       // Outputs: cwd + ASCII SOH (0x01) + field value (no trailing newline).

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

@@ -69,6 +69,21 @@ json_string_field_file() {
   fi
 }
 
+# The element count of an array field in a JSON file. Usage: json_array_length_file "/path/to/file.json" "field"
+# Prints the count as digits when the field is an array, and the word `unknown` for an
+# absent field or any other type (a number, string, object, boolean or null), so a
+# caller can tell "none" from "not reported". Prints nothing, and fails, when the file
+# cannot be read or parsed. Silent on stderr and read the same way on both backends
+# (the node path reads the file on stdin, with its stderr redirected first).
+json_array_length_file() {
+  local file="$1" field="$2"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r "(try .$field catch null) | if type == \"array\" then length else \"unknown\" end" "$file" 2>/dev/null
+  else
+    node "$_JSON_HELPER" array-length "$field" 2>/dev/null < "$file"
+  fi
+}
+
 # --- Multi-field batched extraction ---
 
 # Extract cwd and an arbitrary top-level field from stdin JSON in a single
@@ -103,9 +118,9 @@ json_extract_cwd_prompt() {
 # D-SYSTEMMESSAGE-ENVELOPE: the optional second argument is a message shown to the
 # user, carried in the top-level `systemMessage` key beside (never inside)
 # `hookSpecificOutput`; it does not enter the model's context. With ONE argument the
-# envelope is exactly what every existing caller has always received, byte for byte
-# (ensure-proxy, session-start-orchestrator, session-start-memory and Sections 1-5 of
-# session-start-context pass one). With two:
+# envelope holds the context alone, byte for byte (ensure-proxy and
+# session-start-orchestrator pass one; session-start-context and session-start-memory
+# pass two). With two:
 #   - a message and a context  -> both keys, hookSpecificOutput first;
 #   - a message and no context -> `systemMessage` alone, with NO hookSpecificOutput key;
 #   - an empty message         -> the one-argument envelope for that context.

package/src/assets/scripts/hooks/memory-permission

@@ -0,0 +1,358 @@
+#!/bin/bash
+
+# memory-permission — the memory worker's write permission, as one sourced helper.
+#
+# background-memory-update starts `claude -p` in a permission mode that denies every
+# call no rule allows, with an allow rule for its staged file (WORKING-MEMORY.md.new),
+# the only path the worker's write may reach, and a deny rule for every path under it.
+# Allow rules in the user's own settings also apply to the run.
+# This helper holds what the worker and session-start-memory share, so one bash 3.2 test
+# run covers it (tests/shell-hooks-helpers.test.ts):
+#   path_occupied           whether a file, a folder or a link, even a dangling one, stands on a path
+#   staged_path_safe        whether a staged path can sit in those rules
+#   memory_settings_json    the settings JSON that carries the rules
+#   memory_staged_remove    the guarded removal of a folder or a link at the staged path
+#   memory_result_summary   the fixed log line for a captured JSON result
+#   memory_notice_*         the one-time notice: the worker writes it, a session start reads it
+#   memory_denied_seen      the count of denied runs that raises the `denied` notice
+#
+# Source it after resolve-project-root (it needs df_no_symlink_below and df_file_below)
+# and, for memory_result_summary, after json-parse. log() is used when the caller has one.
+#
+# Errexit safety: both hooks run under `set -e`, and a helper's last non-zero status
+# aborts the caller. So each helper ends in an explicit `return 0` or a `return` with the
+# status it means, link checks are predicates inside `if`, and a create that noclobber may
+# refuse ends in `|| true`. Callers call a predicate inside an `if` or an `||` list.
+#
+# Character sets are spelled out in the patterns below: a range such as a-z collates by
+# locale on bash 3.2.
+
+# The reasons a notice can carry, and the file each one uses beside the memory files:
+#   path    the project path cannot carry the rule, or the staged path is unusable
+#   denied  Claude Code refused the worker's write in two runs with no successful update between them
+MEMORY_NOTICE_REASONS="path denied"
+
+# path_occupied <path> — returns 0 when a file, a folder or a link stands on <path>, and 1
+# when nothing does. A link counts whatever it names, a dangling link included: the name is
+# taken, and a create or a move onto it is not safe. Call it inside an `if` or an `||` list.
+path_occupied() {
+  if [ -e "${1:-}" ] || [ -L "${1:-}" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# staged_path_safe <path> — returns 0 when <path> can sit in the Edit rules as it is.
+# Sets STAGED_PATH_REFUSAL to "" when it can, `chars` when the path holds a character or
+# a segment the rules cannot carry, and `protected` when a .git folder lies above it (the
+# worker skips such a project and logs the reason). A .claude folder above it is fine: a
+# checkout in .claude/worktrees gets its working memory updated. The rule text carries no
+# quoting, so a character that has a meaning in a rule path is refused rather than quoted:
+# * ? [ ] \ " { } and every control character, including newline, tab and DEL. A path that
+# is not absolute, starts with //, or holds an empty, . or .. segment is refused too. ( and )
+# are carried as they are. The path reaches a JSON string by plain concatenation, which is
+# safe after this check: $, backtick and % are inert there, and " \ and controls cannot occur.
+staged_path_safe() {
+  local _p="${1:-}"
+  STAGED_PATH_REFUSAL=""
+  case "$_p" in
+    /*) ;;
+    *) STAGED_PATH_REFUSAL="chars"; return 1 ;;
+  esac
+  case "$_p" in
+    //*|*//*|*/./*|*/../*|*/.|*/..) STAGED_PATH_REFUSAL="chars"; return 1 ;;
+  esac
+  case "$_p" in
+    *[[:cntrl:]]*) STAGED_PATH_REFUSAL="chars"; return 1 ;;
+  esac
+  case "$_p" in
+    *'*'*|*'?'*|*'['*|*']'*|*'\'*|*'"'*|*'{'*|*'}'*) STAGED_PATH_REFUSAL="chars"; return 1 ;;
+  esac
+  case "$_p" in
+    */.git/*) STAGED_PATH_REFUSAL="protected"; return 1 ;;
+  esac
+  return 0
+}
+
+# memory_settings_json <staged path> — prints the settings JSON for `claude --settings`:
+# two rules and no hooks (// makes a rule path absolute):
+#   allow  Edit(//<staged>)     the staged file
+#   deny   Edit(//<staged>/*)   every path under the staged path
+# Under dontAsk, any call no rule allows is refused, so the worker's write is limited to
+# its staged file and to what allow rules in the user's own settings cover.
+# Measured on Claude Code 2.1.269, 2.1.280, 2.1.286 and 2.1.299, both argv forms,
+# against a local stand-in for the Messages API (2026-10-15): with these two rules
+# the Write of the staged file succeeds, and a Write to <staged>/x, <staged>/a/b,
+# <staged>/a/b/c/d/e, <staged>/.hidden or <staged>/../<name> is refused. The deny is
+# `/*` and not `/**`: `/**` was measured to refuse the staged file too (2.1.269 and
+# 2.1.299, 0 of 3 writes), and then no memory is written. A path with two pairs of ( ) in it
+# (`obs ( )/proj (copy)`) carries both rules as they are: on 2.1.269 with the legacy argv
+# and on 2.1.299 with the lean argv, the Write of the staged file succeeded and a Write to
+# <staged>/x, <staged>/a/b, <staged>/.hidden, <staged>/../<name> and to a file in the
+# project root was refused. Prints nothing and returns 1 for a path staged_path_safe
+# refuses, so a rule is never built for an unchecked path.
+memory_settings_json() {
+  local _p="${1:-}"
+  staged_path_safe "$_p" || return 1
+  printf '%s' '{"permissions":{"allow":["Edit(/'"$_p"')"],"deny":["Edit(/'"$_p"'/*)"]},"disableAllHooks":true}'
+  return 0
+}
+
+# STAGED_REMOVE_MAX_LISTING — the most lines `ls -RA` may print for a folder at the staged
+# path. A folder with a longer listing is not deleted.
+STAGED_REMOVE_MAX_LISTING=256
+
+# memory_staged_remove <memory dir> <root> <staged path> — makes the staged path empty
+# when a folder or a link stands on it, with one delete of exactly that path. <root> is
+# the project root as it resolves on disk. It deletes only when it can prove all of these,
+# and otherwise deletes nothing, returns 1 and sets STAGED_REMOVE_REFUSAL to the keyword
+# of the first fact it could not prove:
+#   args    <memory dir>, <root> and <staged path> are all set, and both paths are absolute
+#   path    <staged path> is exactly <memory dir>/WORKING-MEMORY.md.new
+#   parent  <memory dir> is <root>/.devflow/memory, as a string and then on disk
+#   link    no link sits on the way down from <root> to <memory dir>
+#   size    a folder lists at most STAGED_REMOVE_MAX_LISTING lines of `ls -RA`
+#   rm      the delete took effect: nothing stands on the staged path afterwards
+# A link is removed as the link (`rm -f`, never `-r`), so what it names is never touched;
+# a folder is removed with `rm -rf`, which unlinks a link inside it and never follows one.
+# The path is a single quoted word, so no pattern expands. Sets STAGED_REMOVED to `link`,
+# `dir`, or `none` (nothing removed). A regular file, or nothing, is left as it is and
+# returns 0: the caller removes a stale staged file itself. Returns 0 when no folder and
+# no link stands on the path afterwards. The checks and the delete are separate steps, so
+# a process that swaps something in between is not stopped; such a process already runs as
+# the user.
+memory_staged_remove() {
+  local _dir="${1:-}" _root="${2:-}" _staged="${3:-}" _kind="" _phys="" _n=0
+  STAGED_REMOVED="none"
+  STAGED_REMOVE_REFUSAL=""
+  case "$_dir" in /?*) ;; *) STAGED_REMOVE_REFUSAL="args"; return 1 ;; esac
+  case "$_root" in /?*) ;; *) STAGED_REMOVE_REFUSAL="args"; return 1 ;; esac
+  case "$_staged" in /?*) ;; *) STAGED_REMOVE_REFUSAL="args"; return 1 ;; esac
+  if [ -L "$_staged" ]; then
+    _kind="link"
+  elif [ -d "$_staged" ]; then
+    _kind="dir"
+  else
+    return 0
+  fi
+  if [ "$_staged" != "$_dir/WORKING-MEMORY.md.new" ]; then
+    STAGED_REMOVE_REFUSAL="path"; return 1
+  fi
+  if [ "$_dir" != "$_root/.devflow/memory" ]; then
+    STAGED_REMOVE_REFUSAL="parent"; return 1
+  fi
+  if ! df_no_symlink_below "$_root" "$_dir"; then
+    STAGED_REMOVE_REFUSAL="link"; return 1
+  fi
+  _phys=$(cd -P -- "$_dir" 2>/dev/null && pwd -P) || _phys=""
+  if [ "$_phys" != "$_root/.devflow/memory" ]; then
+    STAGED_REMOVE_REFUSAL="parent"; return 1
+  fi
+  if [ "$_kind" = "dir" ]; then
+    _n=$(ls -RA -- "$_staged" 2>/dev/null | head -n $((STAGED_REMOVE_MAX_LISTING + 1)) | wc -l) || _n=0
+    _n=$((_n + 0))
+    if [ "$_n" -gt "$STAGED_REMOVE_MAX_LISTING" ]; then
+      STAGED_REMOVE_REFUSAL="size"; return 1
+    fi
+    rm -rf -- "$_staged" 2>/dev/null || true
+  else
+    rm -f -- "$_staged" 2>/dev/null || true
+  fi
+  if path_occupied "$_staged"; then
+    STAGED_REMOVE_REFUSAL="rm"; return 1
+  fi
+  STAGED_REMOVED="$_kind"
+  return 0
+}
+
+# The most characters a result field may carry into the log line. A longer value reads
+# `unknown` (a status code is left out).
+MEMORY_RESULT_DENIALS_MAX_DIGITS=6
+MEMORY_RESULT_TURNS_MAX_DIGITS=6
+MEMORY_RESULT_STATUS_MAX_DIGITS=3
+MEMORY_RESULT_SUBTYPE_MAX_CHARS=40
+
+# _memory_field_within <digits|letters> <value> <max> — sets _MEMORY_FIELD to <value> when
+# it is one or more characters of the named set and at most <max> of them, and to `unknown`
+# otherwise. `digits` is 0-9; `letters` is a-z and _. Both are spelled out, since a range
+# collates by locale on bash 3.2. A builtin only, so it forks nothing. Always returns 0.
+_memory_field_within() {
+  local _set="${1:-}" _value="${2:-}" _max="${3:-0}"
+  _MEMORY_FIELD="unknown"
+  case "$_set" in
+    digits)
+      case "$_value" in ''|*[!0123456789]*) return 0 ;; esac
+      ;;
+    letters)
+      case "$_value" in ''|*[!abcdefghijklmnopqrstuvwxyz_]*) return 0 ;; esac
+      ;;
+    *) return 0 ;;
+  esac
+  if [ "${#_value}" -le "$_max" ]; then _MEMORY_FIELD="$_value"; fi
+  return 0
+}
+
+# memory_result_summary <file> — reduces a `--output-format json` result file to a fixed
+# line, and reads nothing else of it: the tool input and the result text, which can hold
+# the memory body, are never read. Sets, in the caller's scope:
+#   MEMORY_RESULT_LINE     Result: <subtype>, is_error=<true|false>, <n> turn(s),
+#                          <d> permission denial(s)[, api_status=<digits>]
+#                          or Result: not reported (empty|unparseable|no parser)
+#   MEMORY_RESULT_DENIALS  the denial count as digits, or `unknown` when the result does
+#                          not report one (an absent or non-array field is never 0)
+# Every field is checked against its own shape, so text from the file cannot enter the
+# line: a field that fails its check reads `unknown`. Always returns 0.
+memory_result_summary() {
+  local _f="${1:-}" _sub="" _err="" _turns="" _den="" _status="" _api=""
+  MEMORY_RESULT_LINE=""
+  MEMORY_RESULT_DENIALS="unknown"
+  if [ "${_JSON_AVAILABLE:-false}" != "true" ]; then
+    MEMORY_RESULT_LINE="Result: not reported (no parser)"
+    return 0
+  fi
+  if [ -z "$_f" ] || [ ! -s "$_f" ]; then
+    MEMORY_RESULT_LINE="Result: not reported (empty)"
+    return 0
+  fi
+  _den=$(json_array_length_file "$_f" "permission_denials") || _den=""
+  if [ -z "$_den" ]; then
+    MEMORY_RESULT_LINE="Result: not reported (unparseable)"
+    return 0
+  fi
+  _memory_field_within digits "$_den" "$MEMORY_RESULT_DENIALS_MAX_DIGITS"; _den="$_MEMORY_FIELD"
+  _sub=$(json_string_field_file "$_f" "subtype") || _sub=""
+  _memory_field_within letters "$_sub" "$MEMORY_RESULT_SUBTYPE_MAX_CHARS"; _sub="$_MEMORY_FIELD"
+  _err=$(json_field_file "$_f" "is_error" "") || _err=""
+  case "$_err" in
+    true|false) ;;
+    *) _err="unknown" ;;
+  esac
+  _turns=$(json_field_file "$_f" "num_turns" "") || _turns=""
+  _memory_field_within digits "$_turns" "$MEMORY_RESULT_TURNS_MAX_DIGITS"; _turns="$_MEMORY_FIELD"
+  _status=$(json_field_file "$_f" "api_error_status" "") || _status=""
+  _memory_field_within digits "$_status" "$MEMORY_RESULT_STATUS_MAX_DIGITS"
+  if [ "$_MEMORY_FIELD" != "unknown" ]; then _api=", api_status=${_MEMORY_FIELD}"; fi
+  MEMORY_RESULT_LINE="Result: ${_sub}, is_error=${_err}, ${_turns} turn(s), ${_den} permission denial(s)${_api}"
+  MEMORY_RESULT_DENIALS="$_den"
+  return 0
+}
+
+# memory_notice_write <memory dir> <root> <reason> — leaves a notice for the next session
+# start, once per reason: only where neither the notice nor its `.shown` marker stands,
+# and where no link sits on the way down from <root>. The builtin tests come first, since
+# noclobber alone opens a link to a FIFO or a device; noclobber then makes the create
+# itself exclusive. Content: the reason. Best effort: a refusal leaves nothing.
+memory_notice_write() {
+  local _dir="${1:-}" _root="${2:-}" _reason="${3:-}" _file
+  case " $MEMORY_NOTICE_REASONS " in
+    *" $_reason "*) ;;
+    *) return 0 ;;
+  esac
+  [ -d "$_dir" ] || return 0
+  _file="$_dir/.worker-notice-$_reason"
+  if ! path_occupied "$_file" && ! path_occupied "$_file.shown" \
+     && df_no_symlink_below "$_root" "$_file" "$_file.shown"; then
+    ( umask 077; set -C; printf '%s\n' "$_reason" > "$_file" ) 2>/dev/null || true
+  fi
+  return 0
+}
+
+# memory_notice_clear <memory dir> <root> <reason> — removes the notice, its `.shown`
+# marker and, for `denied`, the one-denied-run marker, once the cause is gone. The
+# files are removed only where no link sits on the way down from <root>.
+memory_notice_clear() {
+  local _dir="${1:-}" _root="${2:-}" _reason="${3:-}" _file _mark
+  case " $MEMORY_NOTICE_REASONS " in
+    *" $_reason "*) ;;
+    *) return 0 ;;
+  esac
+  _file="$_dir/.worker-notice-$_reason"
+  _mark="$_dir/.worker-denied-once"
+  if path_occupied "$_file" || path_occupied "$_file.shown"; then
+    if df_no_symlink_below "$_root" "$_file" "$_file.shown"; then
+      rm -f "$_file" "$_file.shown" 2>/dev/null || true
+    fi
+  fi
+  if [ "$_reason" = "denied" ] && path_occupied "$_mark"; then
+    if df_no_symlink_below "$_root" "$_mark"; then
+      rm -f "$_mark" 2>/dev/null || true
+    fi
+  fi
+  return 0
+}
+
+# memory_denied_seen <memory dir> <root> — records one run that Claude Code refused the
+# worker's write in. The first leaves a marker; a second, with the marker still there,
+# raises the `denied` notice. A run that swapped the memory in clears both
+# (memory_notice_clear denied), so only two denied runs with no successful update between
+# them count.
+memory_denied_seen() {
+  local _dir="${1:-}" _root="${2:-}" _mark
+  [ -d "$_dir" ] || return 0
+  _mark="$_dir/.worker-denied-once"
+  if path_occupied "$_mark"; then
+    memory_notice_write "$_dir" "$_root" "denied"
+  elif df_no_symlink_below "$_root" "$_mark"; then
+    ( umask 077; set -C; : > "$_mark" ) 2>/dev/null || true
+  fi
+  return 0
+}
+
+# memory_notice_text <reason> <log file> — sets MEMORY_NOTICE_TEXT to the message for a
+# reason, naming <log file>, and to "" for a reason it has no message for. Always returns 0.
+memory_notice_text() {
+  local _reason="${1:-}" _logfile="${2:-}"
+  local _where="The worker log is .background-memory-update.log under ~/.devflow/logs/, in the folder for the session that ran it. For this session: ${_logfile}"
+  MEMORY_NOTICE_TEXT=""
+  case "$_reason" in
+    path)
+      MEMORY_NOTICE_TEXT="Devflow: working memory is not updating because the worker cannot write its staged file at this project path. ${_where}"
+      ;;
+    denied)
+      MEMORY_NOTICE_TEXT="Devflow: working memory is not updating because Claude Code refused the worker's write in two runs with no successful update between them. ${_where}"
+      ;;
+  esac
+  return 0
+}
+
+# memory_notice_read <memory dir> <root> <log file> — builds the message for each pending
+# notice and moves each to its `.shown` marker, so a reason is shown once. Sets
+# MEMORY_NOTICE_MESSAGE (empty when nothing is pending), joined by a space when more
+# than one reason is pending. A notice is read only where no link sits on its path; one
+# whose content does not fit its reason is moved to `.shown` unshown and logged.
+# <log file> is named in the messages (memory_notice_text). Always returns 0.
+memory_notice_read() {
+  local _dir="${1:-}" _root="${2:-}" _logfile="${3:-}"
+  local _reason _file _line _tag _extra _text
+  MEMORY_NOTICE_MESSAGE=""
+  for _reason in $MEMORY_NOTICE_REASONS; do
+    _file="$_dir/.worker-notice-$_reason"
+    df_file_below "$_root" "$_file" || continue
+    _line=""; _tag=""; _extra=""; _text=""
+    # stderr is redirected before stdin, so a notice that a concurrent session start moved
+    # away since the check above fails the open in silence.
+    IFS= read -r -n 200 _line 2>/dev/null < "$_file" || true
+    read -r _tag _extra <<< "$_line" || true
+    if [ "$_tag" = "$_reason" ] && [ -z "$_extra" ]; then
+      memory_notice_text "$_reason" "$_logfile"
+      _text="$MEMORY_NOTICE_TEXT"
+    fi
+    if [ -n "$_text" ]; then
+      if [ -n "$MEMORY_NOTICE_MESSAGE" ]; then
+        MEMORY_NOTICE_MESSAGE="${MEMORY_NOTICE_MESSAGE} ${_text}"
+      else
+        MEMORY_NOTICE_MESSAGE="$_text"
+      fi
+    elif declare -F log >/dev/null 2>&1; then
+      log "Worker notice for reason ${_reason} ignored: its content does not fit the reason"
+    fi
+    if df_no_symlink_below "$_root" "$_file" "$_file.shown"; then
+      if ! path_occupied "$_file.shown"; then
+        mv "$_file" "$_file.shown" 2>/dev/null || true
+      else
+        rm -f "$_file" 2>/dev/null || true
+      fi
+    fi
+  done
+  return 0
+}

package/src/assets/scripts/hooks/session-start-context

@@ -848,7 +848,7 @@ fi
 #   (a) an if-clause, so it applies only when a devflow command was running, with an
 #       explicit ignore clause;
 #   (b) where the command file lives, by rule: commands/devflow/ under the Claude
-#       config directory ($CLAUDE_CONFIG_DIR, else ~/.claude);
+#       config directory ($CLAUDE_CONFIG_DIR when absolute, else ~/.claude);
 #   (c) the read mechanics: list the headings, then read from the phase in progress,
 #       never the whole file;
 #   (d) that the command's input (COMMAND_INPUT in the commands that bind it, an
@@ -862,7 +862,7 @@ fi
 case "$SESSION_SOURCE" in
   compact)
     dbg "compaction resume directive emitted"
-    COMPACT_SECTION='If a devflow command was running: re-read {$CLAUDE_CONFIG_DIR or ~/.claude}/commands/devflow/<name>.md, list headings, read from current phase, take input (COMMAND_INPUT/ARGUMENTS) from the summary, resume after the last finished phase. Else ignore.'
+    COMPACT_SECTION='If a devflow command was running: read commands/devflow/<name>.md in $CLAUDE_CONFIG_DIR if absolute, else ~/.claude, list headings, read from current phase, input (COMMAND_INPUT/ARGUMENTS) from summary, resume after last finished phase. Else ignore.'
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
 

package/src/assets/scripts/hooks/session-start-memory

@@ -39,6 +39,8 @@ dbg "CWD=$CWD"
 # Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
 # hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
 source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
+# The one-time notice the memory worker leaves (needs df_file_below from resolve-project-root).
+source "$SCRIPT_DIR/memory-permission" || { echo "session-start-memory: failed to source memory-permission" >&2; exit 1; }
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 
@@ -346,17 +348,36 @@ ${COMPACT_NOTE}"
   fi
 fi
 
+# --- One-time worker notice ---
+# When the memory worker cannot refresh memory for a reason only the user can fix (a
+# project path its permission rule cannot carry, the worker's write refused in two runs
+# with no successful update between them), it leaves a notice file. The message is shown
+# to the user once per reason, whether or not a working memory exists, and the file moves
+# to its `.shown` marker so the next start stays quiet (memory-permission). The worker log
+# is `.background-memory-update.log` under ~/.devflow/logs/, in the folder for the session
+# that ran the worker; the message names this session's folder for it.
+# D-SYSTEMMESSAGE-ENVELOPE: it travels as `systemMessage`, beside the context and never in it.
+memory_notice_read "$MEMORY_DIR" "$PROJECT_ROOT" "$LOG_DIR/.background-memory-update.log"
+SYSTEM_MESSAGE="$MEMORY_NOTICE_MESSAGE"
+if [ -n "$SYSTEM_MESSAGE" ]; then
+  dbg "Worker notice shown"
+  log "Worker notice shown to the user"
+fi
+
 # --- Output ---
 
-# Only output if we have something to inject
-if [ -z "$CONTEXT" ]; then
+# Only output if we have something to inject or to tell the user
+if [ -z "$CONTEXT" ] && [ -z "$SYSTEM_MESSAGE" ]; then
   dbg "EXIT: no context to inject"
   exit 0
 fi
 
 dbg "OUTPUT_LENGTH=${#CONTEXT}"
-log "Injecting memory context (${#CONTEXT} chars)"
+if [ -n "$CONTEXT" ]; then
+  log "Injecting memory context (${#CONTEXT} chars)"
+fi
 dbg "=== HOOK COMPLETE ==="
 
-# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
-json_session_output "$CONTEXT"
+# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible);
+# a notice adds a systemMessage the user sees.
+json_session_output "$CONTEXT" "$SYSTEM_MESSAGE"

package/src/assets/scripts/lib/project-config.cjs

@@ -21,7 +21,9 @@
 // bad value never takes its neighbours down with it (AC-26). What a malformed
 // value MEANS is the consumer's decision, made once in each caller's fold:
 // evidence ⇒ required, compliance ⇒ generic, tracker ⇒ TRACKER_WARN=invalid,
-// reviewPublication ⇒ off, a feature switch ⇒ not narrowed.
+// reviewPublication ⇒ off, a feature switch ⇒ not narrowed. The personal file
+// alone also carries `gateLevel` ("full|standard|lean"); it is a level, not a
+// switch, so it may raise or lower what the machine records.
 //
 // Whole-file rule: that per-key classification applies only INSIDE a file that
 // reads as a JSON object. A file that exists but does not — empty, unparseable,
@@ -61,6 +63,12 @@ const POLICIES = Object.freeze(['required', 'standard']);
 /** Every review-publication value, in ascending order: off < auto < full. */
 const PUBLICATIONS = Object.freeze(['off', 'auto', 'full']);
 
+/**
+ * Every gate level, strictest first — transcribed from GATE_LEVELS in
+ * src/core/gate-level.ts and pinned to it by a parity test.
+ */
+const GATE_LEVELS = Object.freeze(['full', 'standard', 'lean']);
+
 /**
  * The registered tracker providers — transcribed from TRACKER_PROVIDERS in
  * src/core/tracker.ts and pinned to it by a parity test.
@@ -101,7 +109,7 @@ const SAFE_REF_RE = /^(?![A-Za-z0-9._/-]{0,254}\.\.)[A-Za-z0-9][A-Za-z0-9._/-]{0
 /** The ref namespace of origin's remote-tracking branches, as `git symbolic-ref` prints it. */
 const ORIGIN_TRACKING_PREFIX = 'refs/remotes/origin/';
 
-/** Largest machine manifest read, in bytes. */
+/** Largest machine manifest read, in bytes — pinned to MAX_MANIFEST_BYTES in src/core/gate-level.ts by a parity test. */
 const MAX_MANIFEST_BYTES = 1048576;
 
 /** Deepest nesting the duplicate-key scan follows; deeper is invalid. */
@@ -136,9 +144,12 @@ const MAX_JSON_DEPTH = 32;
  *   tracker: Field<string>,
  *   reviewPublication: Field<'off' | 'auto' | 'full'>,
  *   features: Field<FeatureFields>,
+ *   gateLevel: Field<'full' | 'standard' | 'lean'>,
  * }} PersonalConfig
  *   The personal file's `tracker` is the per-repo provider override: a provider
  *   id string (an empty string reads as absent, as parseTrackerOverride does).
+ *   Its `gateLevel` is one of the three level words; every other value,
+ *   including an empty string and a duplicated key, is malformed.
  *
  * @typedef {{ kind: 'absent' } | { kind: 'refused' } | { kind: 'ok', bytes: Buffer }} BoundedRead
  */
@@ -585,8 +596,8 @@ function parseProjectBytes(buf) {
 
 /**
  * Classify the personal `.devflow/config.json` bytes with the same rules. Only
- * the keys a personal file may carry are read: `reviewPublication`, `features`
- * and the `tracker` override. The retired top-level switches (`memory`,
+ * the keys a personal file may carry are read: `reviewPublication`, `features`,
+ * the `tracker` override and `gateLevel`. The retired top-level switches (`memory`,
  * `learning`, `knowledge`, `decisions`) are never read — `features` is a new
  * namespace, so a stale `learning: false` left from the per-repo-install era
  * cannot come back to life. Never throws.
@@ -607,13 +618,17 @@ function parsePersonalBytes(buf) {
     tracker,
     reviewPublication: fieldOf(obj, duplicates, [], 'reviewPublication', oneOf(PUBLICATIONS)),
     features: featuresField(obj, duplicates),
+    // No exception for an empty string, unlike `tracker`: "" is not a level.
+    gateLevel: fieldOf(obj, duplicates, [], 'gateLevel', oneOf(GATE_LEVELS)),
   });
 }
 
 module.exports = Object.freeze({
   MAX_CONFIG_BYTES,
+  MAX_MANIFEST_BYTES,
   POLICIES,
   PUBLICATIONS,
+  GATE_LEVELS,
   TRACKER_PROVIDER_IDS,
   COMPLIANCE_IDS,
   FEATURE_SWITCHES,