devflow-kit 3.1.0 → 3.3.0

package/src/assets/scripts/hooks/background-memory-update

@@ -2,7 +2,9 @@
 
 # background-memory-update — Eager working-memory refresh worker
 # Spawned as a detached background process by memory-worker (Stop hook) after the
-# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` (sonnet 4.6) →
+# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` on the model
+# and effort the `agents.memory` entry of ~/.devflow/agent-models.json names, else the
+# shipped worker default, in a lean session (D-MEMORY-WORKER-LEAN) →
 # rewrites WORKING-MEMORY.md with a git-reconciliation stamp on line 1.
 #
 # Applies the LLM-vs-plumbing principle: artifact content (WORKING-MEMORY.md) is
@@ -106,6 +108,104 @@ if ! command -v cksum >/dev/null 2>&1; then
   exit 0
 fi
 
+# --- Never write through a symbolic link (D-HOOKS-NO-SYMLINK, git-marker) ---
+# The lock (`mkdir`), the batch merge (`>>`), the claim heartbeat and the success
+# stamp (`touch`) write these paths in place; the claim and the trim rename onto the
+# batch and the swap onto the working memory, and `mv` moves a file into the folder
+# a link at its target names. The trim's copy is created only where nothing stands.
+# So the run is skipped, before it takes the lock or starts an LLM run, when any of
+# these paths or a folder above them is a link.
+if ! df_no_symlink_below "$PROJECT_ROOT" "$LOCK_DIR" "$QUEUE_FILE" "$PROCESSING_FILE" "$OK_FILE" "$MEMORY_FILE"; then
+  log "SKIP: a symbolic link sits on the path to the memory files in $MEMORY_DIR; nothing written"
+  exit 0
+fi
+
+# --- CLI version probe: choose the argv form (D-MEMORY-WORKER-LEAN) ---
+# The lean argv (--effort, --safe-mode, --max-turns, ...) is verified from
+# MEMORY_MIN_CLAUDE_VERSION up. A CLI older than that, or one whose version cannot be
+# read, gets the legacy argv instead, because one flag a CLI does not know fails every
+# run. The probe runs here, once $CLAUDE_BIN has resolved and the link check has
+# passed, and before the lock is taken, so a slow or hung `--version` can never extend
+# the lock's hold. It is bounded by DEVFLOW_BG_VERSION_PROBE_SECS (default 10, at most
+# 60; tests override it as they do DEVFLOW_BG_WATCHDOG_SECS) with the watchdog's
+# background-and-kill idiom. Its output is parsed, never executed.
+#
+# Errexit safety: the worker runs under `set -e`, and a helper's last non-zero status
+# aborts the caller, so each helper below ends in an explicit return status and is
+# called inside an `if` condition.
+MEMORY_MIN_CLAUDE_VERSION="2.1.286"
+
+# Sets CLAUDE_VERSION_TEXT to the first 512 bytes `claude --version` printed ("" on any
+# failure). Returns 0 when it exited 0 inside the bound, else 1. A hung probe gets
+# SIGTERM to its own process group (set -m, as for the spawn below) after the bound
+# and SIGKILL 2s later; the watchdog subshell has its descriptors closed so a sleep it
+# leaves behind holds no pipe open.
+probe_claude_version() {
+  local _secs _out _pid _wd_pid _status=1
+  CLAUDE_VERSION_TEXT=""
+  _secs="${DEVFLOW_BG_VERSION_PROBE_SECS:-10}"
+  case "$_secs" in
+    ''|*[!0123456789]*|????*) _secs=10 ;;
+  esac
+  if [ "$_secs" -lt 1 ] || [ "$_secs" -gt 60 ]; then _secs=10; fi
+  _out=$(mktemp "${TMPDIR:-/tmp}/devflow-claude-version.XXXXXX" 2>/dev/null) || return 1
+  set -m
+  "$CLAUDE_BIN" --version </dev/null >"$_out" 2>/dev/null &
+  _pid=$!
+  set +m
+  (
+    sleep "$_secs"
+    kill -TERM -"$_pid" 2>/dev/null || true
+    sleep 2
+    kill -KILL -"$_pid" 2>/dev/null || true
+  ) </dev/null >/dev/null 2>&1 &
+  _wd_pid=$!
+  if wait "$_pid" 2>/dev/null; then _status=0; fi
+  kill "$_wd_pid" 2>/dev/null || true
+  wait "$_wd_pid" 2>/dev/null || true
+  if [ "$_status" -eq 0 ]; then
+    CLAUDE_VERSION_TEXT=$(head -c 512 "$_out" 2>/dev/null || true)
+  fi
+  rm -f "$_out" 2>/dev/null || true
+  return "$_status"
+}
+
+# Returns 0 when the first X.Y.Z in $1 is at or above the first X.Y.Z in $2, comparing
+# the three components as base-10 numbers left to right (2.10.0 is above 2.1.286, and
+# a leading zero is not octal). Returns 1 when it is below, or when either text holds
+# no X.Y.Z or a component longer than six digits. The digit set is spelled out: a
+# range such as 0-9 collates by locale on bash 3.2.
+claude_version_at_least() {
+  local _text="$1" _floor="$2" _re='([0123456789]+)\.([0123456789]+)\.([0123456789]+)'
+  local _f1 _f2 _f3 _v1 _v2 _v3
+  [[ "$_floor" =~ $_re ]] || return 1
+  _f1=${BASH_REMATCH[1]}; _f2=${BASH_REMATCH[2]}; _f3=${BASH_REMATCH[3]}
+  [[ "$_text" =~ $_re ]] || return 1
+  _v1=${BASH_REMATCH[1]}; _v2=${BASH_REMATCH[2]}; _v3=${BASH_REMATCH[3]}
+  if [ "${#_v1}" -gt 6 ] || [ "${#_v2}" -gt 6 ] || [ "${#_v3}" -gt 6 ]; then return 1; fi
+  _v1=$((10#$_v1)); _v2=$((10#$_v2)); _v3=$((10#$_v3))
+  _f1=$((10#$_f1)); _f2=$((10#$_f2)); _f3=$((10#$_f3))
+  if [ "$_v1" -ne "$_f1" ]; then
+    if [ "$_v1" -gt "$_f1" ]; then return 0; fi
+    return 1
+  fi
+  if [ "$_v2" -ne "$_f2" ]; then
+    if [ "$_v2" -gt "$_f2" ]; then return 0; fi
+    return 1
+  fi
+  if [ "$_v3" -ge "$_f3" ]; then return 0; fi
+  return 1
+}
+
+CLAUDE_ARGV_FORM="legacy"
+if ! probe_claude_version; then
+  log "claude --version probe failed or timed out — using the legacy argv"
+elif claude_version_at_least "$CLAUDE_VERSION_TEXT" "$MEMORY_MIN_CLAUDE_VERSION"; then
+  CLAUDE_ARGV_FORM="lean"
+else
+  log "claude --version is below ${MEMORY_MIN_CLAUDE_VERSION} or unparseable — using the legacy argv"
+fi
+
 # --- Worker-level lock (300s stale-break — much longer than learning-lock's 30s) ---
 # This prevents a second worker (spawned 121s later) from double-writing WORKING-MEMORY.md
 # while the first worker's claude -p call (up to 120s) is still in flight.
@@ -159,7 +259,20 @@ fi
 # Clean up any staged file left by a watchdog-killed prior run.
 # Without this, a stale staged file with a valid stamp would be mistakenly
 # mv-ed to the real path on the NEXT run's CAS check (D-MEMORY-STAGED-CAS).
+#
+# D-MEMORY-WORKER-LEAN: the removal is also a CHECKED precondition. The model gets the
+# Write tool alone, and Write refuses a file that exists and has not been read, which
+# is how an earlier Write-only worker failed silently: every Write errored while the
+# run exited 0. Once nothing stands at the staged path, the one Write is always a
+# create, so Write-only is safe. A path `rm -f` cannot clear (a directory, say) would
+# make every Write fail, so the run stops here instead: no LLM call, the batch and
+# the queue untouched (nothing has been claimed yet), the lock released by the EXIT
+# trap. `-e` or `-L`, so a link there counts as present.
 rm -f "$STAGED_FILE" 2>/dev/null || true
+if [ -e "$STAGED_FILE" ] || [ -L "$STAGED_FILE" ]; then
+  log "SKIP: $STAGED_FILE could not be removed — a Write to it would fail, so no LLM run; the batch and the queue are left as they are"
+  exit 0
+fi
 
 # --- Orphan-only skip: if queue has no assistant/qa turn, exit and leave the queue ---
 # This prevents fabrication-prone LLM runs with only user turns in the queue.
@@ -210,8 +323,20 @@ if [ -f "$PROCESSING_FILE" ]; then
   _PROC_LINES=$(wc -l < "$PROCESSING_FILE" | tr -d ' ')
   if [ "$_PROC_LINES" -gt "$PROC_OVERFLOW_CAP" ]; then
     _PROC_TMP="$PROCESSING_FILE.tmp.$$"
-    tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP" && mv "$_PROC_TMP" "$PROCESSING_FILE" || rm -f "$_PROC_TMP" 2>/dev/null || true
-    log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    # SEC-2: the batch is the claimed queue, 0600 like the queue itself, and the
+    # cold path at session start moves it back to the queue. mv gives it the
+    # trimmed copy's inode and mode, so the copy is created under umask 077, and
+    # 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. Such an entry is removed
+    # instead, and the batch is left untrimmed.
+    if [ ! -e "$_PROC_TMP" ] && [ ! -L "$_PROC_TMP" ] && (umask 077 && set -o noclobber && tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP") && mv "$_PROC_TMP" "$PROCESSING_FILE"; then
+      log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    else
+      rm -f "$_PROC_TMP" 2>/dev/null || true
+      log "Processing overflow: not truncated, its copy could not be written ($_PROC_LINES lines)"
+    fi
   fi
 elif [ -f "$QUEUE_FILE" ]; then
   mv "$QUEUE_FILE" "$PROCESSING_FILE" 2>/dev/null || { log "SKIP: failed to claim queue (race condition — another worker got it)"; exit 0; }
@@ -340,15 +465,22 @@ log "Built $TURN_COUNT turns from queue"
 # on either side, the CAS must treat it as CONFLICT rather than a match — separating
 # the "cksum invocation failure" sentinel from "file absent" keeps the "resolves toward
 # false-conflict, never false-success" invariant true even when cksum errors.
+#
+# D-HOOKS-NO-SYMLINK (git-marker): the existing memory goes into the prompt, so a
+# working memory a symbolic link leads to is treated as absent. A link at its own
+# path has already skipped the run, since the swap renames onto it (above), so
+# only one that appeared since can reach this read.
+MEMORY_PRESENT=""
+if df_file_below "$PROJECT_ROOT" "$MEMORY_FILE"; then MEMORY_PRESENT="yes"; fi
 CKSUM_FAILED="false"
 PRE_RUN_CKSUM="ABSENT"
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   PRE_RUN_CKSUM=$(cksum "$MEMORY_FILE" 2>/dev/null) || CKSUM_FAILED="true"
 fi
 
 EXISTING_MEMORY=""
 MEMORY_READ_LIMIT=65536  # bytes — keep prompt under context limit
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   EXISTING_MEMORY=$(head -c "$MEMORY_READ_LIMIT" "$MEMORY_FILE")
 fi
 
@@ -469,7 +601,107 @@ Instructions:
 EOF
 )
 
-log "Spawning claude -p (model claude-sonnet-4-6, ${TURN_COUNT} turns)"
+# --- Model and effort (D-MEMORY-WORKER-LEAN) ---
+# One authority: WORKER_AGENTS.memory in src/core/agent-models.ts, which `devflow
+# agents` shows as the worker's default. The two defaults below are that row spelled
+# out for bash, held equal to it by tests/agent-models-worker.test.ts, as are the
+# alias and effort lists and the name rules. A personal `agents.memory` entry in
+# $HOME/.devflow/agent-models.json (the machine root; nothing relocates it) overrides
+# them. Each field is validated on its own against the worker domain, so a bad model
+# keeps a good effort and the reverse:
+#   model  = `default` (the shipped one), one of the aliases, or a `claude-` name;
+#            a name starts with a letter or digit, continues with those and . _ -,
+#            and is 64 characters at most (MODEL_NAME_RE in src/core/agent-frontmatter.ts)
+#   effort = `default` (the shipped one) or one of the levels
+# `inherit` is outside both, since a background worker has no session to inherit from.
+# Only a value that passed its match reaches argv. A value that is absent, empty or
+# not a JSON string reads as absent and takes the shipped one silently; a string that
+# fails its match takes it with one log line naming the field, never the value.
+# The character sets are spelled out because a range such as A-Za-z matches accented
+# letters in a UTF-8 locale on bash 3.2.
+MEMORY_MODEL_DEFAULT="claude-sonnet-5-5"
+MEMORY_EFFORT_DEFAULT="high"
+MEMORY_MODEL_ALIASES="haiku sonnet opus fable"
+MEMORY_MODEL_PREFIX="claude-"
+MEMORY_MODEL_MAX_LEN=64
+MEMORY_EFFORT_LEVELS="low medium high xhigh max"
+MEMORY_NAME_HEAD="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+MEMORY_EFFORT_CHARS="abcdefghijklmnopqrstuvwxyz"
+
+# Prints the string value of agents.memory.<field> followed by one `x` (the caller strips
+# it, so a value's own trailing newline survives the command substitution). Prints just
+# the `x` when the file, the field or a string there is missing. Always returns 0.
+memory_agent_field() {
+  local _file="$HOME/.devflow/agent-models.json"
+  if [ "$_JSON_AVAILABLE" = "true" ] && [ -f "$_file" ]; then
+    json_string_field_file "$_file" "agents.memory.$1" 2>/dev/null || true
+  fi
+  printf x
+  return 0
+}
+
+# Sets MEMORY_MODEL. Always returns 0.
+resolve_memory_model() {
+  local _raw _tail="${MEMORY_NAME_HEAD}._-" _ok=""
+  MEMORY_MODEL="$MEMORY_MODEL_DEFAULT"
+  _raw=$(memory_agent_field model)
+  _raw=${_raw%x}
+  case "$_raw" in
+    ''|default) return 0 ;;
+    [!$MEMORY_NAME_HEAD]*|*[!$_tail]*) ;;
+    *)
+      if [ "${#_raw}" -le "$MEMORY_MODEL_MAX_LEN" ]; then
+        case " $MEMORY_MODEL_ALIASES " in
+          *" $_raw "*) _ok="yes" ;;
+        esac
+        case "$_raw" in
+          "$MEMORY_MODEL_PREFIX"?*) _ok="yes" ;;
+        esac
+      fi
+      ;;
+  esac
+  if [ -n "$_ok" ]; then
+    MEMORY_MODEL="$_raw"
+  else
+    log "agents.memory.model: not a model the worker accepts (default, an alias or a ${MEMORY_MODEL_PREFIX} name) — using the shipped model"
+  fi
+  return 0
+}
+
+# Sets MEMORY_EFFORT. Always returns 0.
+resolve_memory_effort() {
+  local _raw _ok=""
+  MEMORY_EFFORT="$MEMORY_EFFORT_DEFAULT"
+  _raw=$(memory_agent_field effort)
+  _raw=${_raw%x}
+  case "$_raw" in
+    ''|default) return 0 ;;
+    *[!$MEMORY_EFFORT_CHARS]*) ;;
+    *)
+      case " $MEMORY_EFFORT_LEVELS " in
+        *" $_raw "*) _ok="yes" ;;
+      esac
+      ;;
+  esac
+  if [ -n "$_ok" ]; then
+    MEMORY_EFFORT="$_raw"
+  else
+    log "agents.memory.effort: not an effort level the worker accepts (default or a level) — using the shipped effort"
+  fi
+  return 0
+}
+
+resolve_memory_model
+resolve_memory_effort
+
+if [ "$CLAUDE_ARGV_FORM" = "lean" ]; then
+  EFFORT_LOG="effort ${MEMORY_EFFORT}"
+  ARGV_LOG="lean argv"
+else
+  EFFORT_LOG="no effort passed"
+  ARGV_LOG="legacy argv"
+fi
+log "Spawning claude -p (model ${MEMORY_MODEL}, ${EFFORT_LOG}, ${ARGV_LOG}, ${TURN_COUNT} turns)"
 # SECURITY: never log PROMPT — it contains turn content which may include secrets
 
 # --- Watchdog timeout (overridable for tests: DEVFLOW_BG_WATCHDOG_SECS=2) ---
