headlesscode 1.0.2

package/src/permissions/config.ts

@@ -0,0 +1,241 @@
+/**
+ * Command allow/deny + protected-file permissions configuration for the
+ * headless harness.
+ *
+ * Resolution precedence (mirrors the flag/env/file convention established for
+ * the per-session budget in src/budget/cost.ts and src/cli.ts):
+ *
+ *   CLI flags > env vars > central permissions.json > built-in defaults
+ *
+ * - CLI flags:  `--allowed-commands` / `--denied-commands` / `--protected-files`
+ *               / `--allow-protected-writes` (see src/cli.ts parseArgs)
+ * - env vars:   `HEADLESSCODE_ALLOWED_COMMANDS` / `HEADLESSCODE_DENIED_COMMANDS`
+ *               / `HEADLESSCODE_PROTECTED_FILES` /
+ *               `HEADLESSCODE_ALLOW_PROTECTED_WRITES`
+ * - config file: the CENTRAL project store's `permissions.json`
+ *               (`~/.local/share/headlesscode/projects/<key>/permissions.json` —
+ *               see src/project-store.ts; keyed by the repo's git-common-dir, so
+ *               worktrees share one policy with zero per-directory setup),
+ *               auto-loaded when present (no flag needed). Schema:
+ *               `{ "allowedCommands": string[], "deniedCommands": string[],
+ *               "protectedFiles": string[], "allowProtectedWrites": boolean }`.
+ *               A malformed file fails loudly — mirroring how
+ *               `HEADLESSCODE_PRICING_JSON` is treated in src/budget/cost.ts —
+ *               never silently weakens a policy.
+ *
+ * Deliberate defaults (documented in plans/permissions-parity.md):
+ * - `allowedCommands` defaults to `[]`, which the command decision layer
+ *   (src/permissions/commands.ts) treats as "allow everything except the
+ *   deny-list" — default-ALLOW, backward compatible with the pre-permissions
+ *   harness. `deniedCommands` always applies even then.
+ * - `protectedFiles` defaults to `DEFAULT_PROTECTED_FILES` (secret/credential
+ *   file patterns) — an unattended agent must not silently overwrite .env /
+ *   keys / PEMs. Unlike command allow/deny, leaving this OFF by default would
+ *   be unsafe.
+ * - `allowProtectedWrites` defaults to `false` (an explicit escape hatch only).
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { resolveProjectDataDir } from "../project-store.js"
+import { DEFAULT_PROTECTED_FILES } from "./protected-files.js"
+
+/**
+ * Fully resolved permissions for one session / executor. Everything is
+ * concrete — no `undefined` fields — so enforcement code never has to guess.
+ */
+export interface PermissionsConfig {
+	/** Command prefixes that may run (empty = default-ALLOW; see commands.ts). */
+	allowedCommands: string[]
+	/** Command prefixes that may NEVER run (deny wins over allow). */
+	deniedCommands: string[]
+	/** Glob patterns of files that may not be written (see protected-files.ts). */
+	protectedFiles: string[]
+	/** Escape hatch: when true, the protected-files check is bypassed. */
+	allowProtectedWrites: boolean
+}
+
+/**
+ * Raw (pre-resolution) overrides. Lists arrive as comma-separated strings —
+ * the same shape the CLI flags and env vars carry, so callers don't need to
+ * pre-split. `null`/absent means "no override at this layer".
+ */
+export interface PermissionsOverrides {
+	allowedCommands?: string | null
+	deniedCommands?: string | null
+	protectedFiles?: string | null
+	allowProtectedWrites?: boolean | null
+}
+
+/** The auto-loaded per-repo config file (schema above). */
+export interface PermissionsFile {
+	allowedCommands?: string[]
+	deniedCommands?: string[]
+	protectedFiles?: string[]
+	allowProtectedWrites?: boolean
+}
+
+/** Config file basename inside the central project data dir. */
+export const PERMISSIONS_CONFIG_FILE = "permissions.json"
+
+/** Absolute path of the central permissions.json for a workspace root. */
+export function permissionsFilePath(workspaceRoot: string): string {
+	return path.join(resolveProjectDataDir(workspaceRoot), PERMISSIONS_CONFIG_FILE)
+}
+
+/** Split a comma-separated list (CLI flag / env var) into trimmed entries. */
+export function parseCommaSeparated(raw: string | undefined): string[] | undefined {
+	if (raw === undefined || raw === null) {
+		return undefined
+	}
+	const entries = raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0)
+	return entries.length > 0 ? entries : undefined
+}
+
+/**
+ * Validate an already-parsed permissions-file body (an object of
+ * {allowedCommands?, deniedCommands?, protectedFiles?, allowProtectedWrites?})
+ * and return the normalized `PermissionsFile`. Throws on malformed input —
+ * a broken policy must fail loudly, never silently fall back to weaker
+ * defaults. The file path is only used in error messages.
+ *
+ * Shared by BOTH the file loader below and the dashboard settings POST, so
+ * the HTTP save path can never drift from what the CLI/env path enforces.
+ */
+export function parsePermissionsFileBody(parsed: unknown, source: string): PermissionsFile {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(
+			`permissions: '${source}' must be a JSON object of {allowedCommands, deniedCommands, protectedFiles, allowProtectedWrites}`,
+		)
+	}
+
+	const out: PermissionsFile = {}
+	const obj = parsed as Record<string, unknown>
+
+	for (const key of ["allowedCommands", "deniedCommands", "protectedFiles"] as const) {
+		const value = obj[key]
+		if (value === undefined) {
+			continue
+		}
+		if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+			throw new Error(`permissions: '${source}' field '${key}' must be an array of strings`)
+		}
+		out[key] = value as string[]
+	}
+
+	const allowProtectedWrites = obj.allowProtectedWrites
+	if (allowProtectedWrites !== undefined) {
+		if (typeof allowProtectedWrites !== "boolean") {
+			throw new Error(`permissions: '${source}' field 'allowProtectedWrites' must be a boolean`)
+		}
+		out.allowProtectedWrites = allowProtectedWrites
+	}
+
+	return out
+}
+
+/**
+ * Load the central `permissions.json` for a workspace when present.
+ * Returns `null` when the file does not exist (the common case). A
+ * present-but-malformed file throws — a broken policy must fail loudly, never
+ * silently fall back to weaker defaults. Falls back to the legacy
+ * `<workspaceRoot>/.headlesscode/permissions.json` only when the central file
+ * is absent AND the legacy one still exists (pre-migration grace — the
+ * migration in resolveProjectDataDir normally moves it before this is reached).
+ */
+export function loadPermissionsFile(workspaceRoot: string): PermissionsFile | null {
+	const filePath = permissionsFilePath(workspaceRoot)
+	let raw: string
+	try {
+		raw = fs.readFileSync(filePath, "utf-8")
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+			const legacy = path.resolve(workspaceRoot, ".headlesscode", PERMISSIONS_CONFIG_FILE)
+			try {
+				raw = fs.readFileSync(legacy, "utf-8")
+			} catch {
+				return null
+			}
+		} else {
+			throw new Error(
+				`permissions: cannot read permissions file '${filePath}': ${err instanceof Error ? err.message : String(err)}`,
+			)
+		}
+	}
+
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch (err) {
+		throw new Error(
+			`permissions: invalid JSON in '${filePath}': ${err instanceof Error ? err.message : String(err)}`,
+		)
+	}
+
+	return parsePermissionsFileBody(parsed, filePath)
+}
+
+/** Parse a truthy env flag ("1"/"true"/"yes"); undefined when unset. */
+function envBoolean(name: string, env: NodeJS.ProcessEnv): boolean | undefined {
+	const raw = env[name]
+	if (raw === undefined || raw === "") {
+		return undefined
+	}
+	return raw === "1" || raw.toLowerCase() === "true" || raw.toLowerCase() === "yes"
+}
+
+/**
+ * Resolve the effective permissions for a session:
+ * CLI-flag overrides > env vars > permissions.json > built-in defaults.
+ *
+ * `workspaceRoot` is required so the auto-loaded `<workspaceRoot>/.headlesscode/
+ * permissions.json` policy can participate. Callers that have no CLI flags (the
+ * reviewer/QA executors, which resolve at executor-construction time) simply
+ * omit `overrides` — env + config file + defaults still apply.
+ */
+export function resolvePermissions(options: {
+	workspaceRoot: string
+	overrides?: PermissionsOverrides
+	env?: NodeJS.ProcessEnv
+}): PermissionsConfig {
+	const { workspaceRoot, overrides = {}, env = process.env } = options
+	const file = loadPermissionsFile(workspaceRoot)
+
+	const allowedCommands =
+		parseCommaSeparated(overrides.allowedCommands ?? undefined) ??
+		parseCommaSeparated(env.HEADLESSCODE_ALLOWED_COMMANDS) ??
+		file?.allowedCommands ??
+		[]
+
+	const deniedCommands =
+		parseCommaSeparated(overrides.deniedCommands ?? undefined) ??
+		parseCommaSeparated(env.HEADLESSCODE_DENIED_COMMANDS) ??
+		file?.deniedCommands ??
+		[]
+
+	const protectedFiles =
+		parseCommaSeparated(overrides.protectedFiles ?? undefined) ??
+		parseCommaSeparated(env.HEADLESSCODE_PROTECTED_FILES) ??
+		file?.protectedFiles ??
+		[...DEFAULT_PROTECTED_FILES]
+
+	// The escape hatch has no env-var requirement upstream, but honoring an
+	// env var keeps it usable for unattended workers (run-worker.sh sets
+	// policy via env). Precedence is the same chain.
+	const allowProtectedWrites =
+		overrides.allowProtectedWrites ??
+		envBoolean("HEADLESSCODE_ALLOW_PROTECTED_WRITES", env) ??
+		file?.allowProtectedWrites ??
+		false
+
+	return { allowedCommands, deniedCommands, protectedFiles, allowProtectedWrites }
+}
+
+/** Pretty-printed canonical serialization for the settings file. */
+export function stringifyPermissionsFile(file: PermissionsFile): string {
+	return JSON.stringify(file, null, 2) + "\n"
+}

