devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/lib/tracked-areas.cjs

@@ -0,0 +1,452 @@
+// src/assets/scripts/hooks/lib/tracked-areas.cjs
+//
+// Does git track any entry under one of devflow's data folders at a root? One
+// `git ls-files` call over a fixed set of pathspecs answers `tracked`, `untracked` or
+// `unknown`, for one area at a time: `curation` (the curation folder, the old ledger
+// folder and the backup folders), `memory` (the memory folder) or `both` (the union of the
+// two, one call, for a caller that serves both areas at one root). The one-time ledger move
+// and the backup sweep ask it for the curation area before they lock, read or rename
+// anything: a folder that git tracks is the repository's content, so they leave it alone.
+//
+// DESIGN: a leaf. It loads node built-ins and project-paths.cjs (which loads node
+// built-ins only) and requires neither the store nor the move module (the move requires
+// the store; the store never requires the move), so either of them, and a check for
+// another folder, can use it. No function here prints or exits, and nothing throws:
+// every failure is the answer `unknown`, with a cause from the closed set UNKNOWN_CAUSES.
+//
+// The folder names come from project-paths.cjs, which owns them: AREA_FOLDERS lists the
+// curation area's data folders, the backup prefix names the folders the move leaves
+// behind, and the memory folder is the one getMemoryDir names. To cover another folder of
+// an area, add it to that area's pathspecs.
+//
+// The decision is the repository's index, never the disk. A root with no `.git` entry
+// (a file or a folder) is not a git working tree and gets no git call. A root with one
+// gets exactly one call, and every failure of that call (git missing, a timeout, a
+// non-zero exit with nothing listed) is `unknown`: the caller cannot tell what git
+// tracks and must change nothing. git's error text is never read.
+//
+// trackedAreaCall splits the check in two: it decides whether a call is due and, when it
+// is, describes it (working directory, argv, environment); a caller that runs git in
+// another way (the TypeScript seam's bounded async runner, the settings resolver's
+// injected exec) executes that description and hands the result to judgeTrackedAreas, so
+// every runner gives the answer this leaf gives.
+//
+// COPIES: the leaf is not the only place that holds some of these lists. The shell twin in
+// the capture gate file (hooks/queue-append) keeps its own copy of the pathspecs
+// (`_qta_specs`) and of the list of git variables it removes (the `unset` line of
+// `_qta_probe`), because it runs git without node. Two folder-to-area maps restate which
+// folder belongs to which area: `_qar_area_of` in that file and `projectDataAreaOf` in
+// src/cli/commands/uninstall.ts. Each copy is held equal to the lists here by
+// tests/decisions/tracked-area-parity.test.ts, so a change to a list here fails that test
+// until every copy follows it.
+
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { LEGACY_NAMES, CURATION_DIR_NAME, getMemoryDir } = require('./project-paths.cjs');
+
+/** The curation data folders under `.devflow` that the check covers, by the names the path helpers hold. */
+const AREA_FOLDERS = Object.freeze([LEGACY_NAMES.folder, CURATION_DIR_NAME]);
+
+/** The memory folder under `.devflow`, by the name getMemoryDir gives it. */
+const MEMORY_FOLDER = path.basename(getMemoryDir(path.sep));
+
+/**
+ * The spellings a case-folding file system opens as `.devflow` beyond ASCII letter case.
+ * git's `icase` folds ASCII letters only, but APFS (the macOS default) compares names by
+ * full Unicode case folding, so it also opens `.devflow` (U+FB02 folds to "fl"). The code
+ * is written with an escape, so the code point is named.
+ */
+const DEVFLOW_SPELLINGS = Object.freeze(['.devflow', '.dev\u{FB02}ow']);
+
+/**
+ * The pathspecs of the curation area, each matched without regard to ASCII letter case,
+ * whatever the file system or `core.ignorecase`, and each spelled every way
+ * DEVFLOW_SPELLINGS lists:
+ *   - each folder of AREA_FOLDERS, as a literal path: an index entry at the folder, or
+ *     anywhere below it, matches
+ *   - an entry named like a backup folder (`<backup prefix>*`), and every entry below one
+ *     (`<backup prefix>*` + `/**`): the move leaves its old folder there, and the sweep
+ *     merges the queue files in it into the new folder. The prefix has no glob character.
+ *   - an index entry named `.devflow` ITSELF, which git records only for a symlink, a
+ *     gitlink (submodule) or a plain file, never for a directory: the character class
+ *     keeps `glob` from matching as a leading directory, so the many files under a
+ *     normal `.devflow/` are not listed. Committed content then stands at the path where
+ *     the folders are opened.
+ * The ledger move and the backup sweep ask for this set, and its order and spelling stay
+ * as they are.
+ */
+const TRACKED_AREA_PATHSPECS = Object.freeze([
+  ...DEVFLOW_SPELLINGS.flatMap(dir => [
+    ...AREA_FOLDERS.map(area => ':(icase,literal)' + dir + '/' + area),
+    ':(icase,glob)' + dir + '/' + LEGACY_NAMES.backupPrefix + '*',
+    ':(icase,glob)' + dir + '/' + LEGACY_NAMES.backupPrefix + '*/**',
+  ]),
+  ...DEVFLOW_SPELLINGS.map(dir => ':(icase,glob)[.]' + dir.slice(1)),
+]);
+
+/**
+ * The pathspecs of the memory area, matched and spelled as the curation area's are: the
+ * memory folder as a literal path (an entry at the folder, or anywhere below it), and the
+ * `.devflow` entry itself.
+ */
+const MEMORY_AREA_PATHSPECS = Object.freeze([
+  ...DEVFLOW_SPELLINGS.map(dir => ':(icase,literal)' + dir + '/' + MEMORY_FOLDER),
+  ...DEVFLOW_SPELLINGS.map(dir => ':(icase,glob)[.]' + dir.slice(1)),
+]);
+
+/**
+ * The pathspecs of the two areas together: the curation set, then the memory set, each
+ * pathspec once (the `.devflow` entry forms stand in both sets). One call over this set
+ * answers `tracked` when git tracks anything either area covers.
+ */
+const BOTH_AREAS_PATHSPECS = Object.freeze([...new Set([...TRACKED_AREA_PATHSPECS, ...MEMORY_AREA_PATHSPECS])]);
+
+/** The pathspecs of each area, by the area's name: the closed set of areas the check knows. */
+const AREA_PATHSPECS = Object.freeze({
+  curation: TRACKED_AREA_PATHSPECS,
+  memory: MEMORY_AREA_PATHSPECS,
+  both: BOTH_AREAS_PATHSPECS,
+});
+
+/**
+ * Why a check answered `unknown`, as one fixed word. The words come from this list
+ * alone: they name a spawn error code, a time out, a signal, an exit status or the step
+ * that failed, and never carry git's own text or a path.
+ */
+const UNKNOWN_CAUSES = Object.freeze({
+  rootNotAbsolute: 'root-not-absolute',
+  gitEntryUnreadable: 'git-entry-unreadable',
+  ceilingUnusable: 'ceiling-unusable',
+  checkFailed: 'check-failed',
+  gitNotFound: 'git-not-found',
+  gitTimedOut: 'git-timed-out',
+  gitStopped: 'git-stopped',
+  gitExitStatus: 'git-exit-status',
+  gitNotRun: 'git-not-run',
+});
+
+/** The longest the git call may run (ms). */
+const TRACKED_AREAS_GIT_TIMEOUT_MS = 5000;
+
+/**
+ * The most output the git call may return, in bytes. A normal answer is empty; a
+ * listing past this bound (ENOBUFS) means entries exist, which reads as tracked.
+ */
+const TRACKED_AREAS_GIT_MAX_BUFFER = 4096;
+
+/**
+ * The variables that make git read another repository, another index or other pathspec
+ * rules than the root's own. The call runs without them.
+ */
+const GIT_REDIRECT_VARIABLES = Object.freeze([
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_LITERAL_PATHSPECS',
+  'GIT_GLOB_PATHSPECS',
+  'GIT_NOGLOB_PATHSPECS',
+  'GIT_ICASE_PATHSPECS',
+]);
+
+/**
+ * A copy of `base` without the redirecting variables (GIT_REDIRECT_VARIABLES): git then
+ * reads the repository, index and pathspec rules of the directory it runs in. Nothing else
+ * changes. For a caller that runs git for its own purpose and needs only the scrub.
+ *
+ * @param {NodeJS.ProcessEnv} base
+ * @returns {NodeJS.ProcessEnv}
+ */
+function gitEnvWithoutRedirects(base) {
+  const env = { ...base };
+  for (const name of GIT_REDIRECT_VARIABLES) delete env[name];
+  return env;
+}
+
+/**
+ * The environment of the git call: the process environment without the redirecting
+ * variables, with a fixed locale, no optional lock and a ceiling directory. Answers a new
+ * object. The ceiling is the folder that holds the root: git reads the root's own `.git`
+ * and never looks in a folder above it, so an empty or broken `.git` at the root is not
+ * answered from a work tree around the project.
+ *
+ * @param {NodeJS.ProcessEnv} base
+ * @param {string} ceiling - an absolute path with no list separator in it
+ * @returns {NodeJS.ProcessEnv}
+ */
+function trackedAreasGitEnv(base, ceiling) {
+  const env = gitEnvWithoutRedirects(base);
+  env.LC_ALL = 'C';
+  env.GIT_OPTIONAL_LOCKS = '0';
+  env.GIT_CEILING_DIRECTORIES = ceiling;
+  return env;
+}
+
+/**
+ * The answer of one `git ls-files` call, from the result `spawnSync` gave, with the
+ * cause when the answer is `unknown` (null otherwise):
+ *   tracked    any output byte, whatever the exit status or error (the call listed an
+ *              entry), and an output past the buffer cap (ENOBUFS)
+ *   untracked  exit 0 with nothing listed
+ *   unknown    every other result, with the cause: git-not-found (spawn error ENOENT),
+ *              git-timed-out (ETIMEDOUT), git-not-run (another spawn error, or a result
+ *              of the wrong shape), git-stopped (a signal ended it), git-exit-status (a
+ *              non-zero exit with nothing listed)
+ * Pure: it reads only the fields `error.code`, `status`, `signal` and `stdout`.
+ *
+ * @param {unknown} result
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function judgeTrackedAreas(result) {
+  if (result === null || typeof result !== 'object') return unknownBecause(UNKNOWN_CAUSES.gitNotRun);
+  const { error, status, signal, stdout } = /** @type {{ error?: { code?: unknown }, status?: unknown, signal?: unknown, stdout?: unknown }} */ (result);
+  if (error && error.code === 'ENOBUFS') return { answer: 'tracked', cause: null };
+  const listed = (typeof stdout === 'string' || Buffer.isBuffer(stdout)) && stdout.length > 0;
+  if (listed) return { answer: 'tracked', cause: null };
+  if (error) {
+    if (error.code === 'ENOENT') return unknownBecause(UNKNOWN_CAUSES.gitNotFound);
+    return unknownBecause(error.code === 'ETIMEDOUT' ? UNKNOWN_CAUSES.gitTimedOut : UNKNOWN_CAUSES.gitNotRun);
+  }
+  if (status === 0) return { answer: 'untracked', cause: null };
+  if (typeof status === 'number') return unknownBecause(UNKNOWN_CAUSES.gitExitStatus);
+  return unknownBecause(typeof signal === 'string' ? UNKNOWN_CAUSES.gitStopped : UNKNOWN_CAUSES.gitNotRun);
+}
+
+/**
+ * @param {string} cause - a value of UNKNOWN_CAUSES
+ * @returns {{ answer: 'unknown', cause: string }}
+ */
+function unknownBecause(cause) {
+  return { answer: 'unknown', cause };
+}
+
+/**
+ * The answer of {@link judgeTrackedAreas}, without its cause.
+ *
+ * @param {unknown} result
+ * @returns {'tracked' | 'untracked' | 'unknown'}
+ */
+function classifyTrackedAreas(result) {
+  return judgeTrackedAreas(result).answer;
+}
+
+/**
+ * Whether anything (a file, a folder, a link) stands at `target`: true, false, or null
+ * when the probe failed for a reason other than absence.
+ *
+ * @param {string} target
+ * @returns {boolean | null}
+ */
+function entryExists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch (err) {
+    return err && (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : null;
+  }
+}
+
+/**
+ * The pathspecs of `area`, or null when the leaf does not know the area. Only the own
+ * names of AREA_PATHSPECS count: a name from the object prototype is no area.
+ *
+ * @param {unknown} area
+ * @returns {readonly string[] | null}
+ */
+function pathspecsOf(area) {
+  if (typeof area !== 'string' || !Object.prototype.hasOwnProperty.call(AREA_PATHSPECS, area)) return null;
+  return AREA_PATHSPECS[/** @type {'curation' | 'memory' | 'both'} */ (area)];
+}
+
+/**
+ * Whether a git call is due for `area` at `root`, and the call when it is. Makes no
+ * call and starts no process: it reads only the `.git` entry at the root and the root's
+ * real path. Answers one of:
+ *
+ *   {answer, cause}      no call is due: `untracked` (no `.git` entry at the root), or
+ *                        `unknown` with a cause from UNKNOWN_CAUSES (an area the leaf does
+ *                        not know, a root that is not an absolute path string, a `.git`
+ *                        entry that could not be probed, a folder above the root that
+ *                        holds the list separator, or a failure)
+ *   {cwd, argv, env}     the call: run `git` with `argv` and `env` in `cwd` with no shell,
+ *                        bound its time (TRACKED_AREAS_GIT_TIMEOUT_MS) and its output
+ *                        (TRACKED_AREAS_GIT_MAX_BUFFER), and give the result to
+ *                        judgeTrackedAreas
+ *
+ * The call is `git --no-literal-pathspecs -c core.fsmonitor=false ls-files -z -- <paths>`.
+ * `--no-literal-pathspecs` leads the argv, so a forced literal-pathspec setting cannot
+ * turn the magic off and hide an entry. Reading the index makes git run the command a
+ * repository's config names in `core.fsmonitor`, so the call turns that off for itself and
+ * stays a pure read. The folder above the root's real path is a ceiling directory
+ * (trackedAreasGitEnv); a parent path that holds the list separator can not be named as
+ * one, and answers `unknown`. Each answer is a new object.
+ *
+ * @param {unknown} root - an absolute path
+ * @param {unknown} area - 'curation', 'memory' or 'both'
+ * @param {NodeJS.ProcessEnv} [baseEnv] - the environment the call's own derives from (default: the process environment)
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null } | { cwd: string, argv: string[], env: NodeJS.ProcessEnv }}
+ */
+function trackedAreaCall(root, area, baseEnv = process.env) {
+  const pathspecs = pathspecsOf(area);
+  if (typeof root !== 'string' || !path.isAbsolute(root)) return unknownBecause(UNKNOWN_CAUSES.rootNotAbsolute);
+  if (pathspecs === null) return unknownBecause(UNKNOWN_CAUSES.checkFailed);
+  try {
+    const gitEntry = entryExists(path.join(root, '.git'));
+    if (gitEntry === null) return unknownBecause(UNKNOWN_CAUSES.gitEntryUnreadable);
+    if (gitEntry === false) return { answer: 'untracked', cause: null };
+    const ceiling = path.dirname(fs.realpathSync(root));
+    if (ceiling.includes(path.delimiter)) return unknownBecause(UNKNOWN_CAUSES.ceilingUnusable);
+    return {
+      cwd: root,
+      argv: ['--no-literal-pathspecs', '-c', 'core.fsmonitor=false', 'ls-files', '-z', '--', ...pathspecs],
+      env: trackedAreasGitEnv(baseEnv, ceiling),
+    };
+  } catch (_) {
+    return unknownBecause(UNKNOWN_CAUSES.checkFailed);
+  }
+}
+
+/**
+ * The time bound of one check: `options.timeoutMs` when it is a positive finite number of
+ * milliseconds, otherwise TRACKED_AREAS_GIT_TIMEOUT_MS. A zero would mean no bound at all
+ * to the spawn call, so it is never passed on.
+ *
+ * @param {unknown} options
+ * @returns {number}
+ */
+function timeoutOf(options) {
+  const timeoutMs = options !== null && typeof options === 'object' ? /** @type {{ timeoutMs?: unknown }} */ (options).timeoutMs : undefined;
+  return typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : TRACKED_AREAS_GIT_TIMEOUT_MS;
+}
+
+/**
+ * Whether git tracks any entry under the folders of `area` ('curation', 'memory' or 'both',
+ * the union of the two) at `root`, or an entry named `.devflow` itself (a link, a gitlink or
+ * a file). The index
+ * decides, not the disk, and a staged entry counts. The answer carries the cause (a value
+ * of UNKNOWN_CAUSES) when it is `unknown`, and null otherwise.
+ *
+ *   untracked  no `.git` entry at the root (no git call is made), or git listed nothing
+ *   tracked    git listed an entry
+ *   unknown    a `.git` entry stands and git did not answer (see judgeTrackedAreas),
+ *              the `.git` entry could not be probed, the root is not an absolute path
+ *              string, or the area is not one the leaf knows (no git call is made)
+ *
+ * The call is the one trackedAreaCall describes, run with a time bound (`options.timeoutMs`,
+ * default TRACKED_AREAS_GIT_TIMEOUT_MS) and an output bound.
+ *
+ * @param {unknown} root - an absolute path
+ * @param {unknown} area - 'curation', 'memory' or 'both'
+ * @param {{ timeoutMs?: number }} [options]
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function inspectTrackedArea(root, area, options) {
+  const call = trackedAreaCall(root, area);
+  if (!('argv' in call)) return call;
+  try {
+    const result = childProcess.spawnSync('git', call.argv, {
+      cwd: call.cwd,
+      env: call.env,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutOf(options),
+      maxBuffer: TRACKED_AREAS_GIT_MAX_BUFFER,
+      windowsHide: true,
+      shell: false,
+    });
+    return judgeTrackedAreas(result);
+  } catch (_) {
+    return unknownBecause(UNKNOWN_CAUSES.checkFailed);
+  }
+}
+
+/**
+ * The answer of {@link inspectTrackedArea}, without its cause.
+ *
+ * @param {unknown} root - an absolute path
+ * @param {unknown} area - 'curation', 'memory' or 'both'
+ * @returns {'tracked' | 'untracked' | 'unknown'}
+ */
+function checkTrackedArea(root, area) {
+  return inspectTrackedArea(root, area).answer;
+}
+
+/** The most answers the per-process memo of inspectTrackedAreaOnce holds. */
+const ANSWER_MEMO_MAX_ENTRIES = 64;
+
+/** The answers inspectTrackedAreaOnce has given in this process, by area and root, oldest first. */
+const answerMemo = new Map();
+
+/**
+ * {@link inspectTrackedArea}, asked once per root and area for the life of the process: a
+ * later ask for the same root and area gets the first answer and makes no git call, even if
+ * the project changed meanwhile. For a one-shot process (json-helper, the render check)
+ * whose steps each ask before they read or write: together they cost one git call. A
+ * long-lived caller, or one that changes what git tracks, asks inspectTrackedArea. The
+ * memo holds at most ANSWER_MEMO_MAX_ENTRIES answers; past that the oldest goes. Each
+ * answer is a new object.
+ *
+ * @param {unknown} root - an absolute path
+ * @param {unknown} area - 'curation', 'memory' or 'both'
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function inspectTrackedAreaOnce(root, area) {
+  const key = typeof root === 'string' && typeof area === 'string' ? area + '\0' + root : null;
+  const known = key === null ? undefined : answerMemo.get(key);
+  if (known !== undefined) return { answer: known.answer, cause: known.cause };
+  const answer = inspectTrackedArea(root, area);
+  if (key !== null) {
+    if (answerMemo.size >= ANSWER_MEMO_MAX_ENTRIES) answerMemo.delete(answerMemo.keys().next().value);
+    answerMemo.set(key, Object.freeze({ answer: answer.answer, cause: answer.cause }));
+  }
+  return answer;
+}
+
+/**
+ * Whether git tracks any entry under the curation area's folders at `root`: the check the
+ * ledger move, the backup sweep and the drains ask. {@link inspectTrackedArea} for the
+ * curation area.
+ *
+ * @param {unknown} root - an absolute path
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function inspectTrackedAreas(root) {
+  return inspectTrackedArea(root, 'curation');
+}
+
+/**
+ * The answer of {@link inspectTrackedAreas}, without its cause.
+ *
+ * @param {unknown} root - an absolute path
+ * @returns {'tracked' | 'untracked' | 'unknown'}
+ */
+function checkTrackedAreas(root) {
+  return inspectTrackedAreas(root).answer;
+}
+
+module.exports = {
+  TRACKED_AREA_PATHSPECS,
+  MEMORY_AREA_PATHSPECS,
+  AREA_PATHSPECS,
+  DEVFLOW_SPELLINGS,
+  GIT_REDIRECT_VARIABLES,
+  TRACKED_AREAS_GIT_TIMEOUT_MS,
+  TRACKED_AREAS_GIT_MAX_BUFFER,
+  ANSWER_MEMO_MAX_ENTRIES,
+  UNKNOWN_CAUSES,
+  gitEnvWithoutRedirects,
+  judgeTrackedAreas,
+  classifyTrackedAreas,
+  trackedAreaCall,
+  inspectTrackedArea,
+  inspectTrackedAreaOnce,
+  checkTrackedArea,
+  inspectTrackedAreas,
+  checkTrackedAreas,
+};

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