@@ -506,14 +738,94 @@ fi
 # Restore set +m immediately after capturing CLAUDE_PID so the watchdog subshell and
 # other subsequent background operations stay in the worker's group.
 # Job-control notifications go to stderr which is redirected to the log — suppress them.
+#
+# D-MEMORY-WORKER-LEAN — the spawn. The worker opens a headless session to make one
+# Write, so the session is cut to what that Write needs. Prompt on stdin, output and
+# errors to the log, as before. Two argv forms, chosen by the version probe above:
+#
+#   lean (CLI at or above MEMORY_MIN_CLAUDE_VERSION):
+#     -p --model M --effort E --safe-mode --tools Write --disable-slash-commands \
+#     --strict-mcp-config --mcp-config '{"mcpServers":{}}' --max-turns 3 \
+#     --dangerously-skip-permissions --output-format text
+#   legacy (older, unreadable or timed-out probe):
+#     -p --model M --tools Write --dangerously-skip-permissions --output-format text
+#
+# What each flag is for:
+#   --model, --effort  the resolved agents.memory values above. --effort is the only
+#                      effort source: an inherited CLAUDE_CODE_EFFORT_LEVEL beats the
+#                      flag (measured on 2026-10-09), so it is unset below, for both
+#                      forms, and the log's "no effort passed" is then true.
+#   --safe-mode        starts with the user's customisations off: instruction files,
+#                      skills, plugins, hooks, MCP servers, custom commands and agents.
+#                      Auth, model selection and built-in tools work as usual, and
+#                      settings `env` (the provider URL and key) still applies under
+#                      it (measured on 2026-10-09), so a routed or keyed install works.
+#   --tools Write      Write is the only tool. `--allowedTools` only pre-approves, it
+#                      leaves every tool, listing and MCP server loaded.
+#   --disable-slash-commands, --strict-mcp-config with an empty --mcp-config
+#                      no slash-command or skill listing, no MCP server and none of the
+#                      instructions they add to the context.
+#   --max-turns 3      the worker's own pattern is one Write and then the end of the
+#                      turn, two requests; the third is margin. A run that reaches the
+#                      cap exits non-zero, so its batch stays for the retry; the Write
+#                      on the capped turn still runs. 3 was verified on claude 2.1.294
+#                      on 2026-10-09 (cap 1 exits 1, caps 2 and 3 exit 0 on that
+#                      pattern). `--max-turns` is not listed in `claude --help` there
+#                      but is registered (`--max-turns abc` errors "must be a number"),
+#                      which is why it was exercised rather than read off the help.
+#   --dangerously-skip-permissions  headless: nothing could answer a prompt.
+#   --output-format text
+#   DEVFLOW_BG_UPDATER=1  the recursion guard stays on both forms, though --safe-mode
+#                      also disables hooks. CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 and
+#                      CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 keep the instruction files and
+#                      auto-memory out on both forms, including the legacy one.
+#
+# Why Write-only is safe: the staged path is empty before every run (the removal and
+# the checked precondition after the lock above), so the one Write is always a create.
+# Write refuses an existing file that has not been read, and that is the whole history
+# of this flag set:
+#   a472a490  passed `--tools "Write"` with `--allowedTools` for two memory files;
+#   e701cecc  widened the tools to `Read,Write,Bash` after counting the silent
+#             read-before-write failures (the run exited 0 while every Write errored);
+#   baf02265  removed both flags, with no reason in its message;
+#   6186645f  raised the worker's model and kept `--allowedTools 'Read,Write'`.
+#
+# The version floor is 2.1.286, the lowest CLI on which the whole lean argv was run
+# and its flags, the settings `env` under --safe-mode and the effort override were
+# checked (2.1.286 and 2.1.292 to 2.1.294 behave identically; 2026-10-09, recorded in
+# docs/reference/platform-assumptions.md). The legacy form carries no --effort,
+# --safe-mode, --max-turns, --disable-slash-commands, --strict-mcp-config or
+# --mcp-config, none of which is verified on older CLIs, so on it effort is not
+# applied, MCP servers stay loaded and there is no turn cap.
+#
+# The turns input has no byte cap: the queue holds every turn whole by design, and the
+# prompt is bounded by the newest-20-rows window above and the 64 KB existing-memory
+# cap, not by cutting a turn.
+unset CLAUDE_CODE_EFFORT_LEVEL
 set -m
-DEVFLOW_BG_UPDATER=1 "$CLAUDE_BIN" -p \
-  --model claude-sonnet-4-6 \
-  --dangerously-skip-permissions \
-  --allowedTools 'Read,Write' \
-  --output-format text \
-  <<< "$PROMPT" \
-  >> "$LOG_FILE" 2>&1 &
+if [ "$CLAUDE_ARGV_FORM" = "lean" ]; then
+  DEVFLOW_BG_UPDATER=1 CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 "$CLAUDE_BIN" -p \
+    --model "$MEMORY_MODEL" \
+    --effort "$MEMORY_EFFORT" \
+    --safe-mode \
+    --tools Write \
+    --disable-slash-commands \
+    --strict-mcp-config \
+    --mcp-config '{"mcpServers":{}}' \
+    --max-turns 3 \
+    --dangerously-skip-permissions \
+    --output-format text \
+    <<< "$PROMPT" \
+    >> "$LOG_FILE" 2>&1 &
+else
+  DEVFLOW_BG_UPDATER=1 CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 "$CLAUDE_BIN" -p \
+    --model "$MEMORY_MODEL" \
+    --tools Write \
+    --dangerously-skip-permissions \
+    --output-format text \
+    <<< "$PROMPT" \
+    >> "$LOG_FILE" 2>&1 &
+fi
 CLAUDE_PID=$!
 set +m
 