package/src/permissions/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Permissions module — command allow/deny + protected-file enforcement config
+ * and matching for the headless harness.
+ *
+ * - `config.ts`         — resolution precedence (CLI flags > env > .headlesscode/permissions.json > defaults)
+ * - `commands.ts`       — parseCommand + containsDangerousSubstitution + allow/deny decisions (ported from Zoo Code)
+ * - `protected-files.ts`— default protected patterns + glob matching
+ */
+
+export * from "./config.js"
+export * from "./commands.js"
+export * from "./protected-files.js"

package/src/permissions/protected-files.ts

@@ -0,0 +1,96 @@
+/**
+ * Protected-file glob matching for the headless harness.
+ *
+ * A write to any path matching the resolved protected-files list is refused
+ * (unless the `--allow-protected-writes` escape hatch is on). Simple glob
+ * matching, implemented in-repo — the vendored checkpoint excludes.ts
+ * (src/vendor/zoo-code/src/services/checkpoints/excludes.ts) only *builds*
+ * pattern lists that shadow-git feeds to git itself (via `git config
+ * core.excludesFile`-style config), it has no reusable TS matcher, and there
+ * is no glob/minimatch/picomatch dependency in this repo or node_modules.
+ *
+ * Matching semantics (deliberate, documented):
+ * - Paths are normalized to POSIX separators and matched against their path
+ *   relative to the workspace root.
+ * - A pattern WITHOUT a slash matches the BASENAME at any depth — so `.env`
+ *   matches `subdir/.env`, `*.key` matches `a/b/secret.key`, `id_rsa*`
+ *   matches `config/id_rsa_backup`. This is the behavior the plan requires
+ *   ("a bare filename pattern like `.env` should match `.env` at any depth").
+ * - A pattern WITH a slash is anchored to the workspace root (gitignore-style)
+ *   and matches the full relative path — `config/credentials.key` matches
+ *   `config/credentials.key` but not `other/config/credentials.key`.
+ * - A pattern ending in `/` protects a directory and everything under it.
+ * - `*` matches within one path segment (`[^/]*`), `**` matches across
+ *   segments (`.*`), `?` matches one non-`/` character. Matching is
+ *   case-sensitive (Linux glob convention).
+ */
+
+/** Built-in protected-file default: secrets/credentials an unattended agent
+ * must never silently overwrite. Adjust/extend via config, but ship a real
+ * default. */
+export const DEFAULT_PROTECTED_FILES: string[] = [".env", ".env.*", "*.pem", "*.key", "id_rsa*"]
+
+/** Escape regex metacharacters except the glob wildcards we handle ourselves. */
+function escapeRegExp(ch: string): string {
+	return "\\^$.[]{}()|+".includes(ch) ? `\\${ch}` : ch
+}
+
+/** Convert `*`/`**`/`?` glob wildcards to a regex source (segment-aware). */
+function globSource(pattern: string): string {
+	let out = ""
+	for (let i = 0; i < pattern.length; i++) {
+		const ch = pattern[i]
+		if (ch === "*") {
+			if (pattern[i + 1] === "*") {
+				out += ".*"
+				i++
+			} else {
+				out += "[^/]*"
+			}
+		} else if (ch === "?") {
+			out += "[^/]"
+		} else {
+			out += escapeRegExp(ch)
+		}
+	}
+	return out
+}
+
+/** Compile one protected-files pattern to a RegExp (see module header). */
+export function patternToRegExp(pattern: string): RegExp {
+	// Directory pattern: "secrets/" protects the dir and everything under it.
+	if (pattern.endsWith("/")) {
+		const dir = globSource(pattern.slice(0, -1))
+		return new RegExp(`^${dir}(?:/.*)?$`)
+	}
+	// Anchored always. No-slash patterns are matched against the basename
+	// (findMatchingPattern picks the basename candidate), slash patterns against
+	// the full workspace-relative path — but both are full matches, never
+	// substring matches (so `.env` matches `.env` but not `.envs` or `.env.local`).
+	return new RegExp(`^${globSource(pattern)}$`)
+}
+
+/**
+ * Return the first pattern in `patternList` that matches `relPath`, or `null`.
+ * `relPath` is the workspace-relative path (POSIX separators preferred; `\`
+ * is normalized).
+ */
+export function findMatchingPattern(relPath: string, patternList: string[]): string | null {
+	const normalized = relPath.replace(/\\/g, "/")
+	for (const pattern of patternList) {
+		if (pattern === "") {
+			continue
+		}
+		const hasSlash = pattern.includes("/")
+		const candidate = hasSlash ? normalized : normalized.split("/").pop() ?? ""
+		if (candidate !== "" && patternToRegExp(pattern).test(candidate)) {
+			return pattern
+		}
+	}
+	return null
+}
+
+/** True when `relPath` matches any of the protected patterns. */
+export function isProtectedPath(relPath: string, patternList: string[]): boolean {
+	return findMatchingPattern(relPath, patternList) !== null
+}