@@ -16,6 +16,11 @@
 #   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
 #
+# The worker writes a notice, or counts a denied run, only while the memory area is known
+# to be free of files that git tracks: DF_TRACKED_AREA_MEMORY (queue_tracked_area, queue-append)
+# must read `untracked` in the calling process. Any other value, an unset one included,
+# is a paused area, and both helpers then write nothing.
+#
 # 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.
 #
@@ -241,13 +246,15 @@ memory_result_summary() {
 # 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.
+# itself exclusive. Content: the reason. Best effort: a refusal leaves nothing. Nothing is
+# written unless DF_TRACKED_AREA_MEMORY reads `untracked` in this process.
 memory_notice_write() {
   local _dir="${1:-}" _root="${2:-}" _reason="${3:-}" _file
   case " $MEMORY_NOTICE_REASONS " in
     *" $_reason "*) ;;
     *) return 0 ;;
   esac
+  [ "${DF_TRACKED_AREA_MEMORY:-}" = "untracked" ] || return 0
   [ -d "$_dir" ] || return 0
   _file="$_dir/.worker-notice-$_reason"
   if ! path_occupied "$_file" && ! path_occupied "$_file.shown" \
@@ -285,9 +292,10 @@ memory_notice_clear() {
 # 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.
+# them count. No marker is left unless DF_TRACKED_AREA_MEMORY reads `untracked` in this process.
 memory_denied_seen() {
   local _dir="${1:-}" _root="${2:-}" _mark
+  [ "${DF_TRACKED_AREA_MEMORY:-}" = "untracked" ] || return 0
   [ -d "$_dir" ] || return 0
   _mark="$_dir/.worker-denied-once"
   if path_occupied "$_mark"; then

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

@@ -43,7 +43,7 @@ MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 
 # Memory gate: the machine switch, narrowed by this checkout's project.json /
 # config.json `features.memory`, gates this hook entirely -- read by the helper
-# every memory/learning gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
+# every memory/curation gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "memory-worker: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"
@@ -104,6 +104,17 @@ if [ ! -x "$UPDATER" ]; then
   exit 0
 fi
 
+# Memory area check: while git tracks files in the memory folder of this checkout, or a
+# `.git` entry stands and git does not answer, the memory area is paused, and this hook
+# stamps no trigger and spawns no worker. It asks once, in git mode (queue_tracked_area),
+# at the project root, after the throttle so a throttled Stop event costs nothing.
+queue_tracked_area "$PROJECT_ROOT" memory git
+if [ "${DF_TRACKED_AREA_MEMORY:-unknown}" != "untracked" ]; then
+  log "Memory paused: git tracks files in the memory folder, or did not answer; trigger not stamped, worker not spawned"
+  dbg "EXIT: memory area paused"
+  exit 0
+fi
+
 dbg "Throttle passed: TRIGGER_AGE=${TRIGGER_AGE}s >= 120s — spawning worker"
 
 # Touch trigger BEFORE spawning (prevents concurrent Stop hooks from double-spawning)

package/src/assets/scripts/hooks/pre-compact-memory

@@ -54,7 +54,7 @@ MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 source "$SCRIPT_DIR/hook-log-init" "pre-compact-memory"
 
 # Memory gate: the machine switch, narrowed by this checkout's project.json /
-# config.json `features.memory`, read by the helper every memory/learning gate
+# config.json `features.memory`, read by the helper every memory/curation gate
 # shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "pre-compact-memory: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
@@ -63,6 +63,17 @@ if [ "$_QG_MEMORY" != "true" ]; then
   exit 0
 fi
 
+# Memory area check: while git tracks files in the memory folder of this checkout, or a
+# `.git` entry stands and git does not answer, the memory area is paused, and this hook
+# makes no folder, writes no backup and bootstraps no working memory. The check asks once,
+# in node mode, so a git that hangs is cut (queue_tracked_area), at the project root.
+queue_tracked_area "$PROJECT_ROOT" memory node
+if [ "${DF_TRACKED_AREA_MEMORY:-unknown}" != "untracked" ]; then
+  log "Memory paused: git tracks files in the memory folder, or did not answer; no backup or working memory written"
+  dbg "EXIT: memory area paused"
+  exit 0
+fi
+
 # Auto-create .devflow/ and ensure .gitignore entries (idempotent after first run)
 source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 
@@ -112,27 +123,18 @@ if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   dbg "GIT_BRANCH=$GIT_BRANCH HEAD=$GIT_HEAD_SHA"
 fi
 
-# Snapshot current WORKING-MEMORY.md (preserves session context through compaction).
-# The snapshot goes into the backup the next session start injects, so a working
-# memory a symbolic link leads to is treated as absent (D-HOOKS-NO-SYMLINK).
-MEMORY_SNAPSHOT=""
-if df_file_below "$PROJECT_ROOT" "$MEMORY_DIR/WORKING-MEMORY.md"; then
-  MEMORY_SNAPSHOT=$(head -c 65536 "$MEMORY_DIR/WORKING-MEMORY.md")
-  dbg "MEMORY_SNAPSHOT_LENGTH=${#MEMORY_SNAPSHOT}"
-fi
-
 # Write backup JSON
 # D-BACKUP-RENAME: the backup is written whole into a copy beside it, then
 # renamed over it; it is never truncated and refilled in place. Reason:
-# session-start-memory reads it twice, and a read landing between a truncate
-# and the write that refills it would meet a partial file; a rename hands every
-# read either the previous backup or the new one. SEC-2: the copy is created
+# a read landing between a truncate and the write that refills it would meet a
+# partial file; a rename hands every read either the previous backup or the new
+# one. SEC-2: 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. The rename gives the
-# backup the copy's inode and mode, so the backup, which holds the working
-# memory, is 0600 whatever the caller's umask (as in queue-append). A write or
+# backup the copy's inode and mode, so the Git-state backup is 0600 whatever
+# the caller's umask (as in queue-append). A write or
 # rename that fails removes whatever holds the copy's name and keeps the
 # previous backup; the bootstrap below still runs.
 #
@@ -157,7 +159,6 @@ elif [ ! -e "$BACKUP_TMP" ] && [ ! -L "$BACKUP_TMP" ] && (umask 077 && set -o no
     --arg status "$GIT_STATUS" \
     --arg log "$GIT_LOG" \
     --arg diff "$GIT_DIFF_STAT" \
-    --arg memory "$MEMORY_SNAPSHOT" \
     > "$BACKUP_TMP") && mv "$BACKUP_TMP" "$BACKUP_FILE"; then
   log "Wrote backup: $BACKUP_FILE"
   dbg "Wrote backup: $BACKUP_FILE"