@@ -572,13 +884,28 @@ fi
 # Each state is assigned exactly once at the point it is decided (single OUTCOME
 # variable, three states).
 verify_and_swap() {
-  [ -f "$STAGED_FILE" ] && [ -s "$STAGED_FILE" ] || {
+  # A symbolic link at the staged path counts as no staged file (D-HOOKS-NO-SYMLINK,
+  # git-marker): `head` below would read the file it names, and the swap's `mv`
+  # would rename the link itself into the working memory's place. The worker
+  # removed that path before the LLM run, so a link there was planted during it.
+  # df_file_below checks it before both, and logs the refusal once.
+  df_file_below "$PROJECT_ROOT" "$STAGED_FILE" && [ -s "$STAGED_FILE" ] || {
     log "WARN: staged file missing or empty after claude -p run"; OUTCOME="failed"; return; }
   case "$(head -1 "$STAGED_FILE" 2>/dev/null || echo "")" in
     "<!-- memory-head:"*) : ;;
     *) log "WARN: staged file exists but stamp missing on line 1 — treating as failure"
        rm -f "$STAGED_FILE" 2>/dev/null || true; OUTCOME="failed"; return ;;
   esac
+  # A symbolic link on the working memory's path refuses the swap
+  # (D-HOOKS-NO-SYMLINK, git-marker): the run began without one, so a link there now
+  # is a change made during the run, and `mv` would move the staged memory into a
+  # folder it names. When the run began with no working memory, the cksum
+  # comparison below would take the link for that absent file.
+  if ! df_no_symlink_below "$PROJECT_ROOT" "$MEMORY_FILE"; then
+    rm -f "$STAGED_FILE" 2>/dev/null || true
+    log "CONFLICT: a symbolic link appeared on the path to $MEMORY_FILE during the run — not swapped, leaving .processing for retry"
+    OUTCOME="conflict"; return
+  fi
   # Re-check real file cksum before swapping.
   # Residual TOCTOU: a human edit landing in the O(ms) window between this
   # cksum re-check and the mv would be clobbered; this is accepted — the
@@ -613,14 +940,26 @@ verify_and_swap() {
 OUTCOME="failed"
 verify_and_swap
 
+# Each stamp below is a `touch`, which follows a symbolic link, and its path was
+# checked before the LLM run, which can take minutes. So, like the swap's target,
+# it is checked again just before the touch: a link there now is a change made
+# during the run, and the stamp is skipped and logged (D-HOOKS-NO-SYMLINK, git-marker).
 if [ "$OUTCOME" = "updated" ]; then
   rm -f "$PROCESSING_FILE" 2>/dev/null || true
-  touch "$OK_FILE" 2>/dev/null || true
-  log "SUCCESS: queue drained, .last-refresh-ok touched"
+  if df_no_symlink_below "$PROJECT_ROOT" "$OK_FILE"; then
+    touch "$OK_FILE" 2>/dev/null || true
+    log "SUCCESS: queue drained, .last-refresh-ok touched"
+  else
+    log "SUCCESS: queue drained; .last-refresh-ok not touched, a symbolic link appeared on its path during the run"
+  fi
 elif [ "$OUTCOME" = "conflict" ]; then
   # Heartbeat: this batch is still owned by the retry cycle, not orphaned.
   # Keeps session-start-memory's 300s cold path from reclaiming a live retry.
-  touch "$PROCESSING_FILE" 2>/dev/null || true
+  if df_no_symlink_below "$PROJECT_ROOT" "$PROCESSING_FILE"; then
+    touch "$PROCESSING_FILE" 2>/dev/null || true
+  else
+    log "Heartbeat skipped: a symbolic link appeared on the path to $PROCESSING_FILE during the run"
+  fi
   log "CONFLICT: queue retained in .processing, .last-refresh-ok untouched"
 else
   # Leave .processing for session-start-memory's D56c cold path; do NOT touch .last-refresh-ok

package/src/assets/scripts/hooks/capture-prompt

@@ -84,11 +84,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-prompt: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-prompt: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "user" "$PROMPT" "$TS"
 

package/src/assets/scripts/hooks/capture-question

@@ -140,8 +140,8 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-question: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-question: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 _QUESTION_COUNT=0
 while IFS=$'\t' read -r Q A; do
   [ -z "$Q" ] && continue
@@ -150,7 +150,8 @@ while IFS=$'\t' read -r Q A; do
 A: ${A}"
   TS=$(date +%s)
   queue_append_both \
-    "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+    "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+    "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
     "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
     "qa" "$CONTENT" "$TS"
   _QUESTION_COUNT=$(( _QUESTION_COUNT + 1 ))

package/src/assets/scripts/hooks/capture-turn

@@ -90,11 +90,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-turn: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-turn: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "assistant" "$ASSISTANT_MSG" "$TS"
 

package/src/assets/scripts/hooks/ensure-devflow-init

@@ -2,7 +2,8 @@
 # Ensures .devflow/ and all subdirectories exist and the project root .gitignore
 # ignores .devflow/. Called from capture-prompt, capture-turn, capture-question,
 # memory-worker, and pre-compact-memory. Idempotent.
-# Returns non-zero, having written nothing, outside a git project or at HOME.
+# Returns non-zero, having written nothing, outside a git project, at HOME, or when
+# .devflow is a symbolic link.
 # Usage: source ensure-devflow-init "$CWD"
 
 [ -z "$1" ] && return 1
@@ -33,6 +34,17 @@ df_is_project_root "$_EDI_ROOT" 2>/dev/null || return 1
 
 _DEVFLOW_DIR="$_EDI_ROOT/.devflow"
 
+# D-HOOKS-NO-SYMLINK (git-marker): a `.devflow` that is itself a symbolic link
+# would take every folder below and the carve-out marker into the folder it names,
+# so nothing is written and the caller stops, as at any root it may not write to.
+# The skip is logged once, through log() where the caller defines it. A folder below
+# `.devflow` that is a link is left to the write under it: `mkdir -p` creates
+# nothing through a link it ends at.
+if ! df_no_symlink_below "$_EDI_ROOT" "$_DEVFLOW_DIR"; then
+  declare -F log >/dev/null 2>&1 && log "Skipped: $_DEVFLOW_DIR is a symbolic link; nothing written under it"
+  return 1
+fi
+
 # learning/ is scaffolded only where the ledger lives. In a linked worktree whose
 # main checkout holds the ledger (D-LEDGER-MAIN-WORKTREE, resolve-project-root) a
 # learning/ here would be an empty directory nothing writes to; the capture hooks