package/src/permissions/store-protection.ts

@@ -0,0 +1,272 @@
+/**
+ * Default-on protection for the shared central data store against destructive
+ * commands run through the `execute_command` TOOL.
+ *
+ * Background (plans/protect-shared-store-from-destructive-commands.md): a
+ * worker deleted the real `~/.local/share/headlesscode` with `rm -rf` as an
+ * ad-hoc verification step — three separate times. The command allow/deny
+ * system is deliberately opt-in (`permissions.json` / flags / env), so a
+ * session that configures nothing has ZERO default protection. The central
+ * store (src/project-store.ts) is a categorically different resource: it is
+ * SHARED across every project on the machine, so a single misbehaving
+ * workspace must not be able to destroy it. This check is therefore
+ * always-applied (even with an empty `deniedCommands` list) and NOT
+ * overridable by per-workspace permissions config — a config file a worker
+ * could write must never authorize deleting the shared store.
+ *
+ * Honest scope: this is PATTERN-BASED detection, not a hermetic sandbox. It
+ * catches recursive `rm` invocations (`rm -rf`, `rm -r`, `rm -fr`, `-R`,
+ * `--recursive`, in any flag order/bundle) whose resolved target is the store
+ * root, a PARENT of it, or a DESCENDANT of it (`rm -rf <store>/<subdir>`). It
+ * also follows symlinks when resolving the target (via `fs.realpathSync`,
+ * falling back to the lexical path when the target doesn't exist yet — e.g.
+ * `ln -s <store> /tmp/x && rm -rf /tmp/x` resolves through the symlink). It
+ * deliberately does NOT try to enumerate every way to destroy a file — a
+ * script, `python -c "shutil.rmtree(...)"`, `find ... -delete`, `command rm`,
+ * `sudo rm`, or a non-recursive `rm` of a single file inside the store are all
+ * out of scope for this version. It is a speed bump against the exact class
+ * of mistake that already happened, not a proof of safety. See SEC-5/SEC-6 in
+ * SECURITY.md for the full honest-scope writeup, including the residual
+ * cd-chain caveat (only a leading `cd <dir> &&` prefix chain updates the
+ * effective cwd used for later sub-commands; `cd` inside a subshell, via a
+ * variable, or via `pushd` is not tracked).
+ *
+ * Matching rule (per the plan): a command's target is refused when the
+ * RESOLVED path equals the store root, is an ancestor of it, or is a
+ * descendant of it. Resolution handles `~` / `~/`, `$VAR` / `${VAR}` env
+ * expansion, quoting, symlink following, and relative-vs-absolute paths
+ * (relative targets anchor on the command's working directory — the executor
+ * passes the resolved `cwd`, and `checkCommand` additionally tracks a leading
+ * `cd` chain across `&&`-joined sub-commands). A trailing `/*` glob is treated
+ * as the directory itself (the "delete the contents" idiom targets the same
+ * resource).
+ */
+
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+import { projectStoreRoot } from "../project-store.js"
+
+/**
+ * Split a command string into shell argv words, honoring single quotes, double
+ * quotes and backslash escapes. `~` and `$VAR`/`${VAR}` are KEPT verbatim in
+ * the words so the path expander can process them (quote stripping only).
+ * Deliberately a minimal approximation of shell word splitting — good enough
+ * for the pattern this module detects, not a general shell parser.
+ */
+export function splitCommandWords(command: string): string[] {
+	const words: string[] = []
+	let current = ""
+	let inWord = false
+	let i = 0
+	while (i < command.length) {
+		const ch = command[i]
+		if (ch === "'") {
+			inWord = true
+			i++
+			while (i < command.length && command[i] !== "'") {
+				current += command[i++]
+			}
+			i++ // closing quote
+		} else if (ch === '"') {
+			inWord = true
+			i++
+			while (i < command.length && command[i] !== '"') {
+				if (command[i] === "\\" && i + 1 < command.length && '\\"$`'.includes(command[i + 1])) {
+					current += command[i + 1]
+					i += 2
+				} else {
+					current += command[i++]
+				}
+			}
+			i++ // closing quote
+		} else if (ch === "\\") {
+			inWord = true
+			if (i + 1 < command.length) {
+				current += command[i + 1]
+				i += 2
+			} else {
+				i++
+			}
+		} else if (/\s/.test(ch)) {
+			if (inWord) {
+				words.push(current)
+				current = ""
+				inWord = false
+			}
+			i++
+		} else {
+			inWord = true
+			current += ch
+			i++
+		}
+	}
+	if (inWord) {
+		words.push(current)
+	}
+	return words
+}
+
+/**
+ * True when `words` describe a recursive `rm`: the program is `rm` and any
+ * option is `-r`/`-R` (in any short-flag bundle, e.g. `-rf`, `-fr`, `-Rf`) or
+ * the long `--recursive`. Flags are scanned across ALL words (GNU rm permutes
+ * options and operands), stopping at a literal `--`. Case-insensitive for the
+ * short flag (POSIX `-R` is the traditional spelling).
+ */
+export function isRecursiveDelete(words: string[]): boolean {
+	if (words.length === 0 || path.basename(words[0]) !== "rm") {
+		return false
+	}
+	for (let i = 1; i < words.length; i++) {
+		const w = words[i]
+		if (w === "--") {
+			break
+		}
+		if (w === "--recursive") {
+			return true
+		}
+		if (w.startsWith("-") && w.length > 1 && !w.startsWith("--")) {
+			// Short-flag bundle: -r, -rf, -fr, -Rf, -rfi, ...
+			if (w.slice(1).toLowerCase().includes("r")) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+/**
+ * The operand (path) words of a recursive `rm`: every word that is not an
+ * option, honoring a `--` end-of-options marker (everything after `--` is an
+ * operand even if it starts with `-`).
+ */
+export function deleteTargets(words: string[]): string[] {
+	const targets: string[] = []
+	let afterDoubleDash = false
+	for (let i = 1; i < words.length; i++) {
+		const w = words[i]
+		if (afterDoubleDash) {
+			targets.push(w)
+			continue
+		}
+		if (w === "--") {
+			afterDoubleDash = true
+			continue
+		}
+		if (w.startsWith("-") && w.length > 1) {
+			continue // option bundle / long option
+		}
+		targets.push(w)
+	}
+	return targets
+}
+
+/** Expand a leading `~` / `~/` to the home directory. `~user` forms are left
+ * alone (they are not expanded by this module — vanishingly rare in the
+ * command class under guard, and resolving them needs a passwd lookup). */
+export function expandHome(p: string): string {
+	if (p === "~") {
+		return os.homedir()
+	}
+	if (p.startsWith("~/")) {
+		return path.join(os.homedir(), p.slice(2))
+	}
+	return p
+}
+
+/** Expand `$VAR` and `${VAR}` from `env` (default: process.env). An unset
+ * variable stays literal (the shell would turn it into an empty word, but
+ * keeping it literal errs toward refusing — safe direction). */
+export function expandEnv(p: string, env: NodeJS.ProcessEnv = process.env): string {
+	return p
+		.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (m, name: string) => env[name] ?? m)
+		.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (m, name: string) => env[name] ?? m)
+}
+
+/**
+ * Resolve a raw target word to an absolute path: env expansion, `~`
+ * expansion, then `path.resolve` against the command's working directory
+ * (relative targets anchor there). A trailing `/*` glob is dropped — deleting
+ * "the store's contents" via `rm -rf <store>/*` targets the store itself.
+ */
+export function resolveCommandTarget(target: string, workspaceRoot: string): string {
+	let expanded = expandEnv(expandHome(target))
+	if (expanded.endsWith("/*")) {
+		expanded = expanded.slice(0, -2)
+	}
+	return path.resolve(workspaceRoot, expanded)
+}
+
+/**
+ * Best-effort symlink resolution: `fs.realpathSync` when the path exists,
+ * otherwise the lexical path unchanged (a not-yet-existing target can't be
+ * resolved through a symlink, and that's fine — a `rm -rf` of a nonexistent
+ * path is a no-op anyway). Never throws.
+ */
+function tryRealpath(p: string): string {
+	try {
+		return fs.realpathSync(p)
+	} catch {
+		return p
+	}
+}
+
+/**
+ * True when the resolved `target` is the central store root, an ancestor of
+ * it, or a DESCENDANT of it. Checked both lexically (path.resolve) and
+ * against the symlink-resolved realpath — the same convention
+ * `resolveWithinWorkspace` documents for the harness's own path safety, plus
+ * realpath so `ln -s <store> /tmp/x && rm -rf /tmp/x` is caught too. The
+ * store root comes from project-store.ts's own resolver (projectStoreRoot),
+ * never a second copy of that path logic.
+ */
+export function isCentralStoreOrParent(target: string): boolean {
+	const storeRoot = projectStoreRoot()
+	const candidates = new Set([path.resolve(target), tryRealpath(path.resolve(target))])
+	for (const t of candidates) {
+		if (t === storeRoot) {
+			return true
+		}
+		// Ancestor: storeRoot is inside t.
+		if (storeRoot.startsWith(t.endsWith(path.sep) ? t : t + path.sep)) {
+			return true
+		}
+		// Descendant: t is inside storeRoot.
+		if (t.startsWith(storeRoot.endsWith(path.sep) ? storeRoot : storeRoot + path.sep)) {
+			return true
+		}
+	}
+	return false
+}
+
+/** What a refused destructive command hit, for the model-facing message. */
+export interface StoreDestructionRefusal {
+	/** The resolved absolute target that matched (store root or an ancestor). */
+	target: string
+	/** The protected central store root (projectStoreRoot()). */
+	storeRoot: string
+}
+
+/**
+ * Check ONE sub-command (already split by parseCommand) for a recursive
+ * delete targeting the central store or a parent of it. Returns a refusal
+ * descriptor when it must be blocked, or `null` when it is not a
+ * store-targeting destructive command. `workspaceRoot` anchors relative
+ * targets (defaults to process.cwd()).
+ */
+export function checkCentralStoreDestruction(subCommand: string, workspaceRoot?: string): StoreDestructionRefusal | null {
+	const words = splitCommandWords(subCommand)
+	if (!isRecursiveDelete(words)) {
+		return null
+	}
+	const root = path.resolve(workspaceRoot ?? process.cwd())
+	for (const target of deleteTargets(words)) {
+		const resolved = resolveCommandTarget(target, root)
+		if (isCentralStoreOrParent(resolved)) {
+			return { target: resolved, storeRoot: projectStoreRoot() }
+		}
+	}
+	return null
